Contents

Select different authentication methods using the acr_values parameter

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.

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

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.

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 - 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=3

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

Configure authentication method to send acr_values in authorization request

Some IDPs might require that certain ACR values are sent with the authorization request parameters. To configure your OpenID Connect authentication method to send acr_values parameter you need to provide the configuration in the client registration response. Currently creating and configuring OpenID Connect authentication methods is only possible through the Management API REST calls.

To create and configure an OpenID Connect authentication method follow the instructions in OpenID Connect authentication method.

Most important part to notice is in the registration response body. Here you can provide a static value for acr_values always added to the authorization requests sent to the IDP by this authentication method.

PUT /sso-api/method/oidc.method.1/$attribute/registration HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJjdHk...hFNzMq-hTuw
Host: sso.example.com


{

    .....

    "ubisecure_request_parameters": {
    	"acr_values": "acr1"
    }
}

Related articles

• Page:
  Show different help text depending on the application used
• Page:
  Select different authentication methods using the acr_values parameter
• Page:
  Admin/self-service UI [Warning: Property for 'xx.xx.xx.xx' not found]
• Page:
  Show different UI text using the oidc display parameter
• Page:
  Show different UI texts depending on the template used