SAML Integration Guide

1. What Is SAML 2.0

SAML is a standard that addresses web-browser single sign-on (SSO). SAML 2.0 is an XML-based protocol that uses security tokens containing assertions to pass information about a principal (usually an end-user) between an Identity Provider and a Service Provider.

The SAML flow is shown in the diagram below:

The user via the UserAgent (e.g Browser) tries to access the SP
The SP checks the current authentication session of the user and:
1. If the user still has a valid session provides the user access to the service.
2. If the user does not have a valid session, it will generate a AuthNRequest and redirects the user to the IDP’s SingleSignOnService URL
The IDP checks the AuthNRequest and if valid ask the UserAgent to provide authentication details.
The UserAgent provided the authentication details to the IDP.
The IDP checks the user credentials and if valid generates a SAMLResponse containing a SAML Assertion about the user attributes.
The IDP sends the SAMLResponse (through the UserAgent) to the AssertionConsumerService url of the SP.
The SP validates the SAML Response and assertions and if valid provides the user access to the service.

2. Integration

2.1. Setup

For SAML Integration the Service Provider and the Identity Provider first need to exchange their endpoints and signing-certificates with each other. Usually, this is done by exchanging a SAML Metadata document. The metadata of Audkenni can be downloaded here. An example of the metadata document that a service needs to provide can be downloaded here:

2.2. Request

2.2.1. Providing information about the chained Related Party

In some cases, the Service Provider is also an IDP that received a request from other SPs (Relaying parties) and relies on Audkenni for the actual authentication. This scenario is seen in the picture below.

In this scenario, Audkenni mandates that this information, name of the RelatedPartyParty, is provided in the AuthnRequest as an extension attribute named audkenni:relatedPartyParty, e.g.:

<audkenni:relatedPartyParty xmlns:audkenni="urn:audkenni">Example client</audkenni:relatedPartyParty>

An example full AuthnRequest would then look as follows:

<?xml version="1.0" encoding="UTF-8"?>
<saml2p:AuthnRequest xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol"
                     AssertionConsumerServiceURL="http://localhost:8080/saml/SSO"
                     Destination="https://idp-dev.audkenni.is/sso/SSORedirect/metaAlias/audkenni/idp"
                     ForceAuthn="false"
                     ID="a57h5jf2jdffa5553d58332jc831g7b"
                     IsPassive="false"
                     IssueInstant="2019-11-28T13:27:04.831Z"
                     ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                     Version="2.0">
  <saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">com:audkenni:spring:sp</saml2:Issuer>
  <md:Extensions xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
    <audkenni:relatedPartyParty xmlns:audkenni="urn:audkenni">Example client</audkenni:relatedPartyParty>
  </md:Extensions>
</saml2p:AuthnRequest>

2.2.2. Providing the login message

The message that the user receives during authentication (e.g. on his phone/app/nexus card) can also be provided in the AuthNRequest as an extension attribute named audkenni:signingMessage, e.g.:

<audkenni:signingMessage xmlns:audkenni="urn:audkenni">Login to example client</audkenni:signingMessage>

An example full AuthnRequest would then look as follows:

If no signingMessage is provided, the user will receive the message “Login to Audkenni”.

2.2.3. Influencing the login flow

The login flow the user experiences can be influenced by setting a “RequestedAuthnContext“ in the AuthnRequest. At the moment the following contexts are supported

urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
- In this case, the default login flow would be presented in which the user can choose the authentication method
urn:oasis:names:tc:SAML:2.0:ac:classes:SmartcardPKI
- In this case, only the nexus personal card authentication option is shown
urn:oasis:names:tc:SAML:2.0:ac:classes:MobileOneFactorContract
- In this case, only the Sim card authentication option is shown

An example AuthNRequest where for instance the sim card option is enforced looks like this:

2.3. Response

NameID

The social security number of the user is set as the NameID in the authentication response

attributes

In the SAML Assertion, the following attributes are returned

nationalRegisterId
- The social security number
certificate
- The certificate generated by the authenticator as a result of the user authentication

As a reference, a complete SAML Response looks as follows: