High-value transaction

Some content or user actions within a website or application are more sensitive than others and warrant an extra security checkpoint even after the user has logged in. Examples can include accessing personal medical information, viewing and changing billing details, or making a purchase. These types of actions are considered to be high-value transactions.

With Risk-based Authentication (RBA), you can assess a user’s level of authentication at the entry point to a high-value transaction and, if needed, require an extra security step such as two-factor authentication (2FA) before allowing them to proceed. High-value transaction scenario | Icons by Font Awesome, see fontawesome.com/license

In order for your application to assess the user’s authentication, RBA provides two pieces of data in the user’s id_token: acr and amr claims.

Example id_token:

{
	"acr": "urn:akamai-ic:nist:800-63-3:aal:2",
	"amr": [
		"pwd",
		"email",
		"mfa",
		"rba"
	],
	"at_hash": "2Wu8cM6aE48cXsIK5L5iLg",
	"aud": [
		"12a345b6-c7d8-9e01-f2g3-h4567i890j12"
	],
	"auth_time": 1613087947,
	"exp": 1613091553,
	"global_sub": "capture-v1://us.janraincapture.com/a1bcde2fg3h456ijk7l8mnop9q/user/eca1f099-8003-4c7e-92ff-d45f80f47ec7",
	"iat": 1613087953,
	"iss": "https://v1.api.us.janrain.com/a12bc34d-567e-8f90-gh12-3i45jk678lm9/login",
	"jti": "GGJt96B0vhLFCfsdTbNnMQBn",
	"sub": "eca1f099-8003-4c7e-92ff-d45f80f47ec7"
}

Another helpful piece of data is the auth_time claim. This lets you know when the user authenticated, and can be evaluated when the amount of time since last authentication matters to you.

ACR

ACR is a standard OpenID Connect (OIDC) term that is short for “Authentication Context Class Reference”. It indicates the level, or class, of authentication which the user has satisfied. Hosted Login can return the following ACR values:

Level of authentication Actual acr value What this indicates
Level 1 urn:akamai-ic:nist:800-63-3:aal:1 Login with credentials (password or social account)
Level 2 urn:akamai-ic:nist:800-63-3:aal:2 Login with credentials plus 2FA

AMR

AMR is a standard OpenID Connect (OIDC) term that is short for “Authentication Methods References”. It indicates the elements, or methods, of authentication which were used in the current Hosted Login session. Hosted Login can return the following AMR values:

Element of authentication Actual amr value What this indicates
Credentials pwd Login with credentials (password or social account)
Email email Confirmation via email message to the registered email address
SMS sms Confirmation via SMS message to the registered phone number
Multiple authentication factors mfa This is equal to pwd + email or pwd + sms (2FA)
RBA score rba A risk score has been evaluated, as in Client Reputation

The AMR value can be used by your application to assess the user when their specific methods of authentication matter to you.

ACR Step-up

The ACR value can be used in a request to Hosted Login to step-up the user’s authentication.

Example: A logged-in user attempts to access personal account details on your website, and this requires 2FA. However, their id_token indicates they have not completed 2FA. You trigger Hosted Login to step-up the user’s authentication.

To do this, you must make the /login/authorize call with an acr_values parameter like this:

acr_values = urn:akamai-ic:nist:800-63-3:aal:2

Example call to Hosted Login:

https://v1.api.us.janrain.com/a12bc34d-567e-8f90-gh12-3i45jk678lm9/login/authorize
	?client_id=12a345b6-c7d8-9e01-f2g3-h4567i890j12
	&redirect_uri=https://myapp.com/redirect_uri
	&scope=openid
	&code_challenge=PWt_2Fz95DnyzxREOAhdFAD95m9HoErGlfOpj3yLC3E
	&code_challenge_method=S256
	&response_type=code
	&state=Vz8tHF2An2hXJ-aN_-xh0qpB7DtavIjdQivhGmzcX64
	&acr_values=urn%3Aakamai-ic%3Anist%3A800-63-3%3Aaal%3A2

Note that in the call to Hosted Login, the value of the acr_values parameter must be URL encoded.

