Nota bene

Please note that the tagged version in Git does not follow the OIO SAML profile version. The correlation is described below

• OIO SAML 2.0.9: Newest NuGet release: 2.0.6
• OIO SAML 2.1.0: Newest NuGet release: 2.0.6 (only metadata changes required)
• OIO SAML 3.0.2: Newest NuGet release: 3.0.4

See content and changes of releases in release notes.

Getting started with OIOSAML.Net

This is the codebase that the OIOSAML.Net components are built from.

Resource links

• Project maintenance
• Nuget packages (prefixed dk.nita.saml20)
• Code repository

Repository content

• build: Contains script to create and publish NuGet packages
• certificates: Certificates used for getting the demo sample up and running
• setup: Setup scripts used for getting demo sample up and running
• src: source code for the OIOSAML.Net framework
• developer notes.html: Information relevant for developers of OIOSAML.Net
• Net SAML2 Service Provider Framework.docx: General documentation on how to use OIOSAML.Net
• readme.html: This file

Getting started

The source code contains everything you need to get a demonstration environment up and running, federating with your own local Identity Provider, as well as directly against NemLog-in.

The full documentation on the project is available in the document 'Net SAML2 Service Provider Framework.docx'

For a quick setup, you must do the following:

• Run the script 'setup\setup_prerequisites.ps1' from an elevated powershell. This installs all required certificates and performs sslcert bindings to be able to host local websites using https
• Open the solution 'dk.nita.saml20.sln' in Visual Studio 2019 (Elevated mode) and build it (if you get errors on external dependencies, ensure nuget packages are being restored)
• Set the projects 'IdentityProviderDemo' and 'WebsiteDemo' as startup projects by right-clicking solution, select 'properties', selecting 'Multiple start projects'
• For the web projects, you must manually set the 'Start URL' that IIS express uses. You do this by:
  • right click project 'IdentityProviderDemo', select 'properties', select the tab 'Web', alter the 'Start Action' to the radio button 'Start URL', specifying 'https://oiosaml-demoidp.dk:20001'
  • right click project 'WebsiteDemo', select 'properties', select the tab 'Web', alter the 'Start Action' to the radio button 'Start URL', specifying 'https://localhost:20002'
• Run the solution which should start IIS express for the two websites

This should start two browser windows, one for the demo idp ('IdentityProviderDemo'), and one for the service provider ('WebsiteDemo').

On the service provider you should now be able to log in using either the demo idp or NemLog-in, by selecting the identity provider in the list of identity providers:

• If you choose NemLog-in, you must use an certificate employee certificate from the NemLog-In testportal
• If you choose the local demo idp, you log in with a username/password with one of the users listed in the web.config file for the demo idp under the 'demoIdp' section

When the IdP changes its signing certificate

The IdP metadata files are read from the directory set in IDPEndPoints/@metadata. The library watches the directory and reloads it a few seconds after a change, so a new certificate needs no restart:

• The IdP publishes metadata with both certificates. Replace the metadata file with it. Each certificate is in its own KeyDescriptor, and signatures made with either are accepted.
• The new certificate comes in a separate metadata file. Add the new file next to the old one, with the same entityID. The keys of all files with that entityID are trusted, and the newest file gives the endpoints. Delete the old file once the IdP has switched.

An IDPEndPoint configured in Web.config keeps its settings through a reload, even while its metadata file is being replaced. A file that can't be read, for example while it is being copied or is locked, keeps its last version for up to five minutes; after that its keys are no longer trusted and an error is traced. A file that can be read but isn't usable SAML 2.0 metadata with one EntityDescriptor counts as removed straight away. Certificates are still checked by the configured certificate validation (by default chain and revocation), so the new certificate's CA must be trusted on the server.

When the SP changes its certificate

Each SigningCertificate in Federation/SigningCertificates names one certificate in the certificate store, preferably by thumbprint. It is used if it has a private key and is within its validity period. Its chain and revocation are not checked by the SP, but by the IdP that trusts it; the validOnly attribute is ignored. The store is searched again every ten minutes.

Messages are signed with the certificate of the first entry that can be used. Assertions are decrypted with any of them, and the SP metadata lists every certificate found that has not expired, including one that is not yet valid. To change certificate:

1. Install the new certificate and add an entry for it after the current one. Register the SP metadata, which now has both certificates, with the IdP.
2. Once the IdP has the new metadata, move the new entry first.
3. Remove the old entry, then the old certificate.

Logging

The library writes to two trace sources: dk.nita.saml20.auditLogger for the audit log (or the class set in the auditLoggingType attribute of Federation), and dk.nita.saml20 for tracing.

• Audit entries identify SAML messages by element name, ID, InResponseTo, IssueInstant and Issuer, not by their content. The session id is logged as a hash, which correlates the entries of one session. Line breaks in logged values are escaped.
• The SAML messages as received and sent, with assertions still encrypted, are traced at Verbose only. Turn that level on only while troubleshooting.
• Decrypted assertions are never logged.

Session lifetime

A login ends after SessionTimeout minutes without activity (default 30), and in any case MaximumSessionLength minutes after the user authenticated at the IdP (default 480), or earlier if the IdP's SessionNotOnOrAfter says so. Both are elements of the Federation section. NemLog-in's technical requirements for service providers set the limits these defaults follow.

Saml20Identity.IsInitialized() is true only while the session holds a login that has not ended. The Forms ticket issued at login by the default SetSamlPrincipal action is tied to the OIOSAML session and ends no later than the login; if it is presented with another session, IsInitialized() is false. Sign the user out of Forms authentication when IsInitialized() is false, as WebsiteDemo/Global.asax.cs does.