Enterprise-managed authorization (EMA) with Microsoft Entra ID

Updated:


September 24, 2026

Register a Microsoft Entra ID tenant as a trusted issuer so Entra signs the enterprise-managed authorization assertion. Unified.to checks that signature against the tenant's keys and returns an access token for the end user. Add one trusted issuer per Entra tenant.

⚠️ Direct mode accepts an ID-JAG only. The JWT header typ must be oauth-id-jag+jwt. A normal Entra access token or ID token is rejected. Entra does not generally issue that grant yet. If you only have ordinary Entra sign-in, use the brokered setup at the end of this guide. In that setup Entra is the login directory, and your own issuer is the trusted issuer.

Before you start

  • You are a workspace admin.
  • You can open the Entra admin center for the customer tenant.
  • You have the tenant (directory) id and the application (client) id of the app that will request tokens. These are different ids.
  • The issuer string is the Entra v2 issuer, including /v2.0. https://sts.windows.net// does not match.

1. Turn the feature on

In the app, open Settings, then Enterprise Auth. Turn Enterprise-Managed Authorization on and save.

On EU or AU, use api-eu.unified.to or api-au.unified.to. The audience and resource claims later in this guide must use that same host. The examples below use the US host.

2. Copy the ids from Entra

In the Entra admin center, open the tenant and the app registration that will request tokens for Unified.to.

  • Tenant id — Entra ID, Overview. This is the directory id. It goes in the issuer URL.
  • Application (client) id — the requesting app. It goes in Allowed client IDs. A direct issuer with an empty list is rejected.

The issuer you will register is:

https://login.microsoftonline.com/<tenant-id>/v2.0

3. Add a trusted issuer

On Enterprise Auth, choose 'Add trusted issuer' and set:

  • Topology: Direct (XAA)
  • Issuer (iss): https://login.microsoftonline.com//v2.0
  • Key source: JWKS
  • JWKS URL: leave blank. Unified.to loads the keys from the tenant's OpenID configuration. To set it yourself, use https://login.microsoftonline.com//discovery/v2.0/keys
  • Allowed client IDs: the Entra application (client) id. Required for a direct issuer.
  • Default scopes: the categories the token should receive when the assertion has no scope, for example crm.read
  • Environment: optional. Set it when tokens from this tenant must stay in one connection environment, such as Production
  • Just-in-time identity mapping: on, if you want Unified.to to match the assertion email to a workspace user
  • Enabled: on

The same record over the API:

curl -X POST https://api.unified.to/unified/enterprise-auth/trusted-issuers \
  -H "Authorization: Bearer $UNIFIED_WORKSPACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "direct_xaa",
    "issuer": "https://login.microsoftonline.com/<tenant-id>/v2.0",
    "key_source": "jwks",
    "client_ids": ["<entra-application-client-id>"],
    "default_scopes": ["crm.read"],
    "jit_enabled": true
  }'

Repeat this for each Entra tenant. The tenant id is part of iss, so two tenants cannot share one row.

4. What Entra must put on the assertion

Entra signs the JWT. Your app redeems that JWT. It does not re-sign it. The header typ must be oauth-id-jag+jwt.

  • iss matches the trusted issuer string exactly, including /v2.0
  • aud is the API origin, such as https://api.unified.to
  • resource is that same origin for REST calls, or that origin plus /mcp for MCP calls. A token for one resource is rejected by the other
  • sub is the end user. Entra's oid is the stable subject
  • client_id is the application id in Allowed client IDs
  • jti is unique for each redemption. The test panel does not consume jti
  • scope is space-separated, such as crm.read crm.write. A comma-separated list is treated as one unknown scope and dropped
  • email is a user who already belongs to the workspace, when just-in-time mapping is on. Unified.to does not read preferred_username or upn

5. Test, then exchange

On the issuer row, choose Test and paste the assertion. A passing trace means the signature, issuer, audience, resource, client id, and identity checks succeeded. Test does not issue a token.

Exchange the assertion once at the token endpoint. The access_token starts with ema_. Send it as Authorization: Bearer on integration data routes. It can call only the categories in its scopes. It cannot manage the workspace, create API keys, or change enterprise-auth settings.

curl -X POST https://api.unified.to/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
  --data-urlencode "assertion=$ASSERTION_JWT" \
  --data-urlencode "scope=crm.read"

