# Integrate Identity Verification with Entra Verified ID

Microsoft Entra Verified ID is a decentralized identity platform that enables organizations to issue and verify standards-based digital credentials. It relies on trusted providers to perform identity verification and then issue credentials that can be used across applications and ecosystems.

Mosaic Identity Verification provides this capability through document checks, biometric matching, and fraud-prevention measures. Once a user’s identity is validated, Mosaic can issue a verifiable credential that Entra recognizes.

By integrating Mosaic with Microsoft Entra Verified ID, you can configure secure external connections and communicate with Entra APIs for credential issuance and presentation. End users complete the verification flow in Mosaic and receive a credential they can later present in Entra-protected applications, eliminating the need to repeat the process.

**For example:**

A bank integrates Mosaic with Microsoft Entra Verified ID to streamline digital onboarding. When a new customer signs up, Mosaic performs identity verification using document checks and biometric matching. Once the verification is complete, Mosaic issues a verifiable credential that Entra recognizes. The customer can then present this credential not only when accessing the bank’s own applications, but also when interacting with partner services (such as insurance portals) that trust Entra Verified ID. This eliminates the need for repeated identity verification steps, improving user experience and reducing friction across ecosystems.

This guide explains how to configure both systems, set up the necessary connections, and design Mosaic Journeys to issue and request verified credentials with Entra.

## How it works

The **client** starts an identity verification (IDV) flow in Mosaic, for example during onboarding or a step-up challenge (1). **Mosaic Journeys** then perform the IDV process, including document validation, biometric matching, and fraud checks, and determine the verification result (2).

After the verification, Mosaic triggers an **HTTP Request** (configured in [Integration Hub](/guides/automated-workflows/integration_hub)) to Microsoft Entra Verified ID. Depending on the use case, the journey can either issue a new credential or request and verify an existing one (3). **Microsoft Entra Verified ID** processes the call, performs the required checks, and returns the result of the issuance or verification (4). Mosaic handles the response and passes the outcome back to the **client**, for example, confirming that the credential has been issued or verified successfully (5).

Finally, the **client** can present the credential in other Entra-protected applications without having to repeat the IDV process (6).


```mermaid
sequenceDiagram
    participant Client
    participant Mosaic as Mosaic Journeys
    participant Entra as Microsoft Entra Verified ID

    Note over Client: (1) Start IDV flow
    Client->>Mosaic: Initiate verification

    Note over Mosaic: (2) Run IDV (document + biometric)
    Mosaic-->>Mosaic: Determine verification result

    Note over Mosaic,Entra: (3) Call Entra via Integration Hub HTTP Request
    alt Issue credential after successful IDV
        Mosaic->>Entra: Issue credential (API)
        Entra-->>Mosaic: Issuance result
    else Request/verify credential during access
        Mosaic->>Entra: Request/verify credential (API)
        Entra-->>Mosaic: Verification result
    end

    Note over Mosaic: (5) Prepare outcome for client
    Mosaic-->>Client: Credential status / verification result

    Note over Client: (6) Present credential later to Entra-protected apps
```

This guide walks you through the necessary step to configure the connectors towards Entra Verified ID service:

- **[acquireMSEntraCCToken](#step-7-configure-the-entra-access-token-connector-in-mosaic)**: Obtains an OAuth2 access token from Microsoft Entra using the client credentials flow. Used by other connectors to authenticate Entra API calls.
- **[issueMosaicVerifiedCredential](#step-5-configure-connection-to-entras-issuance-api)**: Calls Entra’s issuance API to create a new verifiable credential after successful IDV. Requires the access token and maps Mosaic IDV data to Entra credential claims.
- **[requestMosaicVerifiedCredential](#step-6-configure-connection-to-entras-verification-api)**: Calls Entra’s presentation API to request or verify an existing credential. Generates a QR code or presentation request for users to present their credential.


## Before you start

Before you start, ensure you have:

- Active Microsoft Entra tenant with [Verified ID enabled](https://learn.microsoft.com/en-us/entra/verified-id/verifiable-credentials-configure-tenant-quick).
- User account with one of the following roles in Entra to configure Verified ID / external connections:
  - Global Administrator (see [Microsoft Entra built-in roles](https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/permissions-reference))
  - Privileged Role Administrator (see [Assign Microsoft Entra roles](https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/manage-roles-portal))
- An **App registration in Entra** dedicated to Mosaic, with client ID and secret (or certificate) available (see [How to register an app in Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app))


## Step 1: Get client credentials

Client credentials are used to identify your app and generate access tokens for authorizing Mosaic requests. To obtain them, you'll need to create an application in the [Admin Portal](https://portal.transmitsecurity.io/) (if you don’t have one yet).

1. From **Applications**, click **Add application**.
2. Add the friendly application name to display in the Admin Portal.
3. Add a client display name, and your website URL as a redirect URI (e.g., `https://your-domain.com`).


1. Click **Add** to create your application. This will automatically generate your client credentials.


## Step 2: Create credentials in Microsoft Entra

In this step, you define the type of credential that Entra will issue and configure its content.

1. In the **Entra Admin center**, go to **Verified ID** > **Credentials** > **Create credentials**.
2. In **Select a credential type**, choose **Custom credential**.
3. Customize the credential card information with a friendly name and any required **custom claims** (for example, attributes that Mosaic needs to pass, such as `firstName`, `lastName`, `address`, `issueDate`, `expiryDate`, `documentNumber`).
4. During this configuration, enter the **Mosaic client ID and secret** retrieved in Step 1.
  - These values establish the external connection so Entra can trust Mosaic as the issuer of the credential.
5. Save the credential. It now appears under the **Credentials** page.


## Step 3: Retrieve credential details

In this step, you locate the credential you created and collect the information required to call Entra’s issuance API.

1. Go back to the **Credentials** page and select the credential you just created.
2. Click **Issue a credential** to display the **API endpoint** to call and a sample **payload request** for issuing that credential. You will use this payload request in Step 5.


## Step 4: Get app credentials from Entra

To allow Mosaic to call the Entra Verified ID APIs, you must get the credentials of an **App registration** in Entra:

1. In the **Entra admin center**, go to **App registrations** and select the app linked to your Verified ID setup.
2. From the **Overview** page, copy the **Application (client) ID**.
3. In **API permissions**, make sure the app has the required permissions for issuing and verifying credentials.
4. In **Certificates & secrets**, create a new **client secret** if you don’t have one yet.
  - Copy the secret value immediately, because it is only shown once.
  - You will later use this client ID and secret in Mosaic’s [Integration Hub](/guides/automated-workflows/integration_hub) to authenticate HTTP requests to Entra.


## Step 5: Configure connection to Entra’s issuance API

Create a reusable **Custom HTTP** integration that Journeys will call to interact with Entra’s issuance APIs.

1. In **Portal** > **[Integration Hub](/guides/automated-workflows/integration_hub)**, search for **HTTP request** and click **Create**.
2. Set a friendly **Function Name**, for example: `issueMosaicVerifiedCredential`. This will appear as the callable step inside Journeys.
3. **URI**: paste the **API endpoint** shown in **Step 3 (Retrieve credential details from Entra)**. This is the exact issuance URL provided by Entra.
4. **Function Arguments**: add the inputs your flow needs, and ensure they match the **claims** configured in Entra so you can map them 1:1. Keep argument names aligned with the **custom claims** you created in Entra to avoid mapping mistakes.
  - In addition, enter: `access_token` (String) — the Entra App access token. This token must be obtained dynamically at runtime (via the OAuth2 client-credentials flow in your backend using the App Registration’s client ID and secret) and passed into the Journey. Mosaic does not generate or store this token.
5. **HTTP Request Method**: `POST`.
6. **Headers**:
  - `Authorization: Bearer {access_token}`
  - `Content-Type: application/json`
7. **Request Body**:
  - Use the **sample payload** shown by Entra in **Issue a credential** (from Step 3).
  - Map the body fields to your **Function Arguments** so the values (e.g., `given_name`, `family_name`, etc.) are injected at runtime.
8. **Authentication**:
  - Leave this section empty. Authentication is handled entirely through the `Authorization` header populated from `access_token`.
9. **HTTP connection settings**:
  - Review timeouts, redirects, and logging per your org’s standards and adjust if needed.
10. **Response**:
  - **Web service response**: select **Wait and process web service response**.
  - **Response Format**: **JSON Object**.


## Step 6: Configure connection to Entra’s verification API

Create a reusable **Custom HTTP** integration that Journeys will call to request a presentation from Microsoft Entra Verified ID.

1. In **Portal > [Integration Hub](/guides/automated-workflows/integration_hub)**, create a new **HTTP request** connector named `requestMosaicVerifiedCredential`.
2. **Function Arguments**:
  - `xsm_id` (String) — the journey or cross-session message ID.
  - `access_token` (String) — the Entra App access token obtained dynamically at runtime (Mosaic does not issue or store it).
3. **HTTP Request Method**: `POST`.
4. **URI**: `https://verifiedid.did.msidentity.com/v1.0/verifiableCredentials/createPresentationRequest`
5. **Headers**:
  - `Authorization: Bearer ${access_token}`
  - `Content-Type: application/json`
6. **Request Body**: use the full payload provided by Entra Verified ID:

```json
{
"authority": "did:web:verifiedid.entra.microsoft.com:8452a37e-6420-43d6-aee6-db512ff08ad6:0d07d568-7e0b-4b20-5579-916bc49e4da6",
"includeReceipt": true,
"registration": { "clientName": "Mosaic Verified Credential" },
"callback": {
   "url": "https://api.transmitsecurity.io/ido/api/v2/invoke-api-journey/verified_credential_pr_callback?clientId=87gVegzrg6eaC1ZT5zkWs",
   "state": "${xsm_id}"
},
"requestedCredentials": [
   {
      "type": "MosaicVerifiedIdentity",
      "purpose": "To see your Mosaic verified identity",
      "acceptedIssuers": [
      "did:web:verifiedid.entra.microsoft.com:8452a37e-6420-43d6-aee6-db512ff08ad6:0d07d568-7e0b-4b20-5579-916bc49e4da6"
      ]
   }
]
}
```
The `state` field in the payload must match the Cross-Session Message ID (`xsm_id`) created earlier in the journey.
This allows Mosaic to correlate Microsoft Entra’s callback response with the correct journey instance.
7. **Authentication**: leave empty — the Bearer token header handles it.
8. **Response**: select Wait and process web service response, format JSON Object.


## Step 7: Configure the Entra access-token connector in Mosaic

Create a reusable **Custom HTTP** integration that returns a Microsoft Entra OAuth2 access token (client credentials). Both journeys will call it.

1. In **Portal > [Integration Hub](/guides/automated-workflows/integration_hub)**, create a new **HTTP request** connector named `acquireMSEntraCCToken`.
2. **HTTP Request Method**: `POST`
3. **URI**: `https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/token`
4. **Headers**: `Content-Type: application/x-www-form-urlencoded`
5. **Request Body** (form-encoded):

```curl
client_id=<YOUR_APP_CLIENT_ID>        // from Entra App registration
&client_secret=<YOUR_APP_CLIENT_SECRET>  // from Entra App registration
&grant_type=client_credentials
&scope=3db474b9-6a0c-4840-96ac-1fceb342124f/.default           // e.g., identifier of the Verified ID resource scope
```
The `scope` value represents the **App ID** of the Microsoft Verified ID service.
To verify or locate this identifier in your tenant, go to **Microsoft Entra admin center > Identity > Verified ID > Enterprise applications > Microsoft Verifiable Credentials Service > Properties**, and copy the **Application (client) ID**.
Use that value in the format: `scope=<application_id>/.default`
6. **Authentication**: leave empty (handled via form body).
7. **Response**: select **Wait and process web service response**, format **JSON Object**.


Note
Map the JSON response field `access_token` from this connector into your Journey and pass it to subsequent Entra calls (e.g., `Authorization: Bearer ${access_token}`).

## Step 8: Create journeys

### Issue Mosaic verified credential Journey

This journey issues a Microsoft Entra–recognized credential after the user successfully completes identity verification in Mosaic.
It combines native Mosaic nodes (for user interaction and authentication) with custom HTTP requests (for external API calls).

#### Journey flow

1. **[Display Information](/guides/orchestration/journeys/display_information)** – Shows an introductory message to the user (e.g., *“You’re about to start identity verification.”*).
2. **[Collect Information](/guides/orchestration/journeys/get_info_from_client)** – Captures user credentials (email and password).
3. **[Password Authentication](/guides/orchestration/journeys/authenticate_password)** – Authenticates the user using Mosaic’s identity service.
  - On failure, redirects back to the previous form.
4. **[Get User Identifiers](/guides/orchestration/journeys/get_user_identifiers)** – Retrieves unique identifiers for the authenticated user.
  - On failure, ends with **Reject Access**.
5. **start_verify_session** – *(Custom HTTP)* Starts a verification session by calling
`https://api.transmitsecurity.io/verify/api/v1/verification`.
6. **[Collect Information](/guides/orchestration/journeys/get_info_from_client)** – Prompts user interaction (for example, scanning a QR code or confirming verification).
7. **get_verify_result** – *(Custom HTTP)* Retrieves the verification result by calling
`https://api.transmitsecurity.io/verify/api/v1/verification/${session_id}/result?detailed=true`.
8. **[Condition](/guides/orchestration/journeys/condition)** – Checks whether verification has completed successfully.
9. **[Display Information](/guides/orchestration/journeys/display_information)** – Shows verification success or failure.
10. **[acquireMSEntraCCToken](#step-7-configure-the-entra-access-token-connector-in-mosaic)** – *(Custom HTTP)* Obtains an Entra client-credentials token for issuing the credential.
11. **[acquireMSEntraCCToken](#step-7-configure-the-entra-access-token-connector-in-mosaic)** – *(Custom HTTP)* Calls Entra’s issuance API, passing verified identity data.
12. **[Collect Information](/guides/orchestration/journeys/get_info_from_client)** – Optional final confirmation (for example, *“Scan in Microsoft Authenticator to finish”*).
13. **Complete Journey** – Ends the flow successfully.


Note
Custom HTTP nodes (`start_verify_session`, `get_verify_result`, `acquireMSEntraCCToken`, and `issueMosaicVerifiedCredential`) must reference integrations created in **[Integration Hub](/guides/automated-workflows/integration_hub)**.

### Request Mosaic Verified Credential Journey

This journey requests and verifies a Mosaic Verified Credential through Microsoft Entra Verified ID.
It combines native Mosaic nodes (for user interaction and flow control) with custom HTTP requests (for external API calls).

#### Journey flow

1. **[Display Information](/guides/orchestration/journeys/display_information)** – Shows an introductory message to the user (e.g., *“You’re about to verify your Mosaic credential.”*).
2. **[Create Cross-Session Message](/guides/orchestration/journeys/create_cross-session_message)** – Creates a cross-session message to track the credential verification request.
3. **[acquireMSEntraCCToken](#step-7-configure-the-entra-access-token-connector-in-mosaic)** – *(Custom HTTP)* Obtains the Microsoft Entra client-credentials token for authentication.
4. **[requestMosaicVerifiedCredential](#step-6-configure-connection-to-entras-verification-api)** – *(Custom HTTP)* Calls Entra’s presentation API to request a credential verification, passing:
  - `xsm_id` (Cross-session message ID)
  - `access_token` (Microsoft Entra token)
5. **[Collect Information](/guides/orchestration/journeys/get_info_from_client)** – Displays the QR code returned by Entra for the user to scan and present their credential.
6. **[Condition](/guides/orchestration/journeys/condition)** – Checks whether the cross-session message contains a consumption reply confirming successful credential verification.
7. **[Display Information](/guides/orchestration/journeys/display_information)** – Shows a confirmation message once credential verification is complete.
8. **Complete Journey** – Ends the flow successfully.


Note
Custom HTTP nodes (`acquireMSEntraCCToken` and `requestMosaicVerifiedCredential`) must reference integrations created in **[Integration Hub](/guides/automated-workflows/integration_hub)**.

## Step 9: Test the user flow

The user experience will depend on your application, but you can follow the [sample app](https://github.com/Azure-Samples/active-directory-verifiable-credentials) documentation to simulate and validate the Verified ID flow using Transmit Security.