> For the complete documentation index, see [llms.txt](/llms.txt)
# 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.
## Solution overview
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](/guide/biometric-authentication/#biometric-authentication) that allows you to enroll users with facial biometrics or authenticate users with previously enrolled facial biometrics.
## 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](https://azure.microsoft.com/en-us/pricing/purchase-options/azure-account) for free.
### Workflow Studio configuration
The following values will need to be configured in Workflow Studio upon setting up your 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)
You can find the configuration page in Workflow Studio under **Developers -> Microsoft Entra**.
_Microsoft Entra account configuration page in Workflow Studio_
### 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 by selecting the **Verifiable Credentials Service Request** API with the `VerifiableCredential.Create.All` application permission, and the **Verifiable Credentials Service Admin** API with the `VerifiableCredential.Contract.Read` and `VerifiableCredential.Authority.Read` application permissions
3. Protect the application with a **Client Secret** and record the value
4. Record your **Decentralized identifier (DID)** from **Verified ID > Organization settings** (available after completing the Verified ID setup)
> ℹ️ **Note:** If your Microsoft Entra app client secret expires or is rotated without updating your integration, Verified ID issuance or presentation in the SDK will fail and end users will see `Unable to continue with your Verified ID issuance` or `Unable to continue with your Verified ID presentation`. Generate a new client secret in Microsoft Entra and update the client secret in Workflow Studio.
### 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 following input claims are supported through Studio:
| Claim | Description | Required |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `firstName` | The applicant's first name | Yes |
| `lastName` | The applicant's last name | Yes |
| `dateOfBirth` | The applicant's date of birth | No |
| `email` | The applicant's email address | No |
| `uniqueId` | A stable identifier used to uniquely identify the person or credential | No |
| `documentType` | The type of identity document used during verification | No |
| `photo` | A photo of the applicant, referencing captured biometric media | No |
| `encryptedBiometricToken` | An encrypted biometric token for use with [Authenticate biometrics](/guide/microsoft-verified-id/#verified-credentials-and-authenticate-biometrics) | No |
> ℹ️ **Note:** If the selected credential configuration includes the `uniqueId` claim and you do not explicitly map a `Unique Id` workflow input, Entrust Studio will use the applicant's `Applicant ID` as the `uniqueId` value during issuance.
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.
> ℹ️ **Note:** The `claims` field in your credential definition specifies which data attributes will be included in the credential. Including all of these claims in the credential allows you to manage the credential solely through Workflow Studio, without needing to modify the credential definition for different use cases.
```json
{
"locale": "en-US",
"card": {
"title": "Verified Credential",
"backgroundColor": "#800080",
"description": "This is your verified credential.",
"issuedBy": "Your Organization",
"textColor": "#FFFFFF",
"logo": {
"description": "Organization logo",
"uri": "https://didcustomerplayground.z13.web.core.windows.net/VerifiedCredentialExpert_icon.png"
}
},
"consent": {
"instructions": "Please click accept to add this credential to your wallet.",
"title": "Do you want to create a verified credential?"
},
"claims": [
{
"claim": "vc.credentialSubject.firstName",
"label": "First Name",
"type": "String"
},
{
"claim": "vc.credentialSubject.lastName",
"label": "Last Name",
"type": "String"
},
{
"claim": "vc.credentialSubject.dateOfBirth",
"label": "Date of Birth",
"type": "String"
},
{
"claim": "vc.credentialSubject.email",
"label": "Email",
"type": "String"
},
{
"claim": "vc.credentialSubject.uniqueId",
"label": "Unique ID",
"type": "String"
},
{
"claim": "vc.credentialSubject.documentType",
"label": "Document Type",
"type": "String"
},
{
"claim": "vc.credentialSubject.photo",
"label": "Photo",
"type": "image/png;base64url"
},
{
"claim": "vc.credentialSubject.encryptedBiometricToken",
"label": "Encrypted Biometric Token",
"type": "String"
}
]
}
```
#### Rules definition
The rules definition specifies how claims are mapped and the credential type value for the credential. The mapping in your credential definition should match the example below to ensure compatibility with Workflow Studio.
```json
{
"attestations": {
"idTokenHints": [
{
"mapping": [
{
"inputClaim": "firstName",
"outputClaim": "firstName",
"required": true,
"indexed": false
},
{
"inputClaim": "lastName",
"outputClaim": "lastName",
"required": true,
"indexed": false
},
{
"inputClaim": "dateOfBirth",
"outputClaim": "dateOfBirth",
"required": false,
"indexed": false
},
{
"inputClaim": "email",
"outputClaim": "email",
"required": false,
"indexed": false
},
{
"inputClaim": "uniqueId",
"outputClaim": "uniqueId",
"required": false,
"indexed": false
},
{
"inputClaim": "documentType",
"outputClaim": "documentType",
"required": false,
"indexed": false
},
{
"inputClaim": "photo",
"outputClaim": "photo",
"required": false,
"indexed": false
},
{
"inputClaim": "encryptedBiometricToken",
"outputClaim": "encryptedBiometricToken",
"required": false,
"indexed": false
}
],
"required": true
}
]
},
"vc": {
"type": [
""
]
}
}
```
#### Using credentials in Workflow Studio
Once your credential definition is created in Microsoft Entra, it appears in the **Credential** dropdown list in Workflow Studio. Select the same credential in the Issue verified credential and Present verified credential tasks.
### Additional useful references
[Verifiable Credentials Quick Setup](https://learn.microsoft.com/en-us/entra/verified-id/verifiable-credentials-configure-tenant-quick)
[Building a Credential Definition](https://learn.microsoft.com/en-us/entra/verified-id/credential-design)
[Integrate ID Token claims](https://learn.microsoft.com/en-us/entra/verified-id/how-to-use-quickstart-idtoken)
## 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 - select a credential definition from the **Credential** dropdown list. This list is populated with the credentials you have created in your Microsoft Entra Verified ID tenant
- 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](#defining-a-new-credential) section for how to create a credential definition in Microsoft Entra so it appears in the **Credential** dropdown list.
_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, document expiry date, a photo ID (referencing the captured biometric media) or any [encrypted biometric token data](/getting-started/workflow-studio-product/#enroll-biometrics-task). 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.
> ℹ️ **Note:** You can set the `Date of Expiry` input to cap the issued credential's expiration date. If the date is earlier than the expiration date derived from the `validityInterval` value in your Microsoft Entra credential contract, the credential expires on the document expiration date instead. This works only if your contract allows validity overrides at issuance by setting the `allowOverrideValidityOnIssuance` flag. If the document expiry date is in the past, the issuance request is rejected. See [Microsoft's credential contract documentation](https://learn.microsoft.com/en-us/entra/verified-id/admin-api#contract-type) for details on enabling credential validity overrides.
_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 - select a credential definition from the **Credential** dropdown list. This should match the credential selected 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`:
| Verification result | Logic |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| clear | A verified credential was successfully presented. The applicant had a credential and successfully shared it for verification. |
| consider | A verified credential was not presented. Either the applicant indicated they don't have a credential, or they failed to present it. |
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.
## Revoking a credential
Credentials can be revoked through the Microsoft Entra Verified ID UI by searching for an indexed claim in the credential definition. We recommend using the `uniqueId` claim, which can be mapped to a stable identifier from your own system, such as a customer ID or employee ID.
To support this, mark the `uniqueId` entry in your rules definition mapping as both required and indexed:
```json
{
"inputClaim": "uniqueId",
"outputClaim": "uniqueId",
"required": true,
"indexed": true
}
```
The `uniqueId` claim can be mapped during issuance from [workflow input data](/getting-started/workflow-studio-product/#workflow-input-data).
## 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
The verified credential tasks support biometric authentication via Entrust's [Authenticate biometrics](/guide/biometric-authentication/) 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 ensures that the person presenting the credential is the same person that it was issued to
> ⚠️ **Warning:** In order to use the biometric authentication solution, a `customer_user_id` must be set during workflow run creation and re-used for any subsequent workflow runs. This customer user ID will be used to uniquely identify the end user, regardless of the applicant ID used for the workflow run. It will default to the applicant ID if not specified at workflow creation.
>
> Review the [biometric authentication guide](/guide/biometric-authentication/) to fully understand the implementation requirements and best practices for this integration.
Below you will find a combined verified credential and biometric authentication workflow:
