Microsoft Entra Verified ID

Start here

This guide presents a technical overview of our Microsoft Entra Verified ID solution, available for integration through Workflow Studio.

Introduction

Integrating Microsoft Entra Verified ID through Workflow Studio offers a robust solution for the issuance and validation of verified credentials. Leveraging digital verified credentials allows you to streamline identity verification journeys with a seamless user experience, while still maintaining the highest level of fraud prevention and security.

The issuance of cryptographically protected verified credentials - such as employee badges or membership cards stored securely in digital wallets - streamlines new customer onboarding, account recovery and moments where step-up authentication is required.

The Entrust Identity Verification SDKs work dynamically with Workflow Studio to control the end-user experience, guiding applicants through the process of issuing or presenting previously registered verified credentials. Users will be prompted to verify their identity either by presenting an existing credential, or creating a new credential following a document and biometric verification. The Entrust Identity Verification SDKs will generate either a QR code that Web applicants will scan, or a button mobile applicants will click to accept and store a newly issued credential or to validate an existing credential in the Microsoft Authenticator mobile app.

The advantage of integrating Microsoft Entra Verified ID through Workflow Studio is the ability to easily incorporate the issuance and presentation of verified credentials with identity verification, all within the intuitive Workflow Builder environment. In particular, you can harness the power of Entrust's encrypted biometric tokens that allows you to enroll users with facial biometrics or authenticate users with previously enrolled facial biometrics.

Issue verified credential task

To issue a verified credential, a dedicated Issue verified credential task should be added to a Studio workflow in the Workflow Builder, in combination with document and biometric verifications.

The Issue verified credential task has several configuration options available, including:

• credential type - the identifier in the rules definition distinguishing a verified credential's schema from others, ensuring it works across issuers and verifiers (a URI prefix is recommended for global uniqueness)
• manifest URL - the credential schema that defines the credential's structure, visual appearance and issuance rules in JSON format
• pin length - determines the length of the security pin code the applicant must enter in their Microsoft Authenticator app during the issuance process. By default, the pin length is 6 digits, with a minimum of 4 digits and a maximum of 16 digits

See the defining a new credential section for more information on creating credential definitions, and how to obtain the manifest URL and credential type values.

Configuration options for the Issue verified credential task

The workflow task takes data as inputs captured during the Studio workflow, including the applicant's first and last name (required), as well as the optional inputs of the applicant's date of birth, identity document type, a photo id (referencing the captured biometric media) or any encrypted biometric token data. Upon successful identity verification, the task initiates the issuance process with Microsoft Entra. It generates a verified credential offer, presented as a QR code (for Web users) or a button (for mobile users), allowing the applicant to claim and save the credential in their Microsoft Authenticator wallet.

Input data for the Issue verified credential task

Below you will find an example of a Studio workflow to issue a verified credential:

Present verified credential task

To validate a previously issued verified credential, a dedicated Present verified credential task should be added to a Studio workflow in the Workflow Builder.

The Present verified credential task has several configuration options available, including:

• credential type - the identifier in the rules definition distinguishing a verified credential's schema from others, ensuring it works across issuers and verifiers (a URI prefix is recommended for global uniqueness). This should match the credential type value configured in the Issue verified credential task
• show introduction screen - a toggle to enable or disable the SDK introduction screen. When enabled, an additional screen asks the end user if they already have a verified ID or not. If the user selects that they do have a verified ID, they will be prompted to present it. Otherwise, the task will end early with a consider result. When disabled, this screen is skipped, and the end user must present an already issued credential

The workflow task prompts the applicant to present and share from their Microsoft Authenticator wallet an existing verified credential via a QR code (for Web applicants) or a button (for mobile applicants), which initiates communication with Microsoft Entra for authentication.

Below you will find an example of a Studio workflow to present a verified credential:

Interpreting results

The Present verified credential task can return a result of clear or consider:

The task also provides breakdown results that offer more granular information about what occurred during the presentation flow:

• user has credential - If the user selected "I don't have a Verified ID" on the introduction screen, this breakdown returns consider.
• user presented credential - If the user failed to present their credential, this breakdown returns consider.

If the user has and successfully presents their verified credential, both breakdown results will be clear, as well as the overall task result. These breakdown results can be used in Logic tasks to determine the appropriate next steps, such as whether to trigger a verified credential issuance flow for users who don't yet have a credential.

Combined verified credential workflow

A single Studio workflow can be created that combines presentation and issuance of a verified credential. This can be done by starting the workflow with the Present verified credential task and enabling the SDK introduction screen option in the task configuration. The user will be asked if they already have a verified credential or not.

If the user presses the I have a Verified ID button, they will be prompted to present it. If the user presses the Create new Verified ID button, the Present verified credential task will return a consider result.

Issue or present a verified credential selection screen in the SDK

As illustrated in the Studio workflow diagram below, you can use a Logic task to determine whether the consider result is caused by button selection or the failed presentation of a valid credential.

