How to integrate the App 

Overview 

On this page you will find out how to integrate your application with IPA. There are 2 possible flows:

  • without MS ENTRA (Identity Proofing Application),
  • with MS ENTRA (Microsoft VC ENTRA Application).

Both flows are similar (from technical side), the same mechanisms operate underneath (Identity Proofing Application - IPA), but last step and output is different, because in ENTRA application Microsoft Azure Verified ID is included.

Integrate using Identity Proofing Application 

Identity Proofing Application flow diagram 

IPA integration_diagram

Let's create IPA application 

In order to use IPA, you must create 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 shared with anyone.

1. Go to 'Access -> Identity Proofing App'

Go to 'Access -> Identity Proofing 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 - document check without face verification
    • Passive Video Liveness - document check with comparison between the submitted self-portrait image and document’s portrait
    • Active Liveness - document check with liveness challenge.
  5. Customize look & feel of your application.
  6. 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 on our “Transactions” page.)
  • Display endpoint details - it will allow you to integrate your own application/system with your newly created IPA application.
  • Delete/edit configured application.

Use generated endpoint in your app 

Integration endpoint details allow you to start integration process and should be used in your own backend application and not be exposed to the end-user. Those endpoint details are secret, do not share it with anyone!

Below sample code blocks shows how you can fully integrate with IPA application based on previously presented diagram.

Step 1: Obtain application access token

Bellow sample allow you to obtain access token via AWS Cognito, which will be required for next step. Access token obtaining must be done via back-end application! See more details in official AWS docs.

Java
1public class IdentityProofingService {
2

3  public String getAccessToken(
4    String cognitoUrl,
5    String clientId,
6    String clientSecret
7  ) throws URISyntaxException, IOException, InterruptedException {
8    var requestBody = Map.of(
9      "grant_type", "client_credentials",
10      "client_id", clientId,
11      "client_secret", clientSecret,
12      "scope", "devportal-entra/session-management"
13    );
14

15    var request = HttpRequest.newBuilder()
16      .uri(new URI(cognitoUrl + "/oauth2/token"))
17      .header("Content-Type", "application/x-www-form-urlencoded")
18      .POST(BodyPublishers.ofString(
19        requestBody.entrySet().stream()
20          .map(entry -> entry.getKey() + "=" + entry.getValue())
21          .collect(Collectors.joining("&"))
22      ))
23      .build();
24

25    var response = HttpClient.newHttpClient().send(request, BodyHandlers.ofString());
26    if (response.statusCode() != 200) {
27      throw new RuntimeException(String.format(
28        "An error occurred while obtaining access token from AWS Cognito, status: %s, body: %s",
29        response.statusCode(),
30        response.body()
31      ));
32    }
33

34    return new ObjectMapper().readTree(response.body()).get("access_token").textValue();
35  }
36}
37

Step 2: Create session

Below sample allow you to create session in previously created IPA application. Previously obtained access token from Cognito AWS is required to make a call. Session creation should be done via back-end application!

Java
1public class IdentityProofingService {
2

3  public UUID createSession(String accessToken, String callbackUrl, String gotoUrl)
4    throws URISyntaxException, IOException, InterruptedException {
5    var objectMapper = new ObjectMapper();
6

7    var requestBody = new CreateSessionDto();
8    requestBody.setCallbackUrl(callbackUrl);
9    requestBody.setGotoUrl(gotoUrl);
10

11    var request = HttpRequest.newBuilder()
12      .uri(new URI("https://rp-handler.did.idemia.io/api/v1/sessions"))
13      .header("Content-Type", "application/json")
14      .header("Authorization", "Bearer " + accessToken)
15      .POST(BodyPublishers.ofString(objectMapper.writeValueAsString(requestBody)))
16      .build();
17

18    var response = HttpClient.newHttpClient().send(request, BodyHandlers.ofString());
19    if (response.statusCode() != 201) {
20      throw new RuntimeException(String.format(
21        "An error occurred while creating IPA session via RP-Handler, status: %s, body: %s",
22        response.statusCode(),
23        response.body()
24      ));
25    }
26

27    return UUID.fromString(objectMapper.readTree(response.body()).findValue("sessionId").textValue());
28  }
29}
30

31public class CreateSessionDto {
32

33  private String callbackUrl;
34  private String gotoUrl;
35

36  public String getCallbackUrl() {
37    return callbackUrl;
38  }
39

40  public void setCallbackUrl(String callbackUrl) {
41    this.callbackUrl = callbackUrl;
42  }
43

44  public String getGotoUrl() {
45    return gotoUrl;
46  }
47

48  public void setGotoUrl(String gotoUrl) {
49    this.gotoUrl = gotoUrl;
50  }
51}
52

Step 3: Authenticate and redirect

Below sample allow you to create session in previously created IPA application. Obtained access token from Cognito AWS is required to make a call. Authentication should be done via front-end application, because as a result user will be redirected to previously configured IPA application.

Java
1public class IdentityProofingService {
2

3  public String authenticate(UUID sessionId) throws URISyntaxException, IOException, InterruptedException {
4    var request = HttpRequest.newBuilder()
5      .uri(new URI("https://rp-handler.did.idemia.io/api/v1/authenticate?session-id=" + sessionId))
6      .GET()
7      .build();
8

9    var response = HttpClient.newHttpClient().send(request, BodyHandlers.discarding());
10    if (response.statusCode() != 302) {
11      throw new RuntimeException(String.format(
12        "An error occurred during session authentication via RP-Handler, status: %s, body: %s",
13        response.statusCode(),
14        response.body()
15      ));
16    }
17

18    return response.headers().firstValue("Location").orElseThrow();
19  }
20}
21

Step 4: Identity Proofing process

In this step user will follow instructions in IPA application, to which he was redirected. Once completed, user will be redirected to gotoUrl provided during session creation and POST request will be sent to provided callbackUrl during session creation. Callback endpoint must be exposed from back-end application! Below sample allow you to retrieve callback request.

Java
1

2@RestController
3public class IdentityProofingController {
4

5  @PostMapping("/callback")
6  public void callback(@RequestBody ProofingResultDto proofingResult) {
7    // TODO: client specific implementation
8  }
9}
10

11public class ProofingResultDto {
12

13  private String applicationId;
14  private String identityId;
15  private String sessionId;
16  private String proofUrl;
17  private Instant timestamp;
18

19  public String getApplicationId() {
20    return applicationId;
21  }
22

23  public void setApplicationId(String applicationId) {
24    this.applicationId = applicationId;
25  }
26

27  public String getIdentityId() {
28    return identityId;
29  }
30

31  public void setIdentityId(String identityId) {
32    this.identityId = identityId;
33  }
34

35  public String getSessionId() {
36    return sessionId;
37  }
38

39  public void setSessionId(String sessionId) {
40    this.sessionId = sessionId;
41  }
42

43  public String getProofUrl() {
44    return proofUrl;
45  }
46

47  public void setProofUrl(String proofUrl) {
48    this.proofUrl = proofUrl;
49  }
50

51  public Instant getTimestamp() {
52    return timestamp;
53  }
54

55  public void setTimestamp(Instant timestamp) {
56    this.timestamp = timestamp;
57  }
58}
59

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 onboarded 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):

ENTRA azure_configuration

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 provide the entire process including usage of the sample app in this tutorial: Configure Microsoft ENTRA Verified ID verifier.

Microsoft VC ENTRA Application flow diagram 

ENTRA integration_diagram

Let's create ENTRA application 

In order to use ENTRA, you must create 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 shared with anyone.

1. Go to 'Access -> Microsoft VC ENTRA 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 - document check without face verification
    • Passive Video Liveness - document check with comparison between the submitted self-portrait image and document’s portrait
    • Active Liveness - document check with liveness challenge.
  5. Choose VC claims and optional deep-link prefix.
  6. Customize look & feel of your application.
  7. Customize landing page and the Terms & Conditions.
  8. 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 on our “Transactions” page.)
  • Display endpoint details - it will allow you to integrate your own application/system with your newly created ENTRA application.
  • Delete/edit configured application.

Use generated endpoint in your app 

Integration endpoint details allow you to start integration process and should be used in your own backend application and not be exposed to the end-user. Those endpoint details are secret, do not share it with anyone!

Below sample code blocks shows how you can fully integrate with ENTRA application based on previously presented diagram.

Step 1: Obtain application access token

Bellow sample allow you to obtain access token via AWS Cognito, which will be required for next step. Access token obtaining must be done via back-end application! See more details in official AWS docs.

Java
1public class IdentityProofingService {
2

3  public String getAccessToken(
4    String cognitoUrl,
5    String clientId,
6    String clientSecret
7  ) throws URISyntaxException, IOException, InterruptedException {
8    var requestBody = Map.of(
9      "grant_type", "client_credentials",
10      "client_id", clientId,
11      "client_secret", clientSecret,
12      "scope", "devportal-entra/session-management"
13    );
14

15    var request = HttpRequest.newBuilder()
16      .uri(new URI(cognitoUrl + "/oauth2/token"))
17      .header("Content-Type", "application/x-www-form-urlencoded")
18      .POST(BodyPublishers.ofString(
19        requestBody.entrySet().stream()
20          .map(entry -> entry.getKey() + "=" + entry.getValue())
21          .collect(Collectors.joining("&"))
22      ))
23      .build();
24

25    var response = HttpClient.newHttpClient().send(request, BodyHandlers.ofString());
26    if (response.statusCode() != 200) {
27      throw new RuntimeException(String.format(
28        "An error occurred while obtaining access token from AWS Cognito, status: %s, body: %s",
29        response.statusCode(),
30        response.body()
31      ));
32    }
33

34    return new ObjectMapper().readTree(response.body()).get("access_token").textValue();
35  }
36}
37

