On this page example SAML 2.0 messages are shown to illustrate how the SURFconext Strong Authentication Gateway uses SAML 2.0 to provide its functionality to Service Providers.

Requesting authentication at a specific LoA

A SP can request authentication at a specific LoA by specifying the LoA in the AuthnRequest. Note that an SP can send an AuthnRequest to the gateway at any time, also when a user is already logged in at the SP. This allows an SP to raise the LoA for a user that is using the service depending on the context, for instance the operation performed by the user at the SP.

The requested LoA is interpreted as a minimum LoA. The SURFconext Strong Authentication gateway:

Will not perform authentication below the requested low
May perform authentication at a higher LoA level, in which case the higher level LoA will be expressed in the returned SAML Assertion.

The LoA required by the SP is passed to the SURFconext Strong Authentication gateway in an AuthnContextClassRef element in a RequestedAuthnContext element in the SAML AuthnRequest:

<samlp:RequestedAuthnContext>
    <saml:AuthnContextClassRef>http://surfconext.nl/assurance/loa2</saml:AuthnContextClassRef>
</samlp:RequestedAuthnContext>

<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" 
                    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
                    ID="_ace040cdf97c2efba5aa4d973a32318217b9aaae09"
                    Version="2.0"
                    IssueInstant="2014-05-26T06:47:27Z"
                    Destination="https://sa-gw.surfconext.nl/authentication/single-sign-on"
                    >
    <saml:Issuer>http://test-sp.example.com</saml:Issuer>
    <samlp:RequestedAuthnContext>
        <saml:AuthnContextClassRef>http://surfconext.nl/assurance/loa2</saml:AuthnContextClassRef>
    </samlp:RequestedAuthnContext>
</samlp:AuthnRequest>

Note that all AuthnRequest messages must be signed be the SP using SHA-2. The SP must use the HTTP-REDIRECT binding to submit the request. When using this binding the signature is put in HTTP request parameters, no XML-Signature is used.

Authentication failure

When a user cancels the authentication at the SURFconext Strong Authentication gateway, the SURFconext Strong Authentication gateway sends a SAML Response back to the SP indicating failure. The reason for the failure is given in the StatusCode in the Response. When the requested LoA cannot be fulfilled the second level StatusCode will be "urn:oasis:names:tc:SAML:2.0:status:AuthnFailed".

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
                xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
                ID="_Yasz/Kubip05bTwe7hIWOc5As+NxwmEliPJ88nUQ"
                Version="2.0"
                IssueInstant="2015-05-12T12:17:38Z"
                Destination="https://your-sp.example.com/acs-location"
                InResponseTo="_6d93f735ccfb8d98454999b4016d515834211b0dde"
                >
    <saml:Issuer>https://sa-gw.surfconext.nl/authentication/metadata</saml:Issuer>
    <samlp:Status>
        <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Responder">
			<samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:AuthnFailed" />
		</samlp:StatusCode>
    </samlp:Status>
</samlp:Response>

When the requested LoA cannot be provided by the SURFconext Strong Authentication gateway, for example because the user is not known at the SURFconext Strong Authentication gateway or the requested LoA exceeds the LoA at which the user can be authenticated, the gateway sends a SAML Response back to the SP indicating failure. The reason for the failure is given in the StatusCode in the Response. When the requested LoA cannot be fulfilled the second level StatusCode will be "urn:oasis:names:tc:SAML:2.0:status:NoAuthnContext".

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
                xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
                ID="_Yasz/Kubip05bTwe7hIWOc5As+NxwmEliPJ88nUQ"
                Version="2.0"
                IssueInstant="2015-05-12T12:17:38Z"
                Destination="https://your-sp.example.com/acs-location"
                InResponseTo="_6d93f735ccfb8d98454999b4016d515834211b0dde"
                >
    <saml:Issuer>https://sa-gw.surfconext.nl/authentication/metadata</saml:Issuer>
    <samlp:Status>
        <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Requester">
			<samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:NoAuthnContext" />
		</samlp:StatusCode>
    </samlp:Status>
</samlp:Response>