Skip to content
Help Center
withpersona.comDashboard

Configure Persona with Microsoft Entra Verified ID

View Markdown Contact support Contact support 16 min read
On this page

Persona supports Microsoft Entra Verified ID as an issuer and as a verifier of verifiable credentials (VCs). This article tells how each flow works. It also tells how to configure each flow in your integration.

Overview

Microsoft Entra Verified ID is a decentralized identity solution. Organizations use it to issue tamper-proof digital credentials. They can also ask users for these credentials across applications and ecosystems. Verifiable credentials are cryptographically signed, portable, and user-controlled. The holder selects which data to share and with whom.

Persona fits into this ecosystem in two ways:

  • As an issuer: After a user completes a Persona verification, Persona can issue a verifiable credential for that user. The user keeps the credential in their Microsoft Authenticator wallet. The user can use it again with all services that are compatible with Entra Verified ID.
  • As a verifier: In a verification flow, Persona can request and validate a verifiable credential that was issued before. If a user already has a trusted credential, they do not have to verify again.

Choosing an issuance model

When Persona issues a credential, you select the Microsoft Entra tenant that issues it. The rest of this article follows that selection. You configure the two models separately and independently:

Persona as your Identity Verification PartnerYour own Microsoft Entra tenant
Entra tenant usedPersona’sYours
Setup required in EntraNoneVerified ID onboarding, a credential definition, and an app registration
Issuing authority (DID)Persona’s — did:web:withpersona.comYour tenant’s DID
BrandingPersona brand and logoYour logo, colors, and per-credential design
Credential lifespanSet by PersonaSet by you, in your credential’s rules definition
Claims in the credentialPersona’s standard claim setAny subset of Persona’s claim set that your rules definition declares
Credential typePersona’sAny type name you register

How it works

Issuance flow

  1. The user completes identity verification through Persona.
  2. After a successful verification, Persona calls the Microsoft Entra Request Service API to create an issuance request. The request comes from the Persona Entra tenant, or from your tenant through the connection that you configured.
  3. Entra generates a verifiable credential that contains the verified identity claims (for example, first name, last name, document number, date of birth).
  4. The user scans a QR code or opens a deep link to add the credential to their Microsoft Authenticator app. If the inquiry configuration includes field_key_pin, the user must also enter a PIN when they add the credential. This is an added security measure.
  5. The user keeps the credential in their wallet. The user can show it to all relying parties that are compatible with Entra Verified ID, and does not have to do the verification process again.

Verification flow

  1. A user arrives at a verification step in your flow.
  2. Persona sends a presentation request to Microsoft Entra.
  3. The user opens Microsoft Authenticator, selects their credential, and presents it.
  4. Entra validates the credential’s signature and returns the result to Persona.
  5. Persona compares the credential with the requirements that you configured (accepted issuers, required claims). Then Persona passes or fails the verification.

Persona as your Identity Verification Partner

In this model, Persona issues the credential from an Entra tenant that Persona controls. You do not need a Microsoft Entra tenant, an Azure subscription, or any Entra configuration.

Issuer configuration

You do not have to configure Entra. To issue a credential at the end of a Persona verification flow:

  1. Open the inquiry template that you want to issue from.
  2. Choose Add → Module → Microsoft Entra Verified ID issuance.
  3. Leave Issuer set to Persona-managed (the default).

The issuance module reads the verified name, address, and document details of the user. Thus, add it to a template that already contains a government ID verification. If the template does not have those fields, the credential contains only the Persona metadata claims.

Claims included in the credential

The claims come from the Persona verification result. Persona sends these claims in every issuance request:

ClaimDescription
firstNameVerified first name from the identity document
lastNameVerified last name from the identity document
dateOfBirthDate of birth
addressStreet1Street address, line 1
addressStreet2Street address, line 2
addressCityCity
addressSubdivisionState, province, or subdivision
addressPostalCodePostal code
addressCountryCodeCountry code
documentNumberDocument ID number
documentTypeDocument class (for example, driver’s license or passport)
documentIssuanceDateDate the document was issued
documentExpirationDateDate the document expires
documentIssuingCountryCodeCountry that issued the document
photoThe user’s selfie, if a selfie was captured
inquiryIdThe Persona inquiry the credential was issued from
referenceIdYour own identifier for the user, if set on the inquiry
organizationIdYour Persona organization
organizationNameYour Persona organization name
environmentIdThe Persona environment (for example, production or sandbox)
inquiryTemplateIdThe inquiry template the credential was issued from

