When integrating Microsoft Entra ID (formerly Azure AD) with EchoVideo, organizations often encounter differences between a user’s primary email address and their userPrincipalName (UPN). Since EchoVideo accounts are managed via email, this mismatch can prevent single sign-on (SSO) from functioning as expected. To address this, EchoVideo supports the echo_identity claim—a flexible identifier that allows administrators to map the UPN (or another unique value) instead of relying solely on email. By configuring Entra to send the UPN as the echo_identity claim, institutions can ensure consistent and reliable SSO authentication across all users.

Step 1 – Acquire Permissions in Microsoft Graph Explorer

1. Go to Microsoft Graph Explorer.  
2. Sign in with an administrator account that has Application.ReadWrite.All and Policy.ReadWrite.ApplicationConfiguration permissions.

Step 2 – Create a Custom Claims Mapping Policy

Run the following request in Graph Explorer to create a mapping policy that sends userprincipalname as the echo_identity claim.

• POST

  https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies

• BODY

  {
         "definition": [
                     "{\"ClaimsMappingPolicy\":{\"Version\":1,\"IncludeBasicClaimSet\":\"true\",\"ClaimsSchema\":[{\"Source\":\"user\",\"ID\":\"userprincipalname\",\"JwtClaimType\":\"echo_identity\"}]}}"
                 ],
                 "displayName": "echo_identity_claim"
  }

Step 3 – Retrieve the Policy ID

Run the following to fetch the list of claims mapping policies and note the policy ID.

• GET

  https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies

If you encounter a 403 Forbidden error when making API calls to Microsoft Graph, it likely means the required permissions haven’t been granted yet. To resolve this, go to Modify Permissions and click Consent to approve the necessary access.

Step 4 – Assign the Policy to Your Application

Attach the policy to your EchoVideo application with the following command (replace placeholders).

• POST

  https://graph.microsoft.com/v1.0/servicePrincipals(appId='<app-client-id>')/claimsMappingPolicies/$ref

• BODY

  {
         "@odata.id": "https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies/<CLAIM-POLICY-ID>"
  }

If you encounter a 403 Forbidden error when making API calls to Microsoft Graph, it likely means the required permissions haven’t been granted yet. To resolve this, go to Modify Permissions and click Consent to approve the necessary access.

Step 5 – Modify Application Manifest

1. Navigate to your Microsoft Entra tenant.
2. Select App registrations from the menu on the left.
3. Choose your application.
4. Select Manifest.

5. Change acceptMappedClaims from null to true, as shown in the figure below.

   By default, it will be null.

   

6. Click Save.

Step 6 – Navigate to Self Service Portal

1. In the EchoVideo self-service portal, select Custom OIDC as your provider.
2. Click Next.

Step 7 – Configure a Custom OIDC Connection in Auth0

1. Copy and paste the following into the OpenID Provider Configuration Endpoint, replacing
   <tenant-id>, as shown in the figure below.

   https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration

   

2. Enter your Client ID and Client Secret.
3. Click Create Connection.

Step 8 – Verify the Claim

1. Test the connection in the portal.

2. Confirm that the echo_identity claim is present with the UPN value.

   

   The email claim may still appear, but EchoVideo ignores it

3. Click Enable Connection.