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.
Table of Contents |
---|
Requesting authentication at a specific LoA
A SP can request authentication at a specific LoA by specifying the that LoA in the the AuthnRequest
. Note that an SP can send an an AuthnRequest
to 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 seen as a minimum LoA. The SURFconext Strong Authentication gateway:
...
The SURFsecureID gateway can perform authentication at a higher LoA
...
, in which case the higher level
...
will be expressed in the returned
...
SAML Assertion
.
The requested LoA required by the SP is passed to the SURFconext Strong Authentication gateway in an AuthnContextClassRef
element in a RequestedAuthnContext
element in the SAML the SURFsecureID gateway in an AuthnContextClassRef
element in a RequestedAuthnContext
element in the SAML AuthnRequest
:
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<samlp:RequestedAuthnContext> <saml:AuthnContextClassRef>http://surfconext.nl/assurance/loa2</saml:AuthnContextClassRef> </samlp:RequestedAuthnContext> |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<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 All AuthnRequest messages must be signed be by the SP using SHA-2. The SP must use the The HTTP-REDIRECT
binding binding must be used 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
". authentication fails, it is generally because the user:
- cancels authentication during verification of the second factor or
- does not have a suitable second factor identification.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<samlp <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:StatusMessage>Authentication cancelled by user</samlp:StatusMessage> </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
".
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
<samlp<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> |