Select different authentication methods using the acr_values parameter

Owned by Keith Uber
Last updated: 2019-12-16
4 min read

If an OAuth relying party is configured to have more than one authentication method, it is possible to skip the selection menu or limit the choices using the acr_values parameter in the OIDC authentication request.

This allows a calling application to implement its own discovery capability.

Typically this is used to enable an application to skip the discovery service of an upstream IDP by selecting the authentication method already at the relying party.

Step-by-step guide

Example 1 - BankID Selection

For this example, we will use an application using OpenID Connect, that is connected to two authentication methods - one is for BankID Mobile and the other is traditional client PKI certificate based BankID.

To enable calling a specific authentication method, you must assign a unique acr_values to each method in the OpenID Connect Authentication Context Class Reference field found in the method settings page (Home → Methods → Select method)

For example, for the method that is for BankID Mobile use bankidmobile

For example, for the method that is for BankID use bankid

When creating the authorization request in the calling application, include the value of the method you wish to select. For example, to select standard BankID use

GET https://sso.example.com/uas/oauth2/authorization?response_type=code&scope=openid&client_id=2001221477&redirect_uri=https://client.example.com/response&state=40e1bfc0-4587-4859-be08-a58e3fffa37a&acr_values=bankid

or for BankID Mobile

GET https://sso.example.com/uas/oauth2/authorization?response_type=code&scope=openid&client_id=2001221477&redirect_uri=https://client.example.com/response&state=40e1bfc0-4587-4859-be08-a58e3fffa37a&acr_values=bankidmobile

If no acr_values parameter is specified, both methods (or all methods enabled for the agent) will be displayed in a menu for the user.

GET https://sso.example.com/uas/oauth2/authorization?response_type=code&scope=openid&client_id=2001221477&redirect_uri=https://client.example.com/response&state=40e1bfc0-4587-4859-be08-a58e3fffa37a

If the request is unsigned, it is important that the relying party verifies that the authentication was performed successfully using the desired method by checking the acr and/or amr (Authentication Method Reference) value in the response returned. The amr value and acr value are visible in the example userinfo response below

Sample userinfo response
HTTP/1.1 200 OK 
Content-Type: application/json  
{"sub":"***","iss":"https://sso.example.com/uas","aud":"2001221477","exp":1429700671981,"iat":1429697071971,"auth_time":1429697071527,"amr":["https://sso.example.com/uas/saml2/names/ac/bankidmobile.1"],"session_index":"0a9b62ce8de4","acr":["bankidmobile"]}

If the values do not match what was request, the application must handle the situation.

 

Where possible, following standard naming conventions for best interoperability. Standard amr values are defined in RFC8176 https://tools.ietf.org/html/rfc8176

The OpenID Connect Authentication Context Class Reference field can accept multiple values separated by a whitespace character.

If more than one method has the same OpenID Connect Authentication Context Class Reference, the user will be shown a selection menu to choose the desired method.

Assigned values in the OpenID Connect Authentication Context Class Reference field become visible in the Configuration String field oidc.acr.

There is an API to retrieve the list of currently configured authentication methods enabled for a given relying party as a JSON response. Refer to Ubisecure SSO Discovery API for more information.


This technique could also be used to enable an application to remember what authentication the user selected on their previous visit and automatically select the same on the next visit. The calling application would have to manage and store this preference information.


Example 2 - Finnish Bank Selection

For this example, we will use an application using OpenID Connect, that is connected to Finnish banks, known as TUPAS authentication - by including tupas and a unique name for each bank in the method settings, the calling application can decided whether to show all banks or preselect one.

To enable calling a specific authentication method, you must assign a unique acr_values to each method in the OpenID Connect Authentication Context Class Reference field found in the method settings page (Home → Methods → Select method)

For example, for the method that is for Nordea bank use "tupas nordea"

For example, for the method that is for Danske bank use "tupas danske"

When creating the authorization request in the calling application, include the value of the method you wish to select. For example, to select Nordea use the acr_values set to "nordea".

GET https://sso.example.com/uas/oauth2/authorization?response_type=code&scope=openid&client_id=2001221477&redirect_uri=https://client.example.com/response&state=40e1bfc0-4587-4859-be08-a58e3fffa37a&acr_values=nordea

or to select any TUPAS bank (a menu will be shown for the user to choose), use the acr_values set to "tupas". Both Nordea and Danske will be displayed for the user to choose.

GET https://sso.example.com/uas/oauth2/authorization?response_type=code&scope=openid&client_id=2001221477&redirect_uri=https://client.example.com/response&state=40e1bfc0-4587-4859-be08-a58e3fffa37a&acr_values=tupas

Example 3 - Mobile Connect LoA

For this example, we will use an application using OpenID Connect according to the GSMA Mobile Connect profile, which specifies acr_values as 2, 3 and 4.

To enable calling a specific authentication method, you must assign a unique acr_values to each method in the OpenID Connect Authentication Context Class Reference field found in the method settings page (Home → Methods → Select method)

For example, for the a method that can fulfil both LoA 2 and 3, use "2 3" in the OpenID Connect Authentication Context field.

For example, to indicate that Mobile PKI fulfils LoA 3, use "3" in the OpenID Connect Authentication Context field.

When creating the authorization request in the calling application, include the value of the method you wish to select. For example, to select a method including use the acr_values set to 3.

GET https://sso.example.com/uas/oauth2/authorization?response_type=code&scope=openid&client_id=2001221477&redirect_uri=https://client.example.com/response&state=40e1bfc0-4587-4859-be08-a58e3fffa37a&acr_values=2

or to select any method, either LoA 2 or 3, and allow the user to choose.

GET https://sso.example.com/uas/oauth2/authorization?response_type=code&scope=openid&client_id=2001221477&redirect_uri=https://client.example.com/response&state=40e1bfc0-4587-4859-be08-a58e3fffa37a&acr_values=2%203



Ubisecure Privacy Policy & Cookie Statement