Prefill PII from your Application

This document outlines how to prefill PII into your verification workflow for an end user.

An example:

You are attempting to verify that the user on the device is the account holder.
In this case - prefill full name (and potentially other attributes), and lock them on the verification workflow side.
This way, the user must verify that they are specifically the account holder, instead of just verifying they are who they say they are.

Prefill Options

There are three options for prefilling PII into your Verification Workflow:

Login_hint Prefill - API - Call the ID DataWeb Admin API with the end user's PII to generate a fully formed JWT, then add this value as a login_hint to your /authorize request.
Login_hint Prefill - Create JWT - Create a JWT in your application with the end user's PII, and add it as a login_hint to your /authorize request.
Pre-Verify Federated Login - Add a federated login to the beginning of your verification workflow, and map attributes from your SSO system to the ID DataWeb form through OpenID Connect.

Note - For both options 1 and 2, you can choose to use a digital signature OR encryption for your JWT. Your solutions architect can configure your API key appropriately.

Digital Signature is appropriate to use when there is no PII included in the payload, or in lower environments for POCs.
Payload Encryption should be used when sensitive information is included.

Option 1: Use the Admin API to generate a JWT for prefill

In this option, you will call the AXN Admin API to generate a fully formed JSON Web Token for you. As an output, you can use this value to append to your /authorize request.

Get an AXN Admin access token. Your solutions architect can generate the credentials required for this step. When you have them, obtain an OAuth2 access token using this API call.
With the token, make a request to the verification link API. . The key inputs for this API call are:
- the access token from step 1
- the api key which you plan to prefill. Note - this is the first client ID in your verification workflow.
- the PII which you want to prefill. Note - ID DataWeb recommends the "full name" field as a minimum. The format follows the standard ID DataWeb PII input format (an example is shown in the docs linked above.)

API Payload Template if Prefilling via. Admin API

{
    "apiKey": "your_workflow_api_key",
    "redirectURL": "https://preprod.mockrp.iddataweb.com/mockrp2/endpoint/preprod/viewEndpoint",
    "credential": "(optional) user credential",
    "IDP": "google",
    "country": "US",
    "userAttributes": [
        {
            "attributeType": "FullName",
            "values": {
                "fname": "First",
                "mname": "",
                "lname": "Last"
            }
        },
        {
            "attributeType": "InternationalTelephone",
            "values": {
                "dialCode": "1",
                "telephone": "123456789"
            }
        },
        {
            "attributeType": "Country",
            "values": {
                "country": "US"
            }
        },
        {
            "attributeType": "InternationalAddress",
            "values": {
                "country": "US",
                "administrative_area_level_1": "VA",
                "locality": "Vienna",
                "postal_code": "23225",
                "route": "Liberty St",
                "street_number": "123"
            }
        },
        {
            "attributeType": "DOB",
            "values": {
                "day": "01",
                "month": "01",
                "year": "1991"
            }
        },
        {
            "attributeType": "SSN4",
            "values": {
                "ssn4": "1234"
            }
        },
        {
            "attributeType": "SSN9",
            "values": {
                "ssn9": "123456789"
            }
        }
    ]
}

As an output, you will receive a fully formed Gateway (/authorize) link that will begin verification with prefilled details.

Option 2: Create a JWT in your application for prefill

👍
Use open source libraries for JWT creation
For this process, it is highly recommended you use an industry standard library to create your JWT. A good list can be found here (for digital signatures) and here (including JSON Web Encryption).

JWT Payload format

The input format should follow the following structure:

{  
  "iat": 1717920000,  // Issued At: June 9, 2024 00:00:00 UTC
  "exp": 1718006400,  // Expiration: June 10, 2024 00:00:00 UTC
  "sub": "user:123456",  // Subject: Could be a user ID or UUID.
  "credential": "user_id_",  // Credential: Could be a user ID or UUID.
  "FullName": {
    "fname": "First",
    "mname": "",
    "lname": "Last"
  },
  "InternationalTelephone": {
    "dialCode": "1",
    "telephone": "123456789"
  },
  "Country": {
    "country": "US"
  },
  "InternationalAddress": {
    "country": "US",
    "administrative_area_level_1": "VA",
    "locality": "Vienna",
    "postal_code": "23225",
    "route": "Liberty St",
    "street_number": "123"
  },
  "DOB": {
    "day": "01",
    "month": "01",
    "year": "1991"
  },
  "SSN4": {
    "ssn4": "1234"
  },
  "SSN9": {
    "ssn9": "123456789"
  }
}

Notes:

some of these values, including iat and exp should be generated by the library you are using to create JWTs.
Credential is a required field.
Aside from credential - you only need to include the required PII attributes above for your use case.

Creating a Digitally Signed JWT

For this process, it is highly recommended you use an industry standard library to create your JWT. A good list can be found here.

Required parameters for open source libraries:

algorithm: HS256
secret for digital signature: client_secret of your service

Process

Set your library to use the above algorithm and secret.
input your payload (per format above) into the function.
output should be a digitally signed JWT.

Creating an Encrypted JWT

In this process, you will be encrypting your JWT with a public key obtained from AXN Admin, which will be decrypted using the private key on the ID DataWeb side.

Required parameters:

Key encryption algorithm (alg) : RSA-OAEP-256
Content encryption (enc) : A128GCM
public key: Obtain from ID DataWeb AXN Admin or your Solutions Architect

Process

Set your library to use the above parameters.
input your payload (per format above) into the function.
output should be an encrypted JWT.

Including your JWT in /authorize call

Make your /authorize request including the login_hint=<your JWT> to initiate your verification workflow:

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
          &login_hint=<your digitally signed JWT>

As a result, the PII will be prefilled on the user's verification workflow.

Option 3: Add a federated login to the beginning of your flow

If a federated login is setup, the user will be authenticated with an Identity Provider (IDP) and then their authentication details will be sent to us for final verification. You can configure the IDP connection to map the user's PII to IDDataWeb user attributes. Typically the user is already authenticated by this point, so they will not have to login again.

Steps

Step 1: Add a federated IDP connection, as outlined here: Adding a federated Identity Provider (IDP)
Step 2: Add the federated IDP to your verification service as per this documentation .
Step 3: Map attributes returned from your IDP to IDDataWeb attributes. Documentation on how to do this can be found here .
Step 4: In your /authorize request, add the appropriate "scope" field to trigger authentication with your configured IDP. For example - idp.bentestIDP.
- The format is: idp.<code field from your IDP configuration page>. For example: idp.bentestidp
Result: User begins verification workflow with PII prefilled.