Step-up authentication

Step-up-authentication is a mechanism that OIDC and SAML clients use to require a stronger authentication level, based on a security policy that the client defines.

Step-up authentication example

For example, if you want to build a web application that allows users who are authenticated with a first factor, such as username and password or a remote IDP (such as Facebook or Google), to view information about their account. When they want to update their profile, you want to provide extra security and challenge the user to authenticate with an additional factor, such as a push notification or an OTP.

This example can be translated to the following steps:

1. The user logs in with their username and password.
2. The user is redirected to a profile page where information about their account is available, such as phone number and email address.
3. The user clicks change email address.
4. The user is prompted to enter an SMS code that was sent to their phone number.
5. After they enter the SMS code and it is successfully verified, the user enters their new email address and updates it.

APIs for step-up authentication

To implement the functionality described in the example above, you need the OAuth and OpenID Connect API, which includes the acr_values query parameter.

The OpenID Connect Specification defines the acr_values attribute, which specifies the level of authentication that the client application is requesting.

CURL request

Assuming that the user is already logged in with their username and password, after the user chooses to change their email address, use the following request:

curl --request GET \
  --url 'https://www.onewelcome.com/onewelcome-dev/auth/oauth2.0/v1/authorize?response_type=id_token&client_id=my_oauth2_client&redirect_uri=https%3A%2F%2Fwww.myApp.com&scope=openid%20email%20phone&state=something&nonce=aewqeqeewqweq&acr_values=aal2'

Bash response

The response is a redirect to the login page with a special token, because the user is not authenticated with a second factor:

< HTTP/2 302 
< location: https://www.onewelcome.com/onewelcome-dev/login/?sessionOnly=true&stepUpTrackId=c7992519-b097-4a14-bba5-c83ff1271697&goto=https%3A%2F%2Fwww.iwelcome.com%2Fiwelcome-dev%2Fauth%2Foauth2.0%2Fv1%2Fauthorize%3Fresponse_type%3Did_token%26client_id%3Dmy_oauth2_client%26redirect_uri%3Dhttps%253A%252F%252Fwww.myApp.com%26scope%3Dopenid%2520email%2520phone%26state%3Dsomething%26nonce%3Daewqeqeewqweq%26acr_values%3Daal2

OneWelcome Identity Platform evaluates the best next options for authenticating the user based on the requested ACR and the already used authentication methods, and shows the user a screen with multiple options that they can choose from. After the user successfully authenticates with the second factor, they are redirected to your application, with an ID token that has the requested acr claim, which indicates that the user achieved the requested level of authentication.

JSON ID token

The following example shows an id_token with the acr claim:

{
  "sub": "a26f674e-8a88-40f8-a6dd-a1a4bbb7c6dd",
  "email_verified": false,
  "iss": "https://www.onewelcome.com/auth/oauth2.0",
  "tokenName": "id_token",
  "phone_number_verified": false,
  "nonce": "aewqeqeewqweq",
  "aud": "your_app",
  "azp": "your_app",
  "auth_time": 1618568370,
  "phone_number": "01371234567890`",
  "exp": 1618571976,
  "tokenType": "JWTToken",
  "iat": 1618568376,
  "email": "xyz@yopmail.com",
  "session-id": "e57627e8-a13a-4538-a1aa-0ce0bda26009",
  "acr":"aal2"
}