Overview

Get an idea of how OpenID Connect with AXN works.

OpenID Connect in 5 Steps

Step 1- /authorize redirect

The relying party makes an OpenID Connect /authorize request to ID DataWeb, including the client ID of the verification workflow, and other key elements (described below and in the technical documentation.)

This browser redirect step can be triggered from your custom application, or through one of the many integrations to SSO and identity systems.

Browser redirect:

HTTP/1.1 302 Found
Location: https://preprod1.iddataweb.com/preprod-axn/axn/oauth2/authorize         
          ?response_type=code
          &scope=openid%20idp.google%20country.us
          &client_id=12345
          &state=554433
          &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb

Step 2- Identity Verification

Once the page loads, the user will begin the identity verification process. This verification process is configured by the customer administrator, and is called a "Verification Workflow."

Depending on your configuration, the user may go through one or many steps to complete the process. Once complete, ID DataWeb will redirect the browser back to the original application's "Redirect URL", as described in the next step.

Step 3- Authorization code to client application

Once verification is complete on the ID DataWeb side, a one-time pin known as an "authorization code" is passed back to the client application's "redirect URL" specified in AXN Admin.

HTTP/1.1 302 Found
Location: https://client.example.org/cb?
          code=SplxlOBeZQQYbYS6WxSbIA
          &state=af0ifjsldkj

Step 4 - Customer Application Retrieves the ID Token

Once the authorization code has been obtained, your application must exchange this (and other client specific data) for the results of the authentication and verification events. This is done by passing the required data to AXN's token endpoint. Once validated, the AXN will respond with the token payload.

Request

POST
HTTP/1.1 302 Found
Location: https://preprod1.iddataweb.com/preprod-axn/axn/oauth2/token
Content-Type: application/x-www-form-urlencoded
body: grant_type=authorization_code
 &code=SplxlOBeZQQYbYS6WxSbIA
 &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
 &client_id=s6BhdRkqt3&client_secret=12345

Response

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzc
    yI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5
    NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZ
    fV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5Nz
    AKfQ.ggW8hZ1EuVLuxNuuIJKX_V8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6q
    Jp6IcmD3HP99Obi1PRs-cwh3LO-p146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJ
    NqeGpe-gccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgjxqGByKHiOtX7Tpd
    QyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoS
    K5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4
    XUVrWOLrLl0nx7RkKU8NXNHq-rvKMzqg"
  "access_token": "SlAV32hkKG",
  "token_type": "Bearer",
  "expires_in": 3600,
}

🚧

Verifying the ID Token's digital signature

It is highly recommended that the RP verifies the ID Token's digital signature. Please see the next page for more information.

Contents of ID Token

The id_token can be decoded and verified to produce the output JSON, as described here.

Once decoded, the format of the id_token is the following:

{
    "at_hash": "udfkrvnPivU4uE0BYeUcXA",
    "sub": "[email protected]",
    "aud": "18976aa43dca4b4e",
    "endpoint": {
      "status": "success",
      "errorCode": "",
      "errorDescription": "",
      "credential": "[email protected]",
      "credentialCreationDate": "02/08/2022 21:09:35 UTC",
      "mbun": "f3f2a548-6c67-4155-8e30-bb1a28c84647",
      "maxToken": "EnMbLwzgyefV3dndx9d5r1C-iEyZ8PpRhuIeIFlGpIE",
      "endpointInstanceList": [
          //details of each step (api key) in verification workflow
        ]
    },
    "policyDecision": "approve",
    "idwRiskScore": "100",
    "iss": "https://preprod1.iddataweb.com/preprod-axn",
    "idwTrustScore": "100",
    "exp": 1644355218,
    "iat": 1644354618,
    "jti": "008ab766-a58d-4489-b4cd-85188d2562d0"
  }

The key attribute in the output is the policyDecision, which indicates how you should proceed with your user - APPROVE (user met your verification policy, proceed to next step), or DENY (user was not verified.) A more detailed look at the ID Token structure can be found here.

Step 5 - User Info

On response, the OP will return a JSON object with the ID token, an access token and an optional refresh token.

Obtaining User Info

Once the tokens are obtained, the RP may obtain results from the /userinfo endpoint. This will return all information required for understanding the result, including the policy decision, scores, assertions and attributes.

📘

UserInfo is optional

Note - the /userinfo call is an optional step, as it will provide the same data as the ID Token. Some 3rd party tools (SSO and IGA systems) require one or the other, so feel free to use whichever is right for your integration.

To access the /userinfo endpoint, the RP must include the access_token from the /token response as a header in the following format: authorization: bearer <access_token>.

Request

POST
HTTP/1.1 302 Found
Location: https://preprod1.iddataweb.com/preprod-axn/axn/oauth2/userInfo
Content-Type: application/x-www-form-urlencoded
header: Authorization: Bearer SlAV32hkKG

Response

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
   "policyDecision_conclusion":"approve",
   "sub":"dbbb757f-75c7-40d8-ba88-c36fb43753e9",
   "policyDecision_obligationApiKey":"null",
   "policyDecision_obligationParam":"null",
   "policyDecision_status":"success",
   "policyDecision_message":"null",
   "userAttributes_InternationalTelephone_dialCode":"1",
   "userAttributes_InternationalTelephone_telephone":"(XXX) xxx-xxxx",   
   "acquiredAttributes_AcquiredFullName_fname":"Roger",
   "acquiredAttributes_AcquiredFullName_lname":"Jones",
   "userAssertionList_ap_assertionCategory.assertionName":"pass",
   
}

For the /userInfo endpoint, policyDecision_conclusion is the key attribute to determine what happens next with your user, as described here.


What’s Next

Next, learn how to verify and parse the ID Token to obtain user verification results.