Step 2: Create session

Below sample allow you to create session in previously created ENTRA application. Previously obtained access token from Cognito AWS is required to make a call. Session creation should be done via back-end application!

Java
1public class IdentityProofingService {
2

3  public UUID createSession(String accessToken, String callbackUrl)
4    throws URISyntaxException, IOException, InterruptedException {
5    var objectMapper = new ObjectMapper();
6

7    var requestBody = new CreateSessionDto();
8    requestBody.setCallbackUrl(callbackUrl);
9

10    var request = HttpRequest.newBuilder()
11      .uri(new URI("https://rp-handler.did.idemia.io/api/v1/sessions"))
12      .header("Content-Type", "application/json")
13      .header("Authorization", "Bearer " + accessToken)
14      .POST(BodyPublishers.ofString(objectMapper.writeValueAsString(requestBody)))
15      .build();
16

17    var response = HttpClient.newHttpClient().send(request, BodyHandlers.ofString());
18    if (response.statusCode() != 201) {
19      throw new RuntimeException(String.format(
20        "An error occurred while creating IPA session via RP-Handler, status: %s, body: %s",
21        response.statusCode(),
22        response.body()
23      ));
24    }
25

26    return UUID.fromString(objectMapper.readTree(response.body()).findValue("sessionId").textValue());
27  }
28}
29

30public class CreateSessionDto {
31

32  private String callbackUrl;
33

34  public String getCallbackUrl() {
35    return callbackUrl;
36  }
37

38  public void setCallbackUrl(String callbackUrl) {
39    this.callbackUrl = callbackUrl;
40  }
41}
42

Step 3: Authenticate and redirect

Below sample allow you to create session in previously created ENTRA application. Obtained access token from Cognito AWS is required to make a call. Authentication should be done via front-end application, because as a result user will be redirected to previously configured ENTRA application.

Java
1public class IdentityProofingService {
2

3  public String authenticate(UUID sessionId) throws URISyntaxException, IOException, InterruptedException {
4    var request = HttpRequest.newBuilder()
5      .uri(new URI("https://rp-handler.did.idemia.io/api/v1/authenticate?session-id=" + sessionId))
6      .GET()
7      .build();
8

9    var response = HttpClient.newHttpClient().send(request, BodyHandlers.discarding());
10    if (response.statusCode() != 302) {
11      throw new RuntimeException(String.format(
12        "An error occurred during session authentication via RP-Handler, status: %s, body: %s",
13        response.statusCode(),
14        response.body()
15      ));
16    }
17

18    return response.headers().firstValue("Location").orElseThrow();
19  }
20}
21

Step 4: Identity Proofing process

In this step user will follow instructions in ENTRA application, to which he was redirected. Once completed, user will be redirected to application from deep-link and POST request will be sent to provided callbackUrl during session creation. Callback endpoint must be exposed from back-end application! Below sample allow you to retrieve callback request.

Java
1

2@RestController
3public class IdentityProofingController {
4

5  @PostMapping("/callback")
6  public void callback(@RequestBody ProofingResultDto proofingResult) {
7    // TODO: client specific implementation
8  }
9}
10

11public class ProofingResultDto {
12

13  private String applicationId;
14  private String identityId;
15  private String sessionId;
16  private String proofUrl;
17  private Instant timestamp;
18

19  public String getApplicationId() {
20    return applicationId;
21  }
22

23  public void setApplicationId(String applicationId) {
24    this.applicationId = applicationId;
25  }
26

27  public String getIdentityId() {
28    return identityId;
29  }
30

31  public void setIdentityId(String identityId) {
32    this.identityId = identityId;
33  }
34

35  public String getSessionId() {
36    return sessionId;
37  }
38

39  public void setSessionId(String sessionId) {
40    this.sessionId = sessionId;
41  }
42

43  public String getProofUrl() {
44    return proofUrl;
45  }
46

47  public void setProofUrl(String proofUrl) {
48    this.proofUrl = proofUrl;
49  }
50

51  public Instant getTimestamp() {
52    return timestamp;
53  }
54

55  public void setTimestamp(Instant timestamp) {
56    this.timestamp = timestamp;
57  }
58}
59