How to integrate the App (V2) 

Overview 

Identity Proofing Application (IPA) is an application that verifies the Identity of your Users. It can be integrated in your own application in 2 possible ways :

• Standard IPA, where at the end of the process you get a Verified Identity of your User to proceed further with their on-boarding process.
• IPA with Microsoft ENTRA, where your User gets a Verifiable Credential with their Identity provisioned in their Microsoft Authenticator App, that they can share with you to complete their on-boarding process.

Standard IPA Integration 

Creation of an IPA Application 

First you must create an application in the Experience Portal. The configurator guides you through the necessary steps to adapt the application to your requirements. Once the application is created, some identifiers and secrets are generated and made available through the Experience portal. These identifiers enable your application to establish connectivity with IPA.

1. Create the IPA App

Go to 'Access -> Identity Proofing App' page and click 'Create new app'.

2. IPA Configuration

1. Choose application name.
2. Select environment.
3. Select a country and document types.
4. Choose one of the possible face capture options:
   • none - no face verification
   • Passive Video Liveness - Liveness verification with seamless User Experience (recommended)
   • Active Liveness - Liveness verification with active User challenge (face movements requested, recommended for high security applications only as it may impact the average success rate of the process).
5. Customize look & feel of your application.
6. Confirm on summary screen.

3. Experience your IPA configuration

Once you have created your application, the following options are available to you :

• Generate QR code - you can test your IPA configuration. Just scan the QR code with your smart phone's camera and experience the User's Journey by yourself. You can check the verification details of your tests in the Transactions History section of the Experience Portal

• Display Endpoint details - get the necessary connectivity details to integrate your IPA configuration into your own Application

• clientID

• secretKey

• Cognito URL

• Create Session URL

• Delete/Edit configured application.

Integrating IPA in your Application 

Overview

Here is a flow diagram detailing each step of the process. It is divided in 5 Steps.

1. Obtain an access token
2. Create IPA Session
3. User performs Identity Proofing Process
4. Receive End of Process Notification
5. Retrieve Verified Identity and redirect the User to the next step
   
   The chapters below detail how to implement this sequence diagram.

Step 0: Engage User and gather consent

As a preliminary step, you need to engage with your End User through the method of your choice, and expose your Terms of Use of the service to gather User Consent. This part of the process is entirely between you and your User. When you create an IPA session, we assume that the End User consented to the agreed Terms of Use.

Step 1: Obtain application access token

First, your back end application must obtain an access token to the IPA application using the Cognito URL, secretKey and clientID.

Example request

Shell
1curl -X POST --location '[COGNITO_URL]/oauth2/token' \
2  --header 'Content-Type: application/x-www-form-urlencoded' \
3  --data-urlencode 'grant_type=client_credentials' \
4  --data-urlencode 'client_id=[CLIENT_ID]' \
5  --data-urlencode 'client_secret=[SECRET_KEY]'
6

Request Variables

Example Response

JSON
1{
2  "access_token": "[ACCESS_TOKEN]",
3  "expires_in": 3600,
4  "token_type": "Bearer"
5}
6

Response Variables

Step 2: Create session

Then, with the access token received from the previous step, create an IPA application session.

This is where you define the callback endpoint to which your backend service is going to receive start and end of session notifications.

You may also define where your User will be redirected to, once the Identity Proofing session is over.

Once created, the session expires automatically after 30 minutes.

IPA Create Session URL

The URL to create a session is : https://rp-handler.did.idemia.io/api/v2/sessions

Example request

Shell
1curl -X POST --location 'https://rp-handler.did.idemia.io/api/v2/sessions' \
2  --header 'Content-Type: application/json' \
3  --header 'Authorization: Bearer [ACCESS_TOKEN]' \
4  --data '{
5    "requestId":  "[REQUEST_ID]",
6    "callbackUrl" : "[CALLBACK_URL]",
7    "callbackAccessToken" : "[CALLBACK_ACCESS_TOKEN]",
8    "gotoUrl" : "[GOTO_URL]"
9  }'
10

Request Variables

Note : Both callbackUrl and gotoUrl are optional parameters. If no callbackUrl and/or gotoUrl is provided, there will be no callback requests, or user redirection performed at the end of the process.

Response

The response payload contains the IPA Session Identifier as well as the URL that needs to be transmitted to your User to start the Identity Proofing process from their smartphone.

Example Response

JSON
1{
2  "sessionId": "[SESSION_ID]",
3  "startUrl": "[START_URL]",
4  "qrCode": "[BASE64_QRCODE_IMAGE]"
5}
6

