Integration with Microsoft Entra Verified ID
Regula IDV Platform supports API-based integration with Microsoft Entra Verified ID service to perform issuance and presentation of the decentralized digital credentials. This page explains available integration flows, their implementation, and configuration parameters.
Overview
Microsoft Entra Verified ID is a verifiable credentials service within the Microsoft Entra product family. It enables organizations to issue and verify trusted digital credentials that contain attested claims about a verified person.
Microsoft Entra Verified ID supports a decentralized identity model in accordance with the Open Identity Standards, where trust is based on a portable, cryptographically signed digital credential rather than on a continuous request to a central identity provider.
The decentralized identity model involves several roles:
- Issuer—the organization that issues the digital credential. The issuer defines the credential type, maps verified attributes to credential claims, and controls credential issuance. Microsoft Entra Verified ID signs the credential using the issuer’s decentralized identifier (DID) and associated cryptographic keys.
- Holder—the person who receives the issued digital credential and stores it in a digital wallet app, such as Microsoft Authenticator. The holder controls when and where to present the credential to a verifier.
- Verifier—the organization that requests and verifies the digital credential presented by the holder. The verifier validates the credential, checks the issuer’s DID and signature, and evaluates the presented claims according to its verification policy.
- Microsoft Entra Verified ID—the verifiable credentials service that manages the credential issuance and verification flow. It performs issuance and signing on behalf of the issuer, using the issuer’s DID and signing keys, and helps the verifier validate presented credentials.
- Regula IDV Platform—the identity verification provider that verifies the person’s identity evidence, such as an identity document, biometric data, or liveness check. The IDV Platform returns verification results that the issuer can map to claims in the digital credential.
The following sections describe two sample integration flows, in which Regula IDV Platform acts as both the issuer and verifier of digital verifiable credentials.
Prerequisites
Microsoft Entra side
Because Verified ID is part of the Microsoft Entra product family, you need a configured Entra tenant (also known as an Azure tenant) to launch the infrastructure. For details, see Set up a new Microsoft Entra tenant.
In your Entra tenant, enable and configure the Verified ID service. For details, see the Advanced Microsoft Entra Verified ID setup. This step includes configuring Azure Key Vault, registering a DID, and verifying the domain.
Then set up the contract for the verifiable credential that the system will issue and verify. Configure both definition sections:
- Rules—what claims the person needs to provide before they receive a digital credential.
- Display—how a digital credential card is branded and claims are styled in the digital wallet app.
For details, see Customize your verifiable credentials.
To securely interact with Microsoft services and APIs, register your application (referred to as Onboarding App) in Entra ID. For details, see the Microsoft documentation articles Register an application in Entra ID and Configure the verifiable credentials app. Grant the required API permissions for your application to send issuance requests, presentation requests, or both. For details, see Grant permissions to get access tokens.
Add a client secret to your registered application for identification purposes. For details, see the article Add a credential to your application.
Regula IDV Platform side
For Entra Verified ID to issue a legitimate digital credential, Regula IDV Platform provides the end-to-end identity verification.
Deploy and configure the IDV Platform, according to your specific server-side setup. Prepare the workflow based on your business needs.
Set up the Onboarding App via the Platform portal.
Digital wallet
Install the digital wallet Microsoft Authenticator app. It stores verifiable digital credentials, issued by Entra Verified ID on behalf of your organization. You can also present the digital credential from Microsoft Authenticator, based on requested claims.
Access Configuration Parameters
The integration with Microsoft Entra Verified ID is configured in scope of the ms_verified_request action. This action supports two user flows: issuance and presentation. For details, see the Flows section.
The following parameters define access to the Entra tenant and Verified ID service. These parameters are applied to both issuance and presentation flows. You can set values via the Platform portal or directly in the workflow YAML file.
- Azure Tenant ID
| Parameter in Platform portal UI | Azure Tenant ID |
| Parameter in workflow YAML file | azTenantId |
| Format | GUID format, for example 03c50625-01bf-4d75-8b56-16be0190dc4f |
| Description | The unique identifier of your Azure AD tenant. |
| Where to find in Microsoft Azure Portal | Azure Portal → Microsoft Entra ID → Overview → Tenant ID |
| Requirement | Required |
- Azure Client ID
| Parameter in Platform portal UI | Azure Client ID |
| Parameter in workflow YAML file | azClientId |
| Format | GUID format, for example 274d8a85-4541-4418-b2fd-c791a4278761 |
| Description | The Application (client) ID of your App Registration. |
| Where to find in Microsoft Azure Portal | Azure Portal → App Registrations → Your App → Overview → Application (client) ID |
| Requirement | Required |
- Azure Client Secret
The client secret must be stored as an encrypted platform parameter—never in the workflow YAML directly. The value is only visible on creation, so store it securely.
To register the parameter:
- In the Platform portal go to Applications → [Your Application] → Parameters.
- Create a named parameter, for example
entra_client_secret. - Paste the client secret value from Entra and save the parameter.
The IDV workflow references the value as {{ parameters.entra_client_secret }}
| Parameter in Platform portal UI | Azure Client Secret |
| Parameter in workflow YAML file | azClientSecret |
| Format | Platform parameter reference, for example {{ parameters.entra_client_secret }} |
| Description | The client secret value for your App Registration, stored as an encrypted platform parameter. |
| Where to find in Microsoft Azure Portal | Azure Portal → App Registrations → Your App → Certificates & Secrets → Client Secrets → Value |
| Requirement | Required |
- Authority
| Parameter in Platform portal UI | Authority |
| Parameter in workflow YAML file | authority |
| Format | Platform parameter reference, for example did:web:<your_domain> |
| Description | The DID of your organization as the credential issuer. |
| Where to find in Microsoft Azure Portal | Azure Portal → Verified ID → Organization settings → Decentralized identifier (DID) |
| Requirement | Required |
Flows
Regula IDV Platform provides the full range of identity verification capabilities that fit into two general flows:
- Issuance (Enrollment)—enrolling the person into the system with an identity check and issuing the verifiable credential, stored in the digital wallet app.
- Presentation (Verification)—validating a previously issued digital credential according to the claims, requested by the verifier and presented from the digital wallet with the holder's consent.
Note
The simplified flows in this section show Regula IDV Platform acting as both the credential issuer and verifier. In production, these roles are typically performed by separate organizations, while the platform handles identity verification only.
Issuance (Enrollment)
The Enrollment flow issues a verifiable credential to the person's digital wallet app. After the person completes document verification, the IDV Platform calls the Entra Verified ID Request Service to generate a deep link. The person opens the link in Microsoft Authenticator or a compatible digital wallet, reviews the credential claims, and accepts them. The platform is notified asynchronously and transitions the session to the success state.
Sequence diagram
See the sequence diagram of the entire Enrollment flow (click to enlarge).
Sample configuration
See the sample configuration of the Issuance flow via the workflow YAML.
actions:
- id: MS_VERIFIED_ISSUANCE
name: MS_VERIFIED_ISSUANCE
type: ms_verified_request
options:
type: issuance # Must be "issuance" for the Enroll flow
config:
azTenantId: "<your_tenant_id>"
azClientId: "<your_client_id>"
azClientSecret: "{{ parameters.entra_client_secret }}"
authority: "did:web:<your_domain>"
manifest: "<manifest_url>"
credentialType: "<verifiable_credential_type>"
includeQRCode: true
registration:
clientName: "<organization_name>"
purpose: "To issue a digital identity credential"
claims:
given_name: '{{ FIRST_NAME | default("") }}'
family_name: '{{ SURNAME | default("") }}'
picture: "{% if DOC_PHOTO is defined and DOC_PHOTO %}{{ DOC_PHOTO | loadFromStorage | imageToJpeg | b64encode }}{% endif %}"
document_number: '{{ DOCUMENT_NUMBER | default("") }}'
birthdate: '{{ DATE_OF_BIRTH | default("") }}'
Parameters
See the Issuance flow specific configuration parameters below.
- Manifest
| Parameter in Platform portal UI | Manifest |
| Parameter in workflow YAML file | manifest |
| Format | https://verifiedid.did.msidentity.com/v1.0/tenants/<tenant_id>/verifiableCredentials/contracts/<contract_id>/manifest |
| Description | URL of the Verified Credential contract manifest. Defines the credential schema, display rules, and attestation rules. |
| Where to find in Microsoft Azure Portal | Azure Portal → Verified ID → Credentials → [Your Credential] → Issue credential → Manifest URL |
| Requirement | Required |
- Credential Type
| Parameter in Platform portal UI | Credential Type |
| Parameter in workflow YAML file | credentialType |
| Format | For example VerifiableCredential |
| Description | The verifiable credential type string that must match the vcTypes field in the manifest contract. Used to select a specific contract when multiple exist under one manifest. |
| Where to find in Microsoft Azure Portal | Azure Portal → Verified ID → Credentials → Type |
| Requirement | Optional |
- Claims
| Parameter in workflow YAML file | claims |
| Format | dictionary (key-value pairs) |
| Description | Key-value pairs that populate the credential claims. Values support Jinja2 templates resolved from the session properties. |
| Where to find in Microsoft Azure Portal | Keys must match the inputClaim names defined in the contract's Rules Definition (attestation mappings). |
| Requirement | Optional, but required if using ID Token Hints attestation. |
- Registration Client Name
| Parameter in Platform portal UI | Registration Client Name |
| Parameter in workflow YAML file | registration → clientName |
| Format | Free-form string |
|---|---|
| Description | Name of your organization shown to the person in the digital wallet app during a credential issuance. |
| Requirement | Optional |
- Registration Purpose
| Parameter in Platform portal UI | Registration Purpose |
| Parameter in workflow YAML file | registration → purpose |
| Format | Free-form string |
| Description | Short description message displayed to the person explaining why the credential is being issued. |
| Requirement | Optional |
- Include QR Code
| Parameter in Platform portal UI | Include QR Code |
| Parameter in workflow YAML file | includeQRCode |
| Format | boolean (true or false) |
| Description | Whether to include a Base64-encoded QR code image in the response (from the Microsoft Entra side). Useful for web flows where the person needs to scan from a desktop browser. |
| Requirement | Optional |
- Issuance PIN Code Length
| Parameter in workflow YAML file | issuancePinCodeLength |
| Format | integer (4-16) |
| Description | Length of a numeric PIN (4–16 digits) that the person must enter in the wallet app to complete issuance. Increases security. Only valid when claims are also provided. |
| Requirement | Optional |
- Expiration Date
| Parameter in workflow YAML file | expirationDate |
| Format | time string (ISO 8601 extended format) |
| Description | If provided (and claims are present), the issued credential will expire at this date-time. |
| Requirement | Optional |
Callback events
Regula IDV Platform receives asynchronous notifications from Microsoft Entra Verified ID at the POST /api/v1/integration/ms-verified-id/session/{session_id}/callback endpoint.
Configure handlers in the events → onMsVerifiedIdCallback section of the workflow for each of the statuses described in the following table.
Status onMsVerifiedIdCallback → status |
Description | Recommended action |
|---|---|---|
issuance_request_retrieved |
The person's digital wallet app fetched the issuance request (the person opened the deep link or scanned the QR code). | Transition to a waiting screen so the person knows to complete the flow in the wallet. |
issuance_successful |
The person accepted the credential in the wallet. | Transition to DONE with a success status. |
issuance_error |
An error occurred during credential issuance. For example, the person rejected the request or the request expired. | Transition to the ABORT or ERROR step. |
Presentation (Verification)
The Verification flow asks the person to present a previously issued verifiable credential from their digital wallet. The IDV Platform generates a deep link, the person opens it in their wallet and consents to share the required claims. Microsoft Entra Verified ID cryptographically checks the credential and securely posts the validated claims to the IDV Platform—without repeating the full KYC enrollment process. The IDV Platform extracts the obtained claims into session properties and transitions the session to the success state.
Sequence diagram
See the sequence diagram of the entire Presentation flow (click to enlarge).
Sample configuration
See the sample configuration of the Verification flow via the workflow YAML.
actions:
- id: MS_VERIFIED_PRESENTATION
name: MS_VERIFIED_PRESENTATION
type: ms_verified_request
options:
type: presentation # Must be "presentation" for the Verify flow
config:
azTenantId: "<your_tenant_id>"
azClientId: "<your_client_id>"
azClientSecret: "{{ parameters.entra_client_secret }}"
authority: "did:web:<your_domain>"
requestedCredentials:
- type: "<vc_type>"
includeQRCode: true
registration:
clientName: "<organization_name>"
purpose: "To verify your digital identity credential"
Parameters
See the Verification flow specific configuration parameters below.
- Requested Credentials Type
| Parameter in Platform portal UI | Requested Credentials Type |
| Parameter in workflow YAML file | requestedCredentials → type |
| Format | The same value as credentialType parameter used in issuance. For example VerifiableCredential. |
| Description | The verifiable credential type string identifying which credential to request from the digital wallet app. |
| Where to find in Microsoft Azure Portal | Azure Portal → Verified ID → Credentials → Type |
| Requirement | Required |
For more details about available optional parameters, see the RequestCredential type from the official Microsoft Entra Verified ID documentation.
- Include Receipt
| Parameter in workflow YAML file | includeReceipt |
| Format | boolean (true or false) |
| Description | Whether to include a receipt in the callback payload with detailed claims. Recommended for audit purposes. |
| Requirement | Optional |
Callback events
Regula IDV Platform receives asynchronous notifications from Microsoft Entra Verified ID at the POST /api/v1/integration/ms-verified-id/session/{session_id}/callback endpoint.
Configure handlers in the events → onMsVerifiedIdCallback section of the workflow for each of the statuses described in the following table.
Status onMsVerifiedIdCallback → status |
Description | Recommended action |
|---|---|---|
presentation_request_retrieved |
The person's digital wallet app fetched the presentation request. | Transition to a waiting screen so the person knows to complete the flow in the wallet. |
presentation_verified |
The person presented the credential and Microsoft Entra Verified ID has validated it. | Run claim-extraction transformers to populate session properties, then transition to DONE step. |
presentation_error |
An error occurred during credential presentation. For example, the credential is revoked or the person rejected the request. | Transition to the ABORT or ERROR step. |
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
401 Unauthorized on API request |
Client secret is wrong or expired. | Rotate the secret in Azure Portal → App Registrations → Certificates & Secrets, update the platform parameter. |
issuance_pin_strategy_invalid error from Microsoft Entra Verified ID |
Another session's callback was delivered to this session. | This should not happen in normal operation. Check that MS_VERIFIED_ID_CALLBACK_STATE is not overwritten between action execution and callback receipt. |
requestId validation fails on callback |
Microsoft Entra Verified ID did not return requestId in the createIssuanceRequest response. |
This is a known edge case. The IDV Platform stores requestId only if Microsoft Entra Verified ID returns it. If it is absent, callback validation skips the requestId check. |
| Person does not receive the credential | Manifest URL is wrong or the contract does not match the credentialType value. |
Verify the manifest URL in Azure Portal → Verified ID → Credentials and ensure credentialType matches the contract's vcTypes value. |
| Claims missing in the issued credential | claims keys don't match the contract's inputClaim names. |
Check the Rules Definition in the Azure Portal for the credential contract. Use inputClaim names (for example, given_name), not display labels. |
FAQ
Does an organization need a Microsoft Entra tenant to use this feature?
Yes. For both digital credential issuance and verification flows, your organization needs a dedicated configured Entra tenant. For details, see the Microsoft Entra Prerequisites section.
Does the person need a digital wallet? What app to use?
The person needs the Microsoft Authenticator digital wallet app installed and configured on an iOS or Android device.
What happens if the person loses access to their digital wallet app?
In this case, the person needs to repeat the full Issuance (Enrollment) flow to receive another digital credential in the Microsoft Authenticator app.
References
- Introduction to Microsoft Entra Verified ID
- Advanced Microsoft Entra Verified ID setup
- Request Service REST API issuance specification
- Request Service REST API presentation specification
- Microsoft Entra Verified ID-supported standards
- Azure Active Directory Verifiable Credentials GitHub Samples