OIDC step-up authentication
Step up authentication is mechanism used by OIDC/SAML clients to require stronger authentication level based on a security policy defined by the client.
How does this work?
Let's assume you want to build a web application that allows users which are authenticated with a first factor, such as username and password or with a remote IDP (Facebook, Google, etc.), to view information about their account. When they want to perform an update of a specific attribute from their profile, for extra security measures, you want to challenge the user to authenticate with an extra factor, such as a push notification or an OTP.
A visualisation of an example can be seen below:
The above example can be translated to the following steps:
- User logs in with username and password
- Is redirected to a profile page where information about his/her account is available, such as phone number and email address
- User clicks change email address
- User is prompted with a screen where he/she has to enter a code which has been sent to their phone number
- Once the sms code is entered en successfully verified, the user enters its new email and updates it.
What APIs do you need?
For implementing the functionality described above, the authorize API is needed using the acr_values query parameter.
acr_values is an attribute which is defined by the OpenID Connect Specification , and specifies the level of authentication that is requested by the client application.
Assuming that the user is already logged in with username and password, once the user chooses to change his email, you would do 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'Since the user is not authenticated with a second factor, the response of the request will be a redirect to the login page with a special token:
< 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%3Daal2OneWelcome will evaluate based on the requested ACR and the already used authentication methods, what's the best next option/s to authenticate the user with, and will show the user a screen with multiple options from where he/she can choose from. Once the user successfully authenticates with the second factor, the user will be redirected back to your application, with an id token having the requested acr claim, which indicates that the user achieved the requested level of authentication.
An example of id_token, with the acr claim can be seen below:
{ "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"}