Skip to main content
This guide shows how to wire Microsoft Entra ID On-Behalf-Of (OBO) through the TrueFoundry MCP Gateway. Callers authenticate to TrueFoundry with an inbound token - a user access token audienced to the Entra app that represents TrueFoundry. On every MCP tool call, the gateway exchanges that token for a new Entra token audienced to your downstream MCP, so the MCP server sees the user - not a shared service principal. Use this when:
  • The MCP server validates Entra JWTs.
  • You need delegated user identity on the outbound call (oid / preferred_username preserved).
  • You do not want interactive Authorization Code consent in the Gateway for every user (contrast with Azure Entra OAuth MCP Server).

​
Architecture

​
Values you need

​
Guide to setting up Azure Entra OBO with TrueFoundry

1

Create the downstream MCP app registration

This app is the protected MCP resource that TrueFoundry OBO exchanges into. Your MCP server validates tokens whose aud is this app’s client ID. It is not the OBO client and not a public login app.
Create the app registration
  1. Entra admin center → App registrations → New registration.
  2. Configure:
    • Name: e.g. mcp-azure
    • Supported account types: Choose based on your needs
    • Redirect URI: leave empty (not required for an OBO resource)
  3. Click Register.
  4. Copy Application (client) ID (<<mcp_client_id>>) and Directory (tenant) ID (<<tenant_id>>).
Expose the API
  1. Open the downstream app → Expose an API.
  2. Application ID URI → Add → api://<<mcp_client_id>> → Save.
Azure Expose an API Application ID URI
  1. Click Add a scope:
    • Scope name: access_as_user
    • Who can consent: Admins and users
    • Admin / user consent display name and description: e.g. Access azure-mcp
    • State: Enabled
  2. Click Add scope.
Azure Expose an API Add a scope dialog
2

Create the TrueFoundry inbound app registration

The TrueFoundry inbound app is both the app users authenticate to (incoming token audience) and the confidential client that performs OBO to downstream.
Create the TrueFoundry inbound app
  1. Entra admin center → App registrations → New registration.
  2. Configure:
    • Name: e.g. azure-truefoundry
    • Supported account types: Choose based on your needs
    • Redirect URI (optional): platform Web, https://jwt.ms (useful for admin consent)
  3. Click Register.
  4. Copy Application (client) ID (<<truefoundry_client_id>>).
Expose the API
  1. Open the created app → Expose an API.
  2. Application ID URI → api://<<truefoundry_client_id>> → Save.
  3. Add a scope:
    • Scope Name: access_as_user
    • Who can consent: Admins and users
    • Admin / user consent display name and description: e.g. Access azure-truefoundry
    • State: Enabled
  4. Click Add scope.
Allow users to sign in to TrueFoundry inbound directlyTrueFoundry inbound must accept interactive / device-code login for its own scope.
  1. TrueFoundry inbound app → Authentication.
  2. Add a platform → Mobile and desktop applications.
  3. Enable https://login.microsoftonline.com/common/oauth2/nativeclient -> Click on Configure
  4. Navigate to Settings → Enable Allow public client flows
  5. Click Save.
Grant TrueFoundry inbound permission to call downstream
  1. TrueFoundry inbound app → API permissions → Add a permission.
  2. My APIs → select the downstream app (mcp-azure).
  3. Delegated permissions → access_as_user → Add permissions.
  4. (Recommended) Also, add this app’s own delegated access_as_user (Add a permissions → My APIs → TrueFoundry inbound), so device-code / silent login against TrueFoundry inbound is consented.
  5. Grant admin consent for your tenant.
Azure API permissions selecting My APIsClient credentials for the OBO callOption1: Client secret
  1. Certificates & secrets → Client secrets → New client secret → Add.
  2. Copy the Value immediately (<<truefoundry_client_secret>>).
Azure Certificates and secrets client secretOption2: Certificate
  1. Generate a key pair; upload the public certificate under Certificates → Add.
  2. Copy the Thumbprint; keep the private key for TrueFoundry / your service.
