Entra ID

This manual sets up Microsoft Entra ID (formerly Azure AD) as the identity provider for two TrustGate patterns in TrustGate (the trust anchor under Settings → Machine identity, then the application’s Authentication):

Validate bearer tokens — an LLM or MCP application whose callers already hold an Entra access token (a service using client credentials, or an app forwarding a user token). TrustGate verifies the token and admits the caller; routing is the application’s own.
OAuth2 · MCP login — an MCP application gated by an exposed API scope. Interactive agents (Cursor, etc.) use TrustGate’s authorization-code broker; optional client-credentials tokens are only for curl checks.

Entra ID issues v2.0 tokens when the app registration uses the v2 endpoint. TrustGate treats an api:// resource URI and its bare identifier as the same audience, and prefers the Entra oid claim as the stable subject. Use the values below exactly.

Prerequisites

An Entra tenant — note your Tenant ID (Overview → Tenant ID).
Rights to register applications (App registrations) and manage Enterprise applications.
For Cursor / agent MCP login: the public MCP base URL of your gateway (e.g. https://{gateway_slug}.mcp.neuraltrust.ai), so you can register the OAuth redirect URI.

SaaS vs Private mcp_base_url: SaaS uses {slug}.mcp.neuraltrust.ai. Private/Hybrid uses the Dataplane MCP URL from Settings → General. Register {mcp_base_url}/oauth/callback on the IdP before testing agent login.

The values you will collect

Placeholder	Where it comes from
`tenant_id`	Entra ID → Overview → Tenant ID
`client_id`	The Application (client) ID of your app registration
`client_secret`	Certificates & secrets → New client secret
`audience`	The Application ID URI — `api://{client_id}` (or the bare `client_id`)
`scope`	A scope you expose under Expose an API (e.g. `mcp.access`)
`mcp_base_url`	Public MCP host for the gateway, with no path

The endpoints are derived from the tenant:

issuer   : https://login.microsoftonline.com/{tenant_id}/v2.0
jwks_url : https://login.microsoftonline.com/{tenant_id}/discovery/v2.0/keys

If your app is configured for v1.0 tokens, the issuer is instead https://sts.windows.net/{tenant_id}/ and the JWKS is https://login.microsoftonline.com/common/discovery/keys. Prefer v2.0.

1. Register the application

Steps use the Microsoft Entra admin center at https://entra.microsoft.com (the same screens exist in the Azure portal under Microsoft Entra ID). Paths below are the left-hand navigation.

Create the registration

In the left sidebar go to Identity → Applications → App registrations → click New registration.

Name: trustgate
Supported account types: pick the one that matches your tenant.
Redirect URI (optional at create time; required for interactive MCP): platform Web, URI {mcp_base_url}/oauth/callback
(example: https://default-xxxxxxxx.mcp.neuraltrust.ai/oauth/callback)

Click Register. On the app’s Overview page copy the Application (client) ID and the Directory (tenant) ID.

Add a client secret

Open the app → left menu Manage → Certificates & secrets → Client secrets tab → New client secret. Set a description and expiry, click Add, then copy the secret Value immediately (it is shown only once — the Secret ID is not the value).

Confirm the redirect URI (for Cursor / MCP)

If you skipped it at registration, open Manage → Authentication → Add a platform → Web, and add:

{mcp_base_url}/oauth/callback

Match character-for-character (no trailing slash). Save.

2. Expose an API scope (for MCP)

Set the Application ID URI

Open the app → left menu Manage → Expose an API. Next to Application ID URI click Add, accept the default api://{client_id}, and Save. This URI is your audience.

Add the scope

Still on Expose an API, click Add a scope:

Scope name: mcp.access
Who can consent: Admins and users (or Admins only) as appropriate.
Fill the admin/user consent display name and description.
State: Enabled.

Click Add scope. The full scope identifier is api://{client_id}/mcp.access.

3. Validate Entra bearer tokens (LLM or MCP)

Use this when the application already obtains its own Entra access token — client credentials for a service, or a user token the application forwards — and sends it as Authorization: Bearer <token>. TrustGate verifies the token; what the application binds on General decides providers and models. Everything below is done in the NeuralTrust app — no API payloads.

Create the trust anchor

Go to Settings → Agent Gateway → Machine identity → Add trust anchor.

Kind: IdP (JWT)
Name: e.g. entra-idp
Issuer: https://login.microsoftonline.com/{tenant_id}/v2.0
Audience: api://{client_id} (the bare {client_id} form is accepted as the same audience)
Advanced: Subject claim oid — a stable per-tenant user id; Entra sub is pairwise per app and changes across apps. Optionally pin JWKS URL to https://login.microsoftonline.com/{tenant_id}/discovery/v2.0/keys.

Save. No client secret is stored: the gateway only verifies tokens.

Attach it to the application

Go to Agent Gateway → Applications, open (or create) the application, and on General → Authentication choose Identity provider and select entra-idp.

Allowed client IDs: the Application (client) ID of every calling application. Entra v2.0 tokens carry it in azp. Leave empty only when the audience is dedicated to this one application.

Save changes. Providers and models stay on General, as for any application.

Call the application

Mint a token (see §5) and send it:

curl https://{llm_host}/{application-slug}/v1/chat/completions \
  -H "Authorization: Bearer $ENTRA_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"Hello"}]}'

401 means the token failed verification; 403 means it verified but its azp is not in Allowed client IDs.

4. OAuth2 for MCP

Use this when Cursor (or another MCP client) should log in through Entra. Access is gated by the exposed API scope (for example mcp.access). TrustGate accepts either:

Delegated (user) tokens — scope appears in the scp claim (what Cursor uses via the authorization-code broker).
Application (client credentials) tokens — grant an app role as an application permission, request api://{client_id}/.default; the granted role appears in roles. TrustGate matches both scp and roles against Required scopes.

Grant API permission (client-credentials / M2M only)

Skip this step for Cursor. For curl M2M tests: open the calling app registration → Manage → API permissions → Add a permission → My APIs → select your trustgate API → Application permissions → tick the app role → Add permissions. Then Grant admin consent for your tenant. Without admin consent the token carries no roles and TrustGate rejects it for missing scopes.

Create the interactive OAuth2 auth

The Machine identity form creates token-validation anchors; an anchor that brokers a login is created with the Admin API and is then listed and editable under Settings → Agent Gateway → Machine identity:

POST /v1/gateways/{gateway_id}/auths
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "name": "entra-mcp",
  "type": "oauth2",
  "enabled": true,
  "config": {
    "oauth2": {
      "issuer": "https://login.microsoftonline.com/{tenant_id}/v2.0",
      "audiences": ["api://{client_id}"],
      "client_id": "{client_id}",
      "client_secret": "{client_secret}",
      "required_scopes": ["mcp.access"],
      "subject_claim": "oid"
    }
  }
}

This is the Interactive login · IdP with discovery setup: leave session_mode off, use the short scope name in required_scopes (not openid / profile / email), and pin jwks_url only if you do not want discovery.

Create an MCP application and attach the auth

Go to Agent Gateway → Applications → New Application.

Name: e.g. entra-mcp
Protocol: MCP
Authentication → Identity provider: select entra-mcp
Allowed client IDs (optional): the app registration’s client ID

Click Create Application. On the application’s General tab, Identity → Acts on behalf of end users with Users sign in makes each person hold their own upstream connections; the application’s servers stay the ones bound on General.

Connect from Cursor

Open the application → Connect tab and copy the Cursor URL:

https://{mcpHost}/{application-slug}/mcp

Add it as an MCP server in Cursor and complete the Entra login. Confirm the Web redirect URI from step 1 is registered, or Entra will reject the callback.

5. Get a test token (optional M2M)

Client credentials are not what Cursor uses. Use this to decode a token and confirm issuer, audience, and scopes, or as the token a service sends in §3:

curl -s --request POST \
  "https://login.microsoftonline.com/$TENANT_ID/oauth2/v2.0/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  -d "scope=api://$CLIENT_ID/.default"

Decode the access_token and confirm:

iss = https://login.microsoftonline.com/{tenant_id}/v2.0
aud = api://{client_id} (or the bare client_id)
azp = the calling application’s client ID (what Allowed client IDs matches)
roles (app permissions) or scp (delegated) contains your scope/role

Troubleshooting

Symptom	Likely cause
Audience mismatch	Token `aud` is the bare `client_id` but the auth lists only `api://…` (or vice versa). TrustGate normalizes the `api://` prefix, so either form works; check for a different app’s ID.
`roles`/`scp` empty	For client credentials you must grant an app role and admin-consent it; delegated tokens need the user assigned and consent granted.
`403 forbidden` on a bearer call	Token verified but its `azp` is not in the application’s Allowed client IDs.
Redirect URI mismatch on login	Add `{mcp_base_url}/oauth/callback` under Authentication → Web on the app registration.
Wrong issuer	App is emitting v1.0 tokens (`sts.windows.net`) — switch to v2 or set the v1 issuer/JWKS.
Config rejected	Required scopes contains `openid`/`profile`/`email`/`offline_access` — remove them.

Back to Authentication.

Start here

Concepts

LLM Gateway

MCP Gateway

Policies

Operate

Prerequisites

The values you will collect

1. Register the application

2. Expose an API scope (for MCP)

3. Validate Entra bearer tokens (LLM or MCP)

4. OAuth2 for MCP

5. Get a test token (optional M2M)

Troubleshooting

​Prerequisites

​The values you will collect

​1. Register the application

​2. Expose an API scope (for MCP)

​3. Validate Entra bearer tokens (LLM or MCP)

​4. OAuth2 for MCP

​5. Get a test token (optional M2M)

​Troubleshooting

Prerequisites

The values you will collect

1. Register the application

2. Expose an API scope (for MCP)

3. Validate Entra bearer tokens (LLM or MCP)

4. OAuth2 for MCP

5. Get a test token (optional M2M)

Troubleshooting