What comes back

The signed JWT is only the assertion. Do not put ema_ in front of it. Unified.to mints a separate opaque access token and returns it already prefixed. There is no refresh token. When it expires, redeem a new assertion.

{
  "access_token": "ema_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "crm.read"
}

⚠️ The token endpoint requires the workspace Enterprise Auth switch to be on. Test still runs when that switch is off. A disabled switch returns issuer not trusted.

Call the API or MCP

The resource claim on the assertion chooses where this access token works. One token does not work for both. Send it as Authorization: Bearer followed by the access_token value.

  • REST API: set resource to https://api.unified.to (or the EU or AU host). The token is accepted only on integration data routes such as GET /crm/{connection_id}/contact, and only when the scope matches the category and the method.
  • MCP: set resource to that same origin plus /mcp, for example https://api.unified.to/mcp. Send the bearer token to the MCP server.

A REST token sent to MCP is refused, and an MCP token sent to the REST API returns token issued for another resource.

6. Map the user

The trusted issuer does not store a user id. Each assertion subject gets an identity row. With just-in-time mapping on, Unified.to sets the workspace user id when the email claim matches a user in the workspace. Otherwise open the identity and set the workspace user yourself. No match and no just-in-time mapping returns identity not provisioned.

When Entra cannot issue an ID-JAG

Sign the user in with ordinary Entra sign-in, then register your own issuer as the trusted issuer. Topology is Brokered (ISV). Key source is JWKS (or Static key, or Workspace secret). Issuer (iss) is your issuer, not the Entra tenant. Put the Entra oid in sub and the user's email in the email claim. aud, resource, and a fresh jti are the same as above. A brokered assertion may omit typ. A direct assertion may not.

curl -X POST https://api.unified.to/unified/enterprise-auth/trusted-issuers \
  -H "Authorization: Bearer $UNIFIED_WORKSPACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "isv_brokered",
    "issuer": "https://your-issuer.example.com",
    "key_source": "jwks",
    "jwks_uri": "https://your-issuer.example.com/.well-known/jwks.json",
    "default_scopes": ["crm.read"],
    "jit_enabled": true
  }'

If the exchange fails

  • issuer not trusted — iss is not the v2 issuer, the row is disabled, or Enterprise Auth is off.
  • direct_xaa requires typ oauth-id-jag+jwt — Entra sent an access token or ID token, not an ID-JAG. Use the brokered setup, or wait until Entra issues that grant.
  • resource mismatch — resource is not this region's API host, or you set /mcp when the call is REST.
  • client_id not allowed — the assertion client_id is not in Allowed client IDs.
  • identity not provisioned — no email match, or just-in-time mapping is off and the subject is unmapped.
  • assertion replayed — that jti was already exchanged. Sign a new one.
  • insufficient_scope — the token's scopes do not cover that category and method.
