Triggering IAL2 Verification Using OAuth 2.0 and OIDC

Overview

Identity Assurance Levels (IALs) are a set of standards defined by the National Institute of Standards and Technology (NIST) that convey the degree of confidence that someone's claimed identity is their real identity - in other words, how likely an individual is actually who they say they are.

The three identity assurance levels, as defined in NIST Special Publication 800-63-3 are:

• IAL1: No requirement to link the individual to a specific real-life identity. Any information provided by the individual should be treated as self-asserted.
• IAL2: Uses digital documents to support the real-world existence of an identity and verifies that the correct person is associated with it.
• IAL3: Requires an authorized and trained representative to verify the individual in person.

Users can upgrade their own status to IAL2 in AdminX by using our web-based identity-proofing flow. Tenant and community Administrators can trigger this flow using OpenID Connect (OIDC) ACR claims.

Prerequisites

• Configured OIDC Application in AdminX

Users should first ensure they have configured an OIDC application for SSO before starting. Please see OIDC Integration in AdminX for more information.

To view your OIDC Application settings, navigate to your AdminX portal and log in as a tenant or community administrator.

Navigate to the Applications page and find your OIDC application. Click the pencil icon, located under actions, to view the OIDC application settings.

Your Client ID and Client Secret can be viewed and copied from this screen.

Fetch Current IAL Using Custom Scope

Your current IAL can be requested using the /assurance/ial/2 custom scope, as shown below:

https://blockid-trial.1kosmos.net/oauth2/community/default/v1/authorize
  ?response_type=code
  &client_id=ae0456c92ac24f0ace200f103ab93c81
  &scope=email openid /assurance/ial/2
  &redirect_uri=https://google.com
  &state=123

The OIDC response returned by the server will contain the user's current IAL, located in the amr parameter.

Requesting IAL2 Step-Up Verification

Using Custom Scope

IAL2 step-up verification can be requested using the /assurance/ial/2 custom scope in your request, as shown below:

https://blockid-trial.1kosmos.net/oauth2/community/default/v1/authorize
  ?response_type=code
  &client_id=ae0456c92ac24f0ace200f103ab000000
  &scope=openid /assurance/ial/2
  &redirect_uri=https://google.com
  &state=123

Response payload:

  "sub": "1PJ8RjLctvisMZvADuKNp",
  "ial": "IAL2",
  "acr": "/assurance/ial/2/",
  "amr": [
    "IAL2"
  ],
  "at_hash": "zYYYvMoJBs9v4kOhiyt000",
  "aud": "33724c7d05e452695658af5a38500000",
  "exp": 1680079821,
  "iat": 1680076221,
  "iss": "https://blockid-trial.1kosmos.net/oauth2/community/default"
}

From a user's standpoint, they will be redirected to AdminX to perform their step-up identity verification as opposed to a standard login. Once the idenity verification is completed, the user will be at IAL2.

Using ACR Claims

IAL2 step-up verification can also be requested using ACR Claims, as shown below:

<authorize_endpoint>
  ?response=...
  &client_id=...
  &scope=...
  &redirect_uri=...
  &state=...
  &claims={ "id_token": { "acr": { "values": ["/assurance/ial/2/"] } } }

From a user's standpoint, they will be redirected to AdminX to perform their identity verification as opposed to a standard login. Once the idenity verification is completed, the user will be at IAL2.

OIDC Responses

Depending on the user's current IAL level after performing their identity verification, the server will return different responses.

The table below shows the different OIDC responses that are returned after the user has attempted an Identity Verification.

Requested AuthnContext	User's IAL Level After Identity Verification	OIDC Response
IAL2	IAL1 (Failed Identity Verification or Insufficient Information)	{ "acr": "/assurance/ial/2/", "amr": [] }
IAL2	IAL2	{ "acr": "/assurance/ial/2/", "amr": ["IAL2"] }
IAL2	IAL3	{ "acr": "/assurance/ial/2/", "amr": ["IAL2","IAL3"] }