If a claim has no value on the inquiry, Persona does not include it in the request. Each claim gets its value from a field on your template. In the configuration panel of the issuance step, you can point each claim to a different field.

Verifier configuration

When Persona verifies a credential, it checks the Decentralized Identifier (DID) of the credential. The DID is a unique identifier that shows which organization issued the credential. The Persona DID is did:web:withpersona.com.

Verification filtering levels

By default, Persona accepts all valid Entra Verified IDs, including IDs that Persona did not issue. To accept fewer credentials, configure one or more of these filters in the Allowed Issuer detection verification check:

  • Issuing authority/DID (allowed_issuers): Accept credentials from specific issuing organizations. For example, accept credentials only from Persona (did:web:withpersona.com), or add more trusted partner DIDs.
  • Persona organization (allowed_organization_ids): For credentials that Persona issued, specify the Persona organization that the credential must come from.
  • Environment ID (allowed_environments_ids): Accept only credentials from a specific Persona environment (for example, your production environment and not a development or staging environment).
  • Inquiry template ID (allowed_inquiry_template_ids): Accept only credentials that specific inquiry templates issued.

Required claims Specify the claims that the credential must contain for the verification to pass. If the credential does not have a required claim, Persona rejects the verification.

To enable this product feature, talk with your Persona account team.

Credential storage and validity

The user keeps issued credentials in their Microsoft Authenticator wallet. Important details:

  • Credentials are cryptographically signed. Nobody can change them after issuance.
  • The Persona configuration sets the validity period at the time of issuance.
  • Users can show their credential to all services that are compatible with Entra, and do not have to verify again.

Issuing from your own Microsoft Entra tenant

Use this model if you want the credential to show the brand and DID of your organization. Also use it to control the lifespan of the credential, or to include claims that are specific to your institution. Persona uses a client ID and secret that you give to connect to your Entra tenant. Persona then issues the credential that you defined there.

The configuration has two parts. First, configure all items in Microsoft Entra (steps 1–3). Then configure all items in the Persona Dashboard (steps 4–5).

Prerequisites

  • An Entra tenant where you have sufficient privilege to onboard Verified ID and register an application. For the Verified ID setup, Microsoft requires the Authentication Policy Administrator role. For the app registration, Microsoft requires the Application Administrator role (Microsoft Learn).
  • Issuance from your own tenant must be turned on for your Persona organization. Before you start, contact your Persona account team to do this.
  • Admin access to your Persona Dashboard.

Step 1: Onboard your tenant to Verified ID

If your tenant never issued a Verified ID, configure the service first. Microsoft gives two paths:

  • Quick setup — Microsoft provisions the signing key and a did:web identifier for you. This is the fastest path. But the signing key is shared. Thus, credential validity has a maximum of six months, and the tenant can send a maximum of two requests per second.
  • Advanced setup — you use your own Azure Key Vault, register your decentralized identifier, and verify your domain. Select this path if you need a custom domain in your DID or a longer credential lifespan.

If you want a custom domain registered for the tenant, you must use advanced setup. Quick setup is not available in EDU tenants at this time. If you use Key Vault, it must use the Vault access policy permission model. Azure RBAC is not supported.

Microsoft Authenticator shows the trusted domain that you verify here as the issuer. Thus, use a domain that your users will know is yours.

Step 2: Create the credential you want Persona to issue

Persona sends the verification results as claims in the issuance request. This is the Microsoft ID token hint attestation. Create a custom credential that declares those claims:

  1. In the Microsoft Entra admin center, go to Verified ID → Credentials → Add a credential.

  2. Select Custom credential, then Next.

  3. Enter a Credential name. This name becomes the type of the credential. Write it down. You enter it in Persona as the Credential Type.

  4. Paste your rules definition. In it, declare each claim that you want Persona to fill under an idTokenHints attestation. Persona sends the same claim names that Claims included in the credential above lists. Refer to them as $.<claimName>:

    {
  "attestations": {
    "idTokenHints": [
      {
        "mapping": [
          {
            "outputClaim": "firstName",
            "required": true,
            "inputClaim": "$.firstName",
            "indexed": false
          },
          {
            "outputClaim": "lastName",
            "required": true,
            "inputClaim": "$.lastName",
            "indexed": true
          },
          {
            "outputClaim": "dateOfBirth",
            "required": false,
            "inputClaim": "$.dateOfBirth",
            "indexed": false
          },
          {
            "outputClaim": "documentNumber",
            "required": false,
            "inputClaim": "$.documentNumber",
            "indexed": false
          },
          {
            "outputClaim": "referenceId",
            "required": false,
            "inputClaim": "$.referenceId",
            "indexed": false
          }
        ],
        "required": false
      }
    ]
  },
  "validityInterval": 63072000,
  "vc": { "type": ["YourCredentialType"] }
}

    validityInterval is the credential lifespan in seconds. The example above is two years. You control the lifespan here. Persona does not override it.

  5. Paste your display definition. It controls the branding of the credential: the logo, the colors, and the label for each claim. Read the Microsoft rules and display definition reference and credential design guide. To show the selfie of the user, map the photo claim. Set its display type to image/jpg;base64url.

  6. Select Create. Open the new credential and select Issue credential. Entra shows a sample Request Service API payload. Copy two values from it:

    • authority — your Verified ID Authority (DID), which looks like did:web:yourdomain.com
    • manifest — your Credential Manifest URL, of the form https://verifiedid.did.msidentity.com/v1.0/tenants/<tenant-id>/verifiableCredentials/contracts/<contract-id>/manifest

You can also point Persona to a credential type from Microsoft, for example VerifiedEmployee. These types use claims from the directory, not the claims that Persona sends. To get one, the user must be signed in to their Entra account in Microsoft Authenticator. For most use cases, a custom credential is the better selection.

Step 3: Register an application for the client ID and secret

Persona uses the client credentials flow to authenticate to your tenant. Thus, Persona needs its own app registration. These are the Microsoft app registration steps:

  1. In the Entra admin center, go to Applications → App registrations → New registration.
  2. Give it a name (for example, “Persona Verified ID issuance”).
  3. Set Supported account types to Accounts in this organizational directory only (single tenant). No redirect URI is needed.
  4. Select Register. Copy the Application (client) ID from the overview page. This is the Client ID that you enter in Persona.
  5. Go to API permissions → Add a permission → APIs my organization uses. Search for Verifiable Credentials Service Request. Select Application permissions, and select VerifiableCredential.Create.All.
  6. Select Add permissions. Then select Grant admin consent for your tenant. Without consent, the requests from Persona fail.
  7. Go to Certificates & secrets → New client secret. Add a description and an expiry, and select Add. Copy the secret Value immediately. Microsoft does not show it again.
  8. Write down your Tenant ID. It is on the Entra Overview page.

Client secrets expire. Record the expiry date that you selected. Before that date, create a replacement secret in Persona. If you do not, issuance starts to fail.

Step 4: Add the connection in the Persona Dashboard

  1. In the Persona Dashboard, go to Integrations → Microsoft Entra (app.withpersona.com/dashboard/integrations/microsoft-entra).

  2. Select Add Credential, then choose Microsoft Entra Verified ID Issuer.

  3. Enter the values that you collected above in the form:

    FieldValue
    Nickname for CredentialA label for this connection, e.g. “Production Entra tenant”
    Tenant IDYour Entra tenant ID (Entra admin center → Overview)
    Client IDThe Application (client) ID from Step 3
    Client SecretThe client secret Value from Step 3
    Verified ID Authority (DID)The authority value from Step 2, e.g. did:web:yourdomain.com
    Credential Manifest URLThe manifest value from Step 2
    Credential TypeThe credential name/type from Step 2
    Issuer Display Name (optional)The issuer name shown to users during issuance. Defaults to Persona if left blank.

  4. Under Scopes, keep Microsoft Entra Verified ID issuance. checked. This is the VerifiableCredential.Create.All permission that you consented to in Step 3. Without it, issuance fails.

  5. Save the connection. Make sure that it shows in the credential list for the Microsoft Entra integration.

