Introduction

To use SURFconext Strong Authentication for authentication with your service your service must use the SAML 2.0 protocol. Your service is a SAML service provider (SP) and the SURFconext Strong Authentication gateway will be your SAML identity provider (IdP). Connecting your SP to the SURFconext Strong Authentication gateway is technically very similar to connecting to SURFconext. In a nutshell:

Use the Interoperable SAML 2.0 Web Browser SSO Deployment Profile;
which is a specialization of the SAML V2.0 Web Browser SSO Profile (pdf);

The core standard on which the profiles build is described in Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0 (pdf). We do not recommend you write your own implementation of the SAML protocol. Instead use one of the many available libraries and products. Feel free to contact us to ask for suggestions.

If you are new to SAML you may want to read the SAML V2.0 Executive Overview (pdf). Because of the strong similarities between the SURFconext gateway and the Strong Authentication gateway most of the technical documentation for SURFconext SPs applies, but there are differences between the SURFconext Strong Authentication gateway and SURFconext regarding:

the SAML metadata of the SURFconext String Authentication gateway;
some optional features supported by SURFconext Strong Authentication that are reflected in the SAML protocol messages
differences in the supported SAML features
differences in SURFconext features that are available when authenticating through SURFconext Strong Authentication gateway

These differences are described in more detail in: Differences between the SURFconext and SURFconext Strong Authentication gateway. When a service provider (SP) is already connected to SURFconext, connecting it to use the Strong Authentication gateway should require minimal changes on the part of the SP. The SURFconext Strong Authentication gateway replaces the regular SURFconext gateway. From the perspective of a SP, authentication is still one SAML authentication request to a SAML IdP (the SURFconext Strong Authentication gateway) which results in one SAML response.

When the SP needs different authentications strengths e.g. low strength for a student accessing their own grades, high strength for staff entering student grades, more work may be involved. In that case the SP needs to communicate the required authentication strength the to SURFconext Strong Authentication gateway, and must verify the actual strength at which a user was authenticated. Both are expressed in the SAML request and response messages that are already being exchanged between the SP and the SURFconext Strong Authentication IdP, so no additional SAML exchanges or exchanges in other protocols are required.

SURFconext Strong Authentication gateway architecture

The picture below shows how the SURFconext Strong Authentication gateway, SURFconext, your SP and 2nd factors used for strong authentication (SMS, Tiqr and YubiKey) are related. Notice that:

For IdPs there are no technical changes required to their IdPs. They still connect to the SURFconext gateway
SPs connect the the SURFconext Strong Authentication gateway. No connection with SURFconext or integration with 2nd factor authentication devices is required.

SURFconext Strong Authentication authentication flow

The picture below shows the authentication flow of a SP using the SURFconext Strong Authentication gateway.

The SP sends a SAML 2.0 AuthnRequest to the SURFconext Strong Authentication gateway. The SP may use a RequestedAuthnConext to specify the minimal LoA at which a user must be authenticated.
The SURFconext Strong Authentication gateway sends a AuthN request to SURFconext. SURFconext takes care of the authentication of the user at their home IdP and applies policies: attribute release, generatioj of persistent identifiers, user consent and institutional consent.
The SURFconext Strong Authentication gateway receives a response from SURFconext with the identity and attributes of the user.
The SURFconext Strong Authentication gateway determines whether authentication at a higher LoA (see below) is required and, when required, sends the user to the authentication provider for their 2nd factor.
The response from the 2nf factor authentication provider is returned to the SURFconext Strong Authentication gateway.
The SURFconext Strong Authentication gateway sends a SAML Response with Assertion and the attributes and the identity of the user to the SP.

Note that it is the SP that chooses where to send the AuthN request (i.e. SP initiated authentication).

Strong Authentication

For expressing the "strength" of the authentication and the identity of the user a assurance framework as described in ISO/IEC 29115 is used (similar to NIST Special Publication 800-63-1). The SURFconext Strong Authentication gateway will Support 3 levels of assurance (LoA):

LoA 1 : Password authentication through SURFconext at the user's home IdP
LoA 2 : LoA 1 + SMS authentication or Tiqr authentication
LoA 3 : LoA 1 + Yubikey (hardware token) authentication

See Using Levels of Assurance to express strength of authentication for more information.

How to determine at which LoA a user must be authenticated?

Three different scenarios are supported:

An IdP wants to enforce that its users are authenticated at a certain minimum LoA for a specific SP.
A SP always wants to have a certain minimum LoA
A SP wants to be able to request a higher LoA for a user under control of the SP. E.g. only when the user accesses the "admin" part of the site.

The first two scenarios are implemented by adding a static policy on the SURFconext Strong Authentication gateway. Because at the time of the authentication the gateway knows both the IdP and the SP involved it can determine the minimum LoA required for the authentication. In third scenario the SP dynamically specifies a minimum LoA during authentication.

The three scenarios can be combined. For a specific IdP-SP combination:

The IdP can have specied a minimum LoA (static)
The SP can have specied a minimum LoA (static)
The SP can request a LoA during authentication (dynamic)

When more then one scenario applies the gateway uses the scenario that results in the highest LoA.

Requesting a static LoA for an SP as SP

When connecting a service to the SA gateway, a Service provider can specify the minimum LoA that it want to be applied to all authentications from that SP. SURFnet will then configure this LoA requirement on the SA gateway. The actual LoA at which a user was authenticated is always reflected in the SAML authentication message that is send to the SP, thus the SP can always be aware of the LoA of a user's authentication.

Requesting a static LoA for an SP as IdP

An IdP can request a minimum LoA to be applied for all authentications to a specific SP. An IdP can contact SURFnet to make this change. SURFnet will then configure this LoA requirement on the SA gateway. For this to work the SP must first be connected to the SA gateway, and use the SA gateway for authentication.

Requesting authentication at a specific LoA as SP

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.

For more information see: SAML message examples and Differences between the SURFconext and SURFconext Strong Authentication gateway

Handing Authentication failure

There are two main reasons for when authentication may fail:

The user cannot authenticate at the requested LoA level because he does not have a suitable 2nd factor
The user cancels authentication during verification of the second factor

In both these cases the SURFconext Strong Authentication gateway sends a SAML Response back to the SP indicating failure. The SP should be ready to handle these responses.