Verified credentials and Authenticate biometrics: motion

The verified credential tasks support biometric authentication via Entrust's Authenticate biometrics: motion solution. When used with Verified ID, the user's encrypted biometric token will be securely stored as a claim of the user's Verified ID in the Microsoft Authenticator app wallet. When the Verified ID is presented, the claim is returned and can be used to complete biometric authentication. This provides a strong form of multi-factor authentication (MFA):

• something you have - verified IDs are secure, tamper-resistant and attestable but only prove that the user has possession of the device
• something you are - Authenticate biometrics: motion ensures that the person presenting the credential is the same person that it was issued to

Below you will find a combined verified credential and biometric authentication workflow:

Configuring Microsoft Entra

In order to use the Verified ID solution with Entrust Studio, you must configure your Microsoft Entra account and create a new credential definition.

Prerequisites

A tenant configured for Microsoft Entra Verified ID service.

If you don't have an existing tenant, you can create an Azure account for free.

Workflow Studio configuration

The following values will need to be provided to Entrust upon configuring the Entra tenant. Keep a record of these fields as you configure Entra ID to enable your integration:

• Tenant ID
• Client ID
• Client Secret
• Decentralized identifier (DID)

Entra configuration

1. Register a new application in Microsoft Entra ID. Record the Tenant ID and Client ID once the application is registered
2. Grant API permissions to the application with the VerifiableCredential.Create.All permission
3. Protect the application with a Client Secret and record the value
4. Record your Decentralized identifier (DID) from your organization settings

Defining a new credential

When creating your verified credential definition in Microsoft Entra, you'll need to define both a display definition and a rules definition. The examples below can be used as a baseline for your credential definitions.

Display definition

The display definition controls how your credential appears in the Microsoft Authenticator wallet. The example below should be adjusted to fit your organization's branding and use case.

1{
2  "locale": "en-US",
3  "card": {
4    "title": "Verified Credential",
5    "backgroundColor": "#800080",
6    "description": "This is your verified credential.",
7    "issuedBy": "Your Organization",
8    "textColor": "#FFFFFF",
9    "logo": {
10      "description": "Organization logo",
11      "uri": "https://didcustomerplayground.z13.web.core.windows.net/VerifiedCredentialExpert_icon.png"
12    }
13  },
14  "consent": {
15    "instructions": "Please click accept to add this credential to your wallet.",
16    "title": "Do you want to create a verified credential?"
17  },
18  "claims": [
19    {
20      "claim": "vc.credentialSubject.firstName",
21      "label": "First Name",
22      "type": "String"
23    },
24    {
25      "claim": "vc.credentialSubject.lastName",
26      "label": "Last Name",
27      "type": "String"
28    },
29    {
30      "claim": "vc.credentialSubject.dateOfBirth",
31      "label": "Date of Birth",
32      "type": "String"
33    },
34    {
35      "claim": "vc.credentialSubject.documentType",
36      "label": "Document Type",
37      "type": "String"
38    },
39    {
40      "claim": "vc.credentialSubject.photo",
41      "label": "Photo",
42      "type": "image/png;base64url"
43    },
44    {
45      "claim": "vc.credentialSubject.encryptedBiometricToken",
46      "label": "Encrypted Biometric Token",
47      "type": "String"
48    }
49  ]
50}

Rules definition

The rules definition specifies how claims are mapped and the credential type to be issued. The mapping in your credential definition should match the example below to ensure compatibility with Workflow Studio.

1{
2  "attestations": {
3    "idTokenHints": [
4      {
5        "mapping": [
6          {
7            "inputClaim": "firstName",
8            "outputClaim": "firstName",
9            "required": true,
10            "indexed": false
11          },
12          {
13            "inputClaim": "lastName",
14            "outputClaim": "lastName",
15            "required": true,
16            "indexed": false
17          },
18          {
19            "inputClaim": "dateOfBirth",
20            "outputClaim": "dateOfBirth",
21            "required": false,
22            "indexed": false
23          },
24          {
25            "inputClaim": "documentType",
26            "outputClaim": "documentType",
27            "required": false,
28            "indexed": false
29          },
30          {
31            "inputClaim": "photo",
32            "outputClaim": "photo",
33            "required": false,
34            "indexed": false
35          },
36          {
37            "inputClaim": "encryptedBiometricToken",
38            "outputClaim": "encryptedBiometricToken",
39            "required": false,
40            "indexed": false
41          }
42        ],
43        "required": true
44      }
45    ]
46  },
47  "vc": {
48    "type": [
49      "<CredentialNameHere>"
50    ]
51  }
52}

Using credential details in Studio

Once your credential definition is created in Microsoft Entra, you'll need to copy the Manifest URL and Credential Type values to configure the Issue verified credential and Present verified credential tasks in Workflow Studio. These values can be found in your credential's details page in Microsoft Entra.

Additional useful references

Verifiable Credentials Quick Setup

Building a Credential Definition

Integrate ID Token claims