Authentication context classes in the SAML IDP

A SAML authentication context class describes a level of assurance or authentication method used in a SAML sign-on process.

SAML authentication context classes are used on the SAML IDP in two different ways:

  • In SAML assertions: to tell the service providers (SPs) how the user was authenticated.>>
  • In SAML AuthnRequests: to ask the IDP to authenticate the user in a specific way.

How to use and configure the two usage types is described in the following.

Authentication context classes in SAML assertions

To let the SAML SP know how the user was authenticated, an authentication context class is included in the SAML assertion. Authentication context classes are strings defined in the SAML specification (see list further below).

To configure Airlock IAM to include the desired authentication context in SAML assertions, do the following:

  1. Include all authentication context classes that may possibly be included in the SAML assertion in the extended IDP metadata file (idp-extended.xml) - see SAML IDP configuration for the Loginapp REST API. The first in the list is used if no information is available which to select.
  2. In the IAM configuration (Config Editor), go to:
    Loginapp >> SAML Settings >> SAML 2.0 Identity Provider
  3. Set property Default Authentication Context to the authentication context class you wish to be included in the SAML assertion if no other authentication context class can be determined based on the mappings. If there is only one authentication method, this is sufficient and you may skip the next step.
  4. In property Authentication Context Mappings, a mapping may be defined. It allows choosing the authentication context class based on an authentication flow condition.
    Example: To choose the authentication context class TimeSyncToken after the user has been authenticated with an OTP code, use a Has Tag condition with a specific Tag (e.g. OTP_VERIFIED) and make sure that the tag is granted in the authentication flow after successful OTP verification.
 
Risk

When using flow conditions to choose authentication context classes, make sure to fully understand the semantics of the conditions. Failing to do so may result in the wrong authentication context class being sent to the SP.

For example, the condition Active Authentication Method (on the value MTAN) or the tag Has mTAN Token do not guarantee that the authentication flow really involved an mTAN token verification.

It is suggested to grant a specific tag for each authentication step (e.g. MTAN_VERIFIED) and test on this using a Has Tag condition.

 
Info

Configuration hint

The flow conditions in property Authentication Context Mappings are processed in the defined order and the first matching mapping is used. Make sure the mapping order is such that the desired mapping is chosen.

Example: Assume that a successfully passed authentication flow always grants the tag PASSWORD_VERIFIED and only in some cases MTAN_VERIFIED. Then, the mapping with the condition on the MTAN_VERIFIED tag must be first and the mapping with the condition on the PASSWORD_VERIFIED second. If placed in the wrong order, the mapping with the PASSWORD_VERIFIED condition would always be selected.

Authentication context classes in SAML AuthnRequests

An authentication context may also be requested by the SP in the AuthnRequest: This is how an SP expresses that it requires a certain authentication context to be in the assertion after authentication.

This may, for example, be used to implement SP-triggered authentication step-up.

Consider the following example scenario:

  • The user is authenticated with a password and accesses the SP remote-sp1 with a SAML assertion bearing the authentication context class urn:oasis:names:tc:SAML:2.0:ac:classes:Password.
  • Because the user tries to access a critical resource, the SP decides to request a stronger authentication scheme from the IDP. To do so, it sends an AuthnRequest bearing the authentication context urn:oasis:names:tc:SAML:2.0:ac:classes:MobileTwoFactorContract to the SAML IDP.
  • The IDP receives the AuthnRequest and asks the user for a 2nd authentication factor (mTAN in this example). Then it sends a new SAML assertion bearing the requested authentication context to the SP.

Airlock IAM supports this scenario by mapping requested authentication context classes to separate application IDs. This mechanism allows the user to go through a specific authentication flow for each requested authentication context.