3

Configure JWT validation on the MCP server

Your MCP server must validate Entra JWTs for the outbound audience:
  • Issuer: https://login.microsoftonline.com/<<tenant_id>>/v2.0
  • JWKS URI: https://login.microsoftonline.com/<<tenant_id>>/discovery/v2.0/keys
  • Audience: <<mcp_client_id>> (the outbound token audience - not the TrueFoundry inbound client ID)
  • Discovery URL (if your runtime uses OpenID discovery): https://login.microsoftonline.com/<<tenant_id>>/v2.0/.well-known/openid-configuration
Use the same JWT verification pattern as JWT verification in the Azure OAuth guide.
4

Add an Identity Provider in TrueFoundry

TrueFoundry must validate the TrueFoundry inbound token and map it to a virtual account.
  1. Go to Settings → Security & Access → Identity Providers (or Settings with section identity-providers).
  2. Add a provider (UI or Apply using YAML).
See Identity Providers for field reference.
5

Create a Virtual Account and map the TrueFoundry inbound client

  1. Go to Access → Virtual Accounts.
  2. Create a virtual account and grant MCP access. Example YAML:
The mapping value must equal the JWT claim configured as name claim (azp). When azp is the TrueFoundry inbound client ID, map that client ID here.Tighten resource_fqn to a specific MCP server FQN in production instead of *.See Manage Virtual Accounts.
6

Register the MCP server with OAuth2 jwt-bearer (OBO)

  1. Go to AI Gateway → MCP Servers → add / edit a Remote MCP server.
  2. Set the URL to your MCP endpoint.
  3. Configure Auth Data → OAuth2 with provider Microsoft Entra and grant type JWT Bearer / On-Behalf-Of (jwt_bearer).
Store client_secret as a TrueFoundry Secret FQN when possible instead of a raw value.The Gateway then sends the caller’s TrueFoundry inbound Bearer token as the OBO assertion, exchanges it at token_url, and forwards the outbound access token to the MCP URL.
7

Obtain a TrueFoundry inbound token and call the Gateway

Generate a user access token whose audience is the TrueFoundry inbound app (not the MCP API app).Call the MCP Gateway with that token:
Adjust the MCP path to match your tenant’s MCP Gateway URL format.

​
Inbound vs outbound token claims

Typical claim differences after a successful Gateway OBO exchange: If the MCP server rejects the call, confirm its configured audience is the outbound aud (<<mcp_client_id>>), not the TrueFoundry inbound client ID.

​
FAQ

Azure Entra OAuth MCP Server uses the Authorization Code flow (and optionally client credentials). Users consent in a browser, and the Gateway stores and refreshes OAuth tokens for that MCP server.This OBO guide assumes the caller already presents a TrueFoundry inbound Entra user access token. The Gateway does not run a consent redirect for that user on the MCP server. On tool call it exchanges the inbound token (OBO / jwt_bearer) for a downstream access token and forwards that to the MCP URL.
In Entra access tokens, azp is the authorized party - the client application that obtained the token. TrueFoundry’s Identity Provider name_claim: azp maps that value to a virtual account. The virtual account’s mapping value must equal the azp you see on inbound tokens (often <<truefoundry_client_id>> when users sign in through the TrueFoundry inbound app; it can be another client ID if a different app acquires tokens for the TrueFoundry inbound API).slug_claim: oid uses the Entra user object ID so traces, metrics, and per-user controls can still distinguish people who share the same virtual account. See Resolve to a virtual account (Name Claim + optional User Slug Claim).
No. Microsoft Entra OBO only accepts a user assertion (On-Behalf-Of flow). An app-only / client-credentials token cannot be the inbound subject for the exchange.Sign the user in (device code, native client, SPA, etc.) so the token’s aud matches the TrueFoundry Identity Provider audience (<<truefoundry_client_id>> in this guide).