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

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>"
  }

Step 5 – Configure a Custom OIDC Connection in Auth0

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

3. 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

   

4. Enter your Client ID and Client Secret.
5. Click Create Connection.

Step 6 – 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.