Share
All guidesAccounting Account Type Hierarchy in UnifiedAdvertising Report Metrics by IntegrationAmazon S3: Required IAM PermissionsATS to Vector DB: How to Power Talent Intelligence with Real-Time DataBuilding AI applications with Unified and LangbaseConcur & Concur (Company) — Connection GuideConfigure Greenhouse Native Candidate WebhooksConfigure Salesforce Meetings and Notes for UnifiedConnect Amazon Seller Central to Unified.toConnecting BambooHR via OAuth 2Connecting Google Workspace Integrations with a Service AccountCorrect WelcomeKit Scopes for Jungle IntegrationCreating Ads using the Unified Ads APICreating Walmart Items via UnifiedEnd-Users, Integrations, and ConnectionsEnriching Unified Objects with Custom MetadataEnterprise-managed authorization (EMA) with a static keyEnterprise-managed authorization (EMA) with a workspace secretExtended observability — pushing API logs to ClickHouseExtended observability — pushing API logs to Grafana / LokiExtended Observability - Pushing API Logs to your Datadog InstanceFacebook Messenger Webhook SetupFireflies Integration GuideGetting started with WorkableHandling Delegated vs. Application Scopes in Microsoft IntegrationsHiBob & Unified: connection and time off guideHow long are logs retainedHow to access employees and usersHow to add API support for the Create Activity in CrelateHow to Associate a Connection ID with Your End-UserHow to build a Candidate Assessment product withHow to build a candidate sourcing or job board app with Unified.toHow to build a Discord support bot with Unified.to and LangbaseHow to Build a Fintech Application with Unified's Payments APIHow to Build an E-Commerce Product Integration with UnifiedHow to build an invoicing system with Unified.toHow to build Enterprise Search using RAGHow to configure Bullhorn Redirect URI for creating a connectionHow to configure webhooks in HubSpotHow to configure webhooks in Thrive LearningHow to configure webhooks in Toast for UnifiedHow to Connect Anthropic to Real-Time SaaS Data with Unified.to MCP ServerHow to Connect Cohere to Real-Time SaaS Data with Unified.to MCP ServerHow to Connect Google Gemini to Real-Time SaaS Data with Unified.to MCP ServerHow to connect HiBob (Bob) to Unified with OAuth 2.0How to Connect LLMs to Real-Time SaaS Data with Unified.to MCP ServerHow to Connect OpenAI to Real-Time SaaS Data with Unified.to MCP ServerHow to Connect Zoom and Zoom PhoneHow to create a Connection In Microsoft TeamsHow to create a token-based connection in HighlevelHow to Create a Unified.to Connection to HighLevelHow to Create a Xero Connection in Unified.toHow to create and configure webhooksHow to create Connection with HubspotHow to customize portal URLs for Stripe and GoCardlessHow to filter webhook eventsHow-to Get a Private Support Channel for Your Unified IntegrationHow to get help fromHow to get your 8x8 Connect API Key, Account ID and SMS Subaccount ID (optional): Step-by-step guideHow to get your ADP Workforce Now Oauth2 client ID, Oauth2 client secret, Oauth2 PEM certificate and Oauth2 private key: Step-by-step guideHow to get your Amazon S3 AWS Region, AWS S3 Key and AWS S3 Secret: Step-by-step guideHow to get your Ashby API Key: Step-by-step guideHow to get your Brex API token: Step-by-step guideHow to get your Bullhorn OAuth2 Client ID, OAuth2 Client Secret, API Username and API Password: Step-by-step guideHow to get your Ceridian Dayforce Username, Password and Client Namespace: Step-by-step guideHow to get your Crelate API key: Step-by-step guideHow to get your Dashlane API Key: Step-by-step guideHow to get your Deel Access Token: Step-by-step guideHow to get your Dialpad API Key: Step-by-step guideHow to get your Discord OAuth 2 credentials and bot tokenHow to get your ELMO client ID and client secret: Step-by-step guideHow to get your Gainsight Client ID, Client Secret and Gainsight API Domain: Step-by-step guideHow to get your Greenhouse API Key and Job board token: Step-by-step guideHow to get your Helpscout API Key: Step-by-step guideHow to get your HiBob Service User ID and Service User Token: Step-by-step guideHow to get your HighLevel API Key and Location ID: Step-by-step guideHow to get your HubSpot developer key and OAuth 2 credentials (Legacy Apps)How to get your Humaans API Key: Step-by-step guideHow to get your iCIMS API Username, API Password and Customer ID: Step-by-step guideHow to get your JobDiva Client ID, Username/email and Password: Step-by-step guideHow to get your Jobvite API Key, API Key Secret and Email: Step-by-step guideHow to get your Lever API Key: Step-by-step guideHow to get your Loxo Agency slug, API Key and Agency ID: Step-by-step guideHow to get your Microsoft Active Directory / Entra ID Client ID, Client Secret and Tenant ID: Step-by-step guideHow to get your Microsoft Azure AD OAuth 2 credentialsHow to get your OAuth 2 credentials for GmailHow to get your OAuth 2 credentials for Microsoft Dynamics 365How to get your OAuth 2 credentials in PipeDriveHow to get your OpenAI API Key: Step-by-step guideHow to get your Paycom SID/Username and Token/Password: Step-by-step guideHow to get your PCRecruiter Username, Password, Database ID, App Key and App ID: Step-by-step guideHow to get your SAP SuccessFactors (OpenID Connect) Username, Password, Client ID, Client Secret, Dependency Name, IAS Host and API URL: Step-by-step guideHow to get your SAP SuccessFactors Username, Company ID, Password and API URL: Step-by-step guideHow to get your Shopify Admin API access token and Store ID: Step-by-step guideHow to get your Wayfair Client ID, Client Secret and Vendor Encrypted Key: Step-by-step guideHow to get your Workable API Token and Subdomain: Step-by-step guideHow to get your yotpo APP Key / Store ID and Secret Key: Step-by-step guideHow to Handle Attachments in Invoice, Bill and Credit MemoHow to Manage Google Ad Manager Orders, Line Items and Creatives with theHow to migrate or import your integrations into Unified.toHow to obtain your GitHub OAuth2 credentialsHow to Power Claude with Live Customer Data Using Unified MCPHow to receive assessment orders from an ATS with Unified.toHow to register a Google developer app and get OAuth 2 credentialsHow to register a Salesforce developer app and get OAuth 2 credentialsHow to register a Slack developer account and get OAuth 2 credentialsHow to Register a Workday Developer App and Get OAUTH2 CredentialsHow to Register a Workday Developer App and Get OAUTH2/ SOAP CredentialsHow to Register a ZendeskSell Developer App and Get OAUTH2 CredentialsHow to Register a Zoho Developer App and Get OAUTH2 CredentialsHow to Register an ADP Developer App and Get OAUTH2 CredentialsHow to Register an Atlassian Developer App and Get OAUTH2 CredentialsHow to Register your Facebook OAuth2 ApplicationHow to Register your Google Ads OAuth2 ApplicationHow to Register your MetaAds OAuth2 applicationHow To Request & Write Raw Integration DataHow to Retrieve Microsoft Dynamics 365 Business Central CredentialsHow to set up a custom API URL with a CNAMEHow to Set Up a Google Meet Meeting Bot with UnifiedHow to set up a HiBob marketplace installHow to Set Up a Microsoft Teams Bot with UnifiedHow to Set Up a Microsoft Teams Meeting Bot with UnifiedHow to Set Up a Webex Meeting Bot with UnifiedHow to Set Up a Zoom Meeting Bot with UnifiedHow to set up and configure NotionHow to set up Google Business Profile API access and get OAuth 2 credentialsHow to Set Up LinkedIn Webhooks with UnifiedHow to set up native webhooks for QuickBooks Online with UnifiedHow to set up Slack webhooks using event subscriptionsHow to set up Telegram (bot) with Unified.toHow to set up your scopes in HubSpotHow to setup a Freshbooks developer appHow to setup a TikTok Shop applicationHow to Setup AWS Assume Role for AWS Secret ManagerHow to setup Oracle JD EdwardsHow to Setup Quickbooks DesktopHow to setup Sage 100 with Unified.toHow to test webhooks in the Synthetic Data (Sandbox) environmentHow to troubleshoot unhealthy connectionsHow to troubleshoot unhealthy webhooksHow to Use Decision Models with the Unified GenAI APIHow to use SCIM with the Unified APIHow to use the Passthrough APIHow to Use Unified.to's Generative AI API with OpenAI and ClaudeHow to use User Provisioning and Verification with UnifiedHow virtual webhook retry and recovery worksIntegration set-up guide for LeverManaging custom validation rules in SalesforceNetSuite Authentication Setup for UnifiedNotice of Deprecation of Fields and Objects (Nov 2025)Oracle HCM / Taleo OAuth Credentials GuideRetrieval-Augmented Generation (RAG)SalesForce (External Client Apps) on Multiple OrganizationsSAML Single-Sign-OnScaling MCP Tools with Anthropic's (& OpenAI's) Defer LoadingScaling MCP Tools with Anthropic's Programmatic Tool CallingSet Environments for your Unified.to WorkspaceSetting up a Slack Bot Connection with Unified.toSetting up OAuth 2 Credentials for Greenhouse's APIsTrello Connection Guide in UnifiedUnderstanding OAuth2 Authorization flowsUnderstanding Response Time Headers in the Unified APIUnified Assessment API: Embed Assessments Inside ATS PlatformsUnified's MCP ServerUnified MCP Server with LangChain and LangGraphUnlock real-time data with virtual webhooksUse Unified to sign in your users into your applicationVincere OAuth Setup Guide for UnifiedWhy you can't use Unified's OAuth2 credentials to authorize your end users on ProductionWorkable: Creating candidates and attaching them to jobsWorkday vs Workday Legacy — Why Unified.to Supports BothWorking with hierarchical tree data in Storage, Messaging, and KMS APIs
Are we missing anything? Let us know
Was this page helpful?