NeuralTrust | Platform for Agent Security.

This manual sets up Microsoft Entra ID (formerly Azure AD) as the identity provider for two TrustGate patterns in the NeuralTrust app (Agent Gateway → Identity / Consumers):

OIDC · Identity-based LLM — an LLM consumer whose routing is chosen from the token’s roles (app roles) or groups claim (roles).
OAuth2 · MCP — an MCP consumer 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.
A group or set of users you can assign to an app role.
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 → Agent Gateway → 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. Define app roles (for identity-based LLM routing)

App roles are the cleanest way to drive TrustGate roles; they arrive in the roles claim.

Create the app role

Open the app → left menu Manage → App roles → Create app role:

Display name: Engineering
Allowed member types: Users/Groups (and/or Applications for M2M).
Value: engineering — this exact string is what appears in the roles claim.
Description: anything.
Tick Do you want to enable this app role?

Click Apply.

Assign users or groups to the role

Assignment happens on the enterprise application (the service principal), not the registration. In the left sidebar go to Identity → Applications → Enterprise applications → open your trustgate app → Manage → Users and groups → Add user/group. Pick the users/groups, and under Select a role choose Engineering. Click Assign.

(Optional) emit a groups claim instead

To route on directory groups instead of app roles, open the app registration → Manage → Token configuration → Add groups claim, pick the group types, and save. The token then carries a groups array of group object IDs (GUIDs), not names.

4. OIDC identity-based routing (LLM)

Use this when an LLM consumer should pick registries and models from the caller’s Entra token (app role roles, or directory groups). Everything below is done in the NeuralTrust app under Agent Gateway — no API payloads. Recommended order: Auth → Role → Consumer.

Create an OIDC auth

Go to Agent Gateway → Identity → Auth → New Auth.

Type: OIDC
Name: e.g. entra-idp
Status: Active
Issuer: https://login.microsoftonline.com/{tenant_id}/v2.0
JWKS URL: https://login.microsoftonline.com/{tenant_id}/discovery/v2.0/keys
Audiences: api://{client_id} (add the bare {client_id} as well if your tokens use that form)
Subject claim: oid
(oid is a stable per-tenant user id; Entra sub is pairwise per app and changes across apps)

Click Create Auth.

Create a role that matches Entra app roles

Still under Identity, open the Roles tab → New Role.

Role name: e.g. engineering
Claim: roles (or groups if you emit directory groups instead)
Value: the app role Value from step 3, e.g. engineering
(for directory groups, use the group object ID GUID, not the display name)
Resources: Add resource and select the LLM registries (and optional models) this role may reach

Click Create Role.

Create an LLM consumer with Identity-based routing

Go to Agent Gateway → Consumers → Consumer.On General:

Name: e.g. entra-llm
Protocol: LLM
Authentication → Method: OIDC
OIDC provider: select the auth from the first step

On Routing:

Switch from Static to Identity-based
Roles: select the role(s) you created (at least one)

Click Create Consumer.For an existing consumer, use the Auth and Routing tabs the same way, then Save changes. With Identity-based routing, registries come from the role’s resources — not from a static list on the consumer.

5. 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 an OAuth2 auth in the app

Go to Agent Gateway → Identity → Auth → New Auth.

Type: OAuth2
Name: e.g. entra-mcp
Status: Active
Setup: Interactive login · IdP with discovery (Okta, Entra ID)
Issuer: https://login.microsoftonline.com/{tenant_id}/v2.0
Audiences: api://{client_id}
Client ID / Client secret: from the app registration
Session mode: Disabled
Required scopes: mcp.access (the short scope name — not openid / profile / email)

Leave Token validation · advanced closed unless you want to pin JWKS URL to https://login.microsoftonline.com/{tenant_id}/discovery/v2.0/keys.Click Create Auth.

Create an MCP consumer and attach the auth

Go to Agent Gateway → Consumers → Consumer.

Name: e.g. entra-mcp
Protocol: MCP
Authentication → Method: OAuth2 (MCP does not use OIDC)
OAuth client: select the auth from the previous step

Click Create Consumer.

Connect from Cursor

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

https://{mcpHost}/{consumer_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.

6. Get a test token (optional M2M)

Client credentials are not what Cursor uses. Use this only to decode a token and confirm issuer, audience, and scopes:

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)
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). Add both forms to Audiences if unsure — TrustGate normalizes the `api://` prefix.
`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.
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.
Role never selected	`groups` claim carries object IDs, not names — put the GUID in the role Value, or match app-role `roles` values instead.
Config rejected	Required scopes contains `openid`/`profile`/`email`/`offline_access` — remove them.

Back to the Authorization overview.

Introduction

Getting started

Console

Core concepts

Routing

Policies

MCP

Observability

Operate

Admin API

API reference

Entra ID

Prerequisites

The values you will collect

1. Register the application

2. Expose an API scope (for MCP)

3. Define app roles (for identity-based LLM routing)

4. OIDC identity-based routing (LLM)

5. OAuth2 for MCP

6. 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. Define app roles (for identity-based LLM routing)

​4. OIDC identity-based routing (LLM)

​5. OAuth2 for MCP

​6. 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. Define app roles (for identity-based LLM routing)

4. OIDC identity-based routing (LLM)

5. OAuth2 for MCP

6. Get a test token (optional M2M)

Troubleshooting