Introduction

Identify 5.5 step up service pack (staring from build 5.5.1.61) adds the new step-up feature to Identify 5.5. In some situations, an application can have functionalities that need different levels of assurance. For example, an ecommerce website needs level 2 for most functionalities, but it will require level 3 when it comes to updating user account or to checking out. Therefore, the website can generally authenticate users using username and password only, but when they want to access the functionalities that need level 3, the website can send step-up login requests to Identify to ask the users log in again using a level 3 authentication method, e.g. username password and a second factor. This document is not only a release note but is also a user guideline. The screenshots are taken from Identify Admin but the same settings are available on Safewhere Admin.

The main use cases

The two main use cases are:

1. Initially you log in by using a level 2 authentication method, e.g. using username and password. When doing step up, because you have logged in, you only need to perform a second factor.
2. Initially you log in by using a level 2 authentication method, e.g. using username and password. When doing step up, because the previously chosen method doesn’t support level 3, you can choose another authentication provider such as NemId.

Use case 1 calls for the the ability to use MFA only when a request asks for a certain level of assurance (LoA). The setup for it is:

1. An authentication connection is set up with a second factor.
2. The first factor alone has LoA 2, but when the second factor is used, LoA of the whole login is 3.
3. We add a new setting to specify the LoA when the second factor is used: Second factor authentication context method class. The name is a bit misleading though and should have been called “Authentication context method class after second factor is done”. We may update the name in a future version. As a side note, we use “authentication context method class” and “level of assurance” interchangeably in this document.

 

The flow:

1. An SP sends a request to Identify either without LoA or with LoA 2.
2. The user is asked to log in with the first factor but doesn’t need to do the second factor.
3. Identify returns a token to the SP with LoA 2. The LoA is returned inside the AuthnContextClassRef element.
4. After that, the user wants to access a functionality that requires LoA 3, so the SP sends a step-up request to Identify with LoA 3. The requested LoA is specified in AuthnRequest’s RequestedAuthnContext element.
   • Or the user wants to access another application that requires level 3 and is federated with Identify.
5. Identify will authenticate the user again, but this time the user also needs to do the second factor.
   • If the first factor is an upstream IdP such as SAML 2.0 or WSFed, Identify will forward the request to the IdP. If the login session is still valid there, the IdP will automatically return a response to Identify which means the user won’t need to redo the first factor. If the first factor is a Username & Password connection and the login session is still valid, the first factor is skipped too.
   • Even if there are other connections that support level 3, the connection used originally is picked by default.
6. After the user finishes second factor, Identify returns a token with LoA 3 to the SP.

Configure step up on Identify

Define level of assurances

You can go to System Setup -> Authentication context method classes to define necessary LoAs:

The none value, the http://schemas.microsoft.com/claims/multipleauthn value, and the urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport value (actually this one depends on settings on the ADFS side, but this is the default value) are used when you need to do step-up against ADFS. Comparable value for urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport should be set to that of the Authentication Context Method Class setting (see the Configure Identity Provider section below).

Configure Service Provider

By default, Identify doesn’t take the RequestedAuthnContext element into account. You need to setting the following settings as follows:

Configure Identity Provider

You can do the following steps to enable step-up support for Identity Provider connections. Open an authentication connection and:

1. Select a second factor connection:

2. Specify LoA of the first factor, and LoA when the second factor is done:

Note: in this example, the Authentication context method class setting is set to 2. Thus, urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport should be set to 2 too.

3. If the Identity Provider connection is a SAML 2.0 one, you need to tick on:

This setting makes sure Identify will forward the requested LoA to the upstream IdP.

Integration with other systems

Integration with KOMBIT

When Identify acts as Identity Provider of KOMBIT CH, Identify needs to issue LoA via a special assurance level claim. As is, you can issue a static value as follow:

With step-up, because LoA varies depending on requested LoA, you can use:

The AuthenticatedAssuranceLevel returns the real LoA of a login. Note that if your claims somehow already has the AssuranceLevel claim, you need to remove it before adding a new one.

Integration with ADFS

ADFS only supports two levels:

• When no RequestedAuthnContext element is sent, MFA is not triggered.
• When http://schemas.microsoft.com/claims/multipleauthn is sent, MFA is triggered.

Thereforce, you need to map from your standard LoAs to ADFS’ LoAs. The following screenshot assumes that you want to do MFA for LoA 3 and 4:  

Note: when an assurance level is mapped to urn:none, it will not be added to the AuthnRequest sent to upstream IdP.

Edge cases

When a SAML IdP’s authentication context method class has LoA 2 and the second factor setting has LoA 3 but after authenticating the upstream SAML IdP returns assurance level 3, the second factor will be skipped. When a request doesn’t request any LoA (aka the RequestedAuthnContext setting doesn’t exist) and an Identidy Provider doesn’t have the Second factor authentication context method class specified, the second factor will always be triggered. In fact, this is the current behaviour when step up is not set up.

What does not work (yet)

Currently, step up does not work with WSFederation application connection. The reason is that WSFederation can use both SamlAssertion and Saml2Assertion and we need to specifically write code to support them for the WSFederation plugin.

Step up also does not work with OAuth2.0/OIDC application connection.

Due to time constraint, we weren’t able to cover these plugins.

Extra scopes

When a Service Provider sends scoping with RequesterId to Identify, we expose the scoping value to Claims Transformation pipeline so that claims transformations can have access to it. E.g., an external BPP CT can use the scoping value to decide what roles it should issue via an BPP claim. External components will use this helper code found at https://github.com/Safewhere/Safewhere-Identify-samples/blob/master/Extensible%20Identify/ExternalSamples/PassiveContextService.cs to retrieve the requesterId value.