The above example step-up scenario is configured as follows: The instructions are based on an existing SAML target application with application id remote-sp1-application as described in Adding SAML SPs to the IDP configuration for the Loginapp REST API .

  1. Go to:
    Loginapp >> Applications and Authentication
  2. Add a new Target Application with Application ID remote-sp1-step-up and configure it as follows:
    • Configure an Authentication Flow that extends the authentication flow of the target application remote-sp1-application by a 2nd factor. See Flow-based authentication for more information on step-up flows.
    • Use the same identity SAML 2.0 Identity Propagator plugin as used in target application remote-sp1-application (or create a new SAML 2.0 Identity Propagator also referring to the SP Entity ID sp1).
  4. Go to:
    Loginapp >> SAML Settings >> SAML 2.0 Identity Provider) >> SAML 2.0 Service Provider for entity ID sp1.
  5. Add a new mapping plugin the RequestedAuthnContext to Flow Application ID property and configure it as follows.
  6. In Requested Authentication Context selected the desired requested authentication context class (in our example urn:oasis:names:tc:SAML:2.0:ac:classes:MobileOneFactorContract).
  7. In Flow Application ID select the application ID remote-sp1-step-up.
  8. Open the extended SP metadata file (sp1-extended.xml) and make sure that the authentication context in question is listed in the attribute spAuthncontextClassrefMapping as in the example below. The list specifies all authentication contexts that are allowed to be requested.
 
Example
<Attribute name="spAuthncontextClassrefMapping">
	<Value>urn:oasis:names:tc:SAML:2.0:ac:classes:Password|0|default</Value>
	<Value>urn:oasis:names:tc:SAML:2.0:ac:classes:MobileOneFactorContract|1</Value>
</Attribute>

The syntax is as follows: <classref-name>|<auth-level>[|default]. The one with the default label is chosen by default for the SP.

Note that the authentication context class entries in the extended IDP metadata file are without the auth level and default tag. If copying them to the IDP configuration, remember to remove |0|default, |1, and alike.

  1. The previous steps make sure, that the authentication context sent by the SP is accepted and it defines what flow to start for each authentication context.
    To ensure, that the requested authentication context is included in the assertion after successful authentication, follow the instructions in section Authentication context classes in SAML assertions at the beginning of this article.

SAML Authentication context classes

The SAML specification defines the following authentication context classes. You may use them in the extended IDP metadata file (see SAML IDP configuration for the Loginapp REST API).

urn:oasis:names:tc:SAML:2.0:ac:classes:InternetProtocol

urn:oasis:names:tc:SAML:2.0:ac:classes:InternetProtocolPassword

urn:oasis:names:tc:SAML:2.0:ac:classes:Kerberos

urn:oasis:names:tc:SAML:2.0:ac:classes:MobileOneFactorUnregistered

urn:oasis:names:tc:SAML:2.0:ac:classes:MobileTwoFactorUnregistered

urn:oasis:names:tc:SAML:2.0:ac:classes:MobileOneFactorContract

urn:oasis:names:tc:SAML:2.0:ac:classes:MobileTwoFactorContract

urn:oasis:names:tc:SAML:2.0:ac:classes:Password

urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport

urn:oasis:names:tc:SAML:2.0:ac:classes:PreviousSession

urn:oasis:names:tc:SAML:2.0:ac:classes:X509

urn:oasis:names:tc:SAML:2.0:ac:classes:PGP

urn:oasis:names:tc:SAML:2.0:ac:classes:SPKI

urn:oasis:names:tc:SAML:2.0:ac:classes:XMLDSig

urn:oasis:names:tc:SAML:2.0:ac:classes:Smartcard

urn:oasis:names:tc:SAML:2.0:ac:classes:SmartcardPKI

urn:oasis:names:tc:SAML:2.0:ac:classes:SoftwarePKI

urn:oasis:names:tc:SAML:2.0:ac:classes:Telephony

urn:oasis:names:tc:SAML:2.0:ac:classes:NomadTelephony

urn:oasis:names:tc:SAML:2.0:ac:classes:PersonalTelephony

urn:oasis:names:tc:SAML:2.0:ac:classes:AuthenticatedTelephony

urn:oasis:names:tc:SAML:2.0:ac:classes:SecureRemotePassword

urn:oasis:names:tc:SAML:2.0:ac:classes:TLSClient

urn:oasis:names:tc:SAML:2.0:ac:classes:TimeSyncToken

urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified

For detailed information, refer to OASIS SAML 2.0 Authntication Context Classes (PDF).