When you save, Persona validates the form. If you see an error, check these items:

  • The Credential Manifest URL is an https URL on the host verifiedid.did.msidentity.com. Persona rejects manifest URLs on all other hosts.
  • The Verified ID Authority (DID) starts with did:.
  • The authority, the manifest URL, and the credential type all have values.
  • Customer-managed issuance is enabled for your organization. If it is not, the save fails with “Customer-managed Microsoft Entra Verified ID connections are not enabled for this organization.” Contact your Persona account team.

Step 5: Point the issuance module at your connection

  1. Open the inquiry template that you want to issue from. If it does not have the module, select Add → Module → Microsoft Entra Verified ID issuance. Add the module to a template that includes a government ID verification. The claims of the credential come from the verified name, address, and document fields.
  2. Select the issuance screen. In the configuration panel on the right, set Issuer to Customer-managed.
  3. A Connection picker shows. Select the connection that you created in Step 4.
  4. Optional: Review the field pickers below. These are First name field, Last name field, Birthdate field, the address fields, and the document fields. Use them to point a claim to a different field on your template.
  5. Optional: Set a PIN field. The user must then enter a PIN again when they add the credential to their wallet.
  6. Publish the template.

Step 6: Test the flow

  1. Create an inquiry from the template and complete the verification.
  2. At the issuance step, scan the QR code with Microsoft Authenticator. Make sure that the wallet adds the credential.
  3. Open the credential in the wallet. Make sure that your branding and claims show as you defined them in Step 2.

If Authenticator shows that the credential comes from an unverified issuer, the trusted domain on your DID is not verified. Do Step 1 again. If issuance fails completely, the most frequent causes are:

  • Admin consent is missing in Step 3.
  • The client secret expired.
  • Your rules definition marks a claim as "required": true, but the inquiry did not collect that claim.

User experience

For end users (issuance)

  1. Complete identity verification in your application.
  2. When the inquiry tells you, do the steps that it shows.
  3. After you complete the inquiry, confirm the credential details. Add the credential to your wallet.
  4. You can now show your verified credential to supported services.

For end users (verification)

  1. At the verification step, scan the QR code with Microsoft Authenticator.
  2. Select the credential that you want to share.
  3. Confirm the data fields that you share. Approve the presentation.
  4. Persona receives and validates the credential automatically.

Frequently asked questions

Does my organization need a Microsoft Entra tenant to use this feature? Only if you want to issue from your own tenant. When Persona is your Identity Verification Partner, Persona uses its own Entra tenant. For verification, you also do not need a tenant. Persona does the presentation request and the validation.

When should I issue from my own tenant instead? Issue from your own tenant if you need one or more of these:

  • Your own branding on the credential.
  • Control of the lifespan of the credential.
  • A credential type and DID that belong to your organization.
  • Claims that are specific to your institution, for example a student number or campus affiliation.

Can I use both models? Yes. You set the issuer for each issuance module. Thus, different templates, or different steps, can issue from the Persona tenant and from your tenant.

Can I connect more than one Entra tenant? Yes. Add one connection for each tenant. On each issuance module, select the connection that you want.

What wallet does the user need? Users must have Microsoft Authenticator installed on their iOS or Android device to receive and present credentials.

Can I accept credentials from multiple issuing organizations? Yes. You can configure Persona to accept credentials from more than one DID. For example, Persona can accept credentials that Persona issued and credentials from partner organizations or other vendors.

What happens if a user loses access to their Authenticator app? The user must verify again through Persona to get a new credential.

Is the issued credential reusable across multiple services? Yes. After the user puts the credential in the wallet, the user can show it to all relying parties that support Entra Verified ID. The user does not have to do the identity verification process again.

What happens when my client secret expires? Issuance requests to your tenant start to fail. Before the expiry date, create a new secret in Entra. Then update the connection in the Persona Dashboard.

Plans Explained

Microsoft Entra Integration by plan

Startup ProgramEssential PlanGrowth PlanEnterprise Plan
Microsoft Entra IntegrationNot AvailableNot AvailableLimitedAvailable

Learn more about pricing and plans.

Was this page helpful?If something is missing, let us know and we will take a look.
Thanks for the feedback. It helps us improve these docs.

Related articles

Using Persona Workflows to manage Microsoft Entra users & profiles
Marketplace and 3rd-Party Integrations · Authentication
Microsoft Entra integration overview
Marketplace and 3rd-Party Integrations · Authentication