This can be confusing - you’re making the /login/authorize call even though the user may already be logged in. To be clear, the example call above will evaluate the user’s acr value and do the following:

  • If they haven’t reached ACR level 2 - meaning they haven’t completed 2FA - Hosted Login will prompt them to complete 2FA.
  • If they haven’t reached ACR level 1 - meaning they are not logged in - Hosted Login will prompt them to login and complete 2FA.

Sample Step-up Flow

A recommended flow for utilizing the ACR value to step-up the user looks something like this: ACR step-up flow diagram | Icons by Font Awesome, see fontawesome.com/license

Let’s step through this:

  1. A user logs into your application.
  2. Your application stores the Hosted Login id_token in its session.

    For more information on the login/token flow and session management, see Sample Login Flow in the Sessions & SSO guide.

  3. The user attempts a high-value transaction (HVT), such as making a payment.
  4. Before allowing this action, your application checks the user’s acr value in the stored id_token.
    • If you care about when the user last authenticated, for example within the last 30 minutes, your application should also check the user’s auth_time value.

      If the user meets your authentication requirements for this transaction, the application allows the user to continue.
      (The remaining steps are not needed.)

  5. If the user does not meet your authentication requirements for this transaction, the application makes an authorize call to Hosted Login as depicted in the example above.
    • If you care about when the user last authenticated, add the max_age parameter to your authorize call. Your app can dictate both how and when the user must have authenticated by using the two parameters: acr_values and max_age

      For more information, see Max Age in the Hosted Login Getting Started Guide.

  6. Hosted Login compares the user’s ACR value (Level 1) to the requested acr_values parameter (Level 2). Since the user has logged in but hasn’t satisfied the 2FA request, Hosted Login prompts the user to complete 2FA.
  7. The user completes the 2FA process, and Hosted Login returns an updated id_token to the application.
  8. The application checks the id_token from Hosted Login, which serves as a receipt of the step-up authentication. If the required values are present, it allows the user to continue.

Hidden Step-up Request

You can request that Hosted Login evaluate the user’s ACR value for you and respond accordingly without triggering a step-up screen to the user. This is done by making the /login/authorize call with the following adjustments:

  • Add the parameter prompt=none

  • Instead of the acr_values parameter, use the claims parameter and include the "acr" claim with "essential": true, like this:

    claims={
  	"id_token": {
  		"acr": {
  			"essential": true,
  			"values": ["urn:akamai-ic:nist:800-63-3:aal:2"]
  		}
  	}
  }

    Including "essential": true lets Hosted Login know that you require this evaluation. If you don’t include this, Hosted Login will consider the requested ACR value to be optional.

Example call to Hosted Login:

https://v1.api.us.janrain.com/a12bc34d-567e-8f90-gh12-3i45jk678lm9/login/authorize
	?client_id=12a345b6-c7d8-9e01-f2g3-h4567i890j12
	&redirect_uri=https://myapp.com/redirect_uri
	&scope=openid
	&code_challenge=PWt_2Fz95DnyzxREOAhdFAD95m9HoErGlfOpj3yLC3E
	&code_challenge_method=S256
	&response_type=code
	&state=Vz8tHF2An2hXJ-aN_-xh0qpB7DtavIjdQivhGmzcX64
	&prompt=none
	&claims=%7B%22id_token%22%3A%7B%22acr%22%3A%7B%22essential%22%3Atrue%2C%22values%22%3A%5B%22urn%3Aakamai-ic%3Anist%3A800-63-3%3Aaal%3A2%22%5D%7D%7D%7D

Note that in the call to Hosted Login, the value of the claims parameter must be URL encoded.

Example response to the redirect_uri when the requested ACR value has not been met by the user:

https://myapp.com/redirect_uri
	?error=interaction_required
	&error_description=Authorization+rule+%27requested_acr%27+failed
	&state=Vz8tHF2An2hXJ-aN_-xh0qpB7DtavIjdQivhGmzcX64

When the requested ACR value has been met, Hosted Login redirects with an authorization code, similar to a successful login.