Response Variables

Step 3: User performs the Identity Proofing Process with IPA

Once you have received the IPA sessionId and Start URL from the previous step, record the SessionId and transmit the IPA session's URL to your user, so they can start the IPA from their own smartphone device.

This URL can be transmitted in multiple ways, like in the form a QR code to scan, a text message, or an email.

At the moment the User activates the link that you transmitted, they start the Identity Proofing Process.

When the User starts the Identity Proofing Process, you receive a "start session" notification to your backend's callback URL defined in step 2.

Your callback endpoint must be able to accept the following request :

Example request

Shell
1curl -X POST --location [CALLBACK_URL] \
2  --header 'Content-Type: application/json' \
3  --header 'Authorization: Bearer [CALLBACK_ACCESS_TOKEN]' \
4  --data '{
5      "applicationId":  "[APPLICATION_ID]",
6      "sessionId":  "[SESSION_ID]",
7      "identityId" : "[IDENTITY_ID]"
8      "status":  "STARTED",
9      "errorCode":  "NO_ERROR",
10      "requestId":  "[REQUEST_ID]",
11      "timestamp":  [TIMESTAMP]
12    }'
13

Request Variables

Response

It is expected that the callback's listener service returns an HTTP code 2XX with an empty response body to this request.

We recommend to miminize the time and processing before returning the HTTP code 2XX response to reduce performance impacts of activity peaks.

In case of unexpected HTTP response code received (different from 2XX), the IPA service will send up to 2 more attempts with a delay of 1 second.

Identity Proofing Process

The Identity Proofing process is then conducted autonomously by the User through their device's browser.

Note : The Identity Proofing Application automatically checks the device's configuration and informs the User if it does not meet the requirements. Refer to 'Device minimal requirements' for more details.

Step 4: Receive End of Process Notification

When the User has completed the Identity Proofing Process, you receive an "end of process notification" to your backend's callback URL defined in step 2.

Your callback endpoint must be able to accept the following request :

Example request

Shell
1curl -X POST
2    --location [CALLBACK_URL] \
3    --header "Content-Type: application/json" \
4    --header 'Authorization: Bearer [CALLBACK_ACCESS_TOKEN]' \
5    --data '{
6        "applicationId":  "[APPLICATION_ID]",
7        "identityId":  "[IDENTITY_ID]",
8        "sessionId":  "[SESSION_ID]",
9        "proofUrl":  "[PROOF_URL]",
10        "timestamp":  TIMESTAMP,
11        "status":"[STATUS]",
12        "errorCode":" "[ERROR_CODE]",
13        "loaReached": LOA_REACHED,
14        "requestId":"[REQUEST_ID]"
15    }'
16

Request Variables

Response

It is expected that the callback's listener service returns an HTTP code 2XX with an empty response body to this request.

We recommend to miminize the time and processing before returning the HTTP code 2XX response to reduce performance impacts of activity peaks.

In case of unexpected HTTP response code received (different from 2XX), the IPA service will send up to 2 more attempts with a delay of 10 seconds.

Status values

Here are the possible Status values and their meaning so you can adapt your post processing to the actual outcome of the Identity Proofing session.

Error Codes

Step 5: Retrieve Verified Identity and redirect the User to the next step

Retrieve User's verified Identity using the IdentityId or getProofURL received in the callback.

Use your ID&V REST API endpoint and GIPS-RS API key to do so.

In parallel, the User is redirected to the gotoURL defined in Step 2 to proceed with the rest of your User's on-boarding Journey, using the results of the Identity Proofing session.

Option 1 : Retrieving the Proof file

The proof file is a zip archive containing a comprehensive output of the Identity Proofing session.

It contains the Identity payload, the images captured by the user and a full audit trail of the verifications performed during the session.

For further details, refer to the 'Proof File specifications' and 'Identity Proofing API Documentation'.

Request Example

Shell
1curl -X GET --location [PROOF_URL]
2--header 'Content-Type: application/json' \
3--header 'apikey: [GIPS-RS_API_KEY]' \
4--output proof.tar.gz
5

Request Variables

Response

In response you receive an Identity Proof file containing the Verified Identity of the User as well as all submitted evidence and verification methods detailed results.

Option 2 : Retrieving the Identity payload

The Identity payload contains the detailed results of the Identity proofing session such as :

• Level of Assurance (LOA)
• Identity Attributes (names, date of birth etc...) extracted from the Identity Documents
• Status and error codes of the different evidence captured during the proofing session For further details refer to the 'API Explorer section of the Identity Proofing & Verification API' and look for the GET /v1/identities/{id} endpoint.

Request Example

Shell
1curl -X GET --location https://[IDV_URL]/gips/v1/identities/[IDENTITY_ID] \
2--header 'Content-Type: application/json' \
3--header 'apikey: [GIPS-RS_API_KEY]'
4

Request Variables

Response

In response you receive the Identity payload JSON file containing the Verified Identity of the User.

User Redirection

If you provided a a gotoUrl while creating the IPA session ( Step 2), your User is redirected to that URL.

We append to your gotoUrl some paremeters to help you present the right screen depending on the sesssion outcome, and reconciliate it with the rest of your onboarding journey.

The format of the final User redirect URL is as follows :

[GOTO_URL]?requestId=[REQUEST_ID]&status=[STATUS]&errorCode=[ERROR_CODE]

Example : https://mycompany.myservice.com/signup/confirm?requestId=A.PmvzQKgYek6SdkT5sWaqw.B&status=SUCCESS&errorCode=NO_ERROR

Note : In case of technical issue during the end of process flow (Step 4), it might happen that the redirect URL misses some additional parameters. So the page corresponding to the redirect URL must be prepared for such scenario and interpret it as a technical error.

Integrate using Microsoft VC ENTRA Application 

Azure configuration 

In order to get your Identity Proofing Application integrated with Microsoft ENTRA Verified ID, you must have a valid tenant on your Azure Cloud account. We recommend you to follow the tutorial from Microsoft: Configure your tenant for Microsoft ENTRA Verified ID. You have to create the resources described below:

• Azure Active Directory. Subscription.

• Azure Key Vault (under Resource Group or directly under Subscription).

• App Registration (under Azure Active Directory).

• Access Policy allowing to trigger VC presentation request (under App Registration).

• Verified ID Service (under Azure Active Directory). You need to get a unique set of OAuth2 Client ID and Client secret credentials from App Registration process which is used in "Client Credentials" flow to obtain an Access Token as explained on the following page: Request Service REST API. This access token allows to call VC presentation API: Configure Microsoft ENTRA Verified ID verifier. Moreover, your system needs have a valid domain registered that is verified by Azure Verified ID Service according to DID (Decentralized Identity) policy. Following descriptor files has to be exposed:

• /.well-known/did.json

• /.well-known/did-configuration.json These descriptors are obtained from Verified ID Service. After that setup, you have to select IDEMIA as provider of the trusted credentials which can be located using: {region}.did.idemia.io domain ({region}.did-{stage}.idemia.io for lower stages):

  
  Please note that if you want to authenticate end users across multiple regions, it is required to trust multiple credentials. This is related to Microsoft ENTRA Verified ID service design that controls PII processing according to AD setup location. Microsoft provides the entire process including usage of the sample app in this tutorial: Configure Microsoft ENTRA Verified ID verifier.

Microsoft VC ENTRA Application flow diagram 

Creation of IPA for ENTRA application 

In order to use ENTRA, you must create an application in Experience Portal and obtain an integration endpoint details, which will be used to communicate with our servers. Those details are secret and should not be exposed by your Front End application.

1. Create the IPA App

Go to 'Access -> Microsoft VC ENTRA App' page and Click 'Create new app'.

2. Fill out the form

1. Choose application name.

2. Select environment.

3. Select a country and document types.

4. Choose one of the possible liveness options:

   • none - no face verification
   • Passive Video Liveness - Simple selfie capture (recommended)
   • Active Liveness - face capture with active challenge (face movements requested, recommended for high security applications only).

5. Choose VC claims

   • Add optional deep-link prefix in case the Microsoft Authenticator SDK is embedded into your own native application.

6. Customize look & feel of your application.

7. Confirm on summary screen.

3. Submit form

After form submission, an application will be created. Afterward you can:

• Generate test QR code - scan the QR code and test document verification yourself without any integration. (You can check the verification details later on the Transactions History page.)
• Display endpoint details - it will allow you to integrate your own application/system with your newly created ENTRA application.
• Delete/Edit configured application.

Integrate IPA for ENTRA in your application 

Integrating IPA for ENTRA is identical to the Standard IPA, except for Step 5 where your End User gets a Verifiable Credential provisioned in their Microsoft Authenticator App at the end of the process.

Verifying Issued Verifiable Credentials

You can now ask your End User to share their Verified Credential with you through a Presentation Request to Microsoft ENTRA. Ref : https://learn.microsoft.com/en-us/entra/verified-id/presentation-request-api. Here are the information details related to the Issued VC to include in your presentation request :