NeuralTrust | Platform for Agent Security.

This manual sets up Okta 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 groups claim (roles).
OAuth2 · MCP — an MCP consumer gated by a custom scope. Interactive agents (Cursor, Claude Desktop, MCP Inspector) use TrustGate’s authorization-code broker; optional client-credentials tokens are only for curl checks.

Everything below uses Okta’s custom authorization server (the /oauth2/{authServerId} path). The default custom auth server ships in every Okta org, including the free Integrator Free Plan org — ideal for a POC. In production Workforce orgs the custom authorization server feature is the API Access Management product.

Prerequisites

An Okta org — note your domain, e.g. dev-123456.okta.com.
Admin access to Security → API and Applications.
A group you can route on (e.g. TrustGate-Engineering) under Directory → Groups.
For Cursor / agent MCP login: the public MCP base URL of your gateway (e.g. https://default-xxxxxxxx.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
`okta_domain`	Your org host, e.g. `dev-123456.okta.com`
`okta_auth_server_id`	Security → API → Authorization Servers (use `default` or a custom id)
`okta_audience`	The Audience of that authorization server (default: `api://default`)
`okta_client_id` / `okta_client_secret`	The OIDC Web Application you create for MCP (not API Services)
`okta_scope`	A custom scope you define on the authorization server
`mcp_base_url`	Public MCP host for the gateway, with no path. NeuralTrust-hosted defaults look like `https://{gateway_slug}.mcp.neuraltrust.ai` (provisioned defaults use `default-{first8OfTeamId}`)

1. Authorization server

All steps happen in the Okta Admin Console at https://<your-org>-admin.okta.com (the admin console, not the end-user dashboard). Use the left sidebar to navigate.

Open the authorization servers list

In the left sidebar go to Security → API, then open the Authorization Servers tab.

Pick or create the server

Use the row named default, or click Add Authorization Server (top right) and fill:

Name: trustgate
Audience: api://trustgate
Description: anything.

Click Save.

Record the issuer and audience

Open the server and read the Settings tab. Copy the Issuer URI (https://{okta_domain}/oauth2/{okta_auth_server_id}) and the Audience — you will paste both into the TrustGate credential. The keys endpoint is the issuer plus /v1/keys:

https://{okta_domain}/oauth2/{okta_auth_server_id}/v1/keys

2. Add a custom scope (for MCP)

Stay in Security → API → Authorization Servers → your server; the tabs below are on that server’s detail page.

Create the scope

Open the Scopes tab → click Add Scope:

Name: mcp.access
Display phrase: MCP access
Tick Include in public metadata.

Click Create.

Add an access policy

Open the Access Policies tab → click Add Policy:

Name: trustgate
Assign to clients: All clients (or select your app once it exists).

Click Create Policy.

Add a rule to the policy

On the policy you just created click Add Rule:

Rule name: mcp
Grant type: tick Authorization Code (required for Cursor and other interactive MCP clients). Also tick Client Credentials if you want curl / M2M test tokens from the same app.
Scopes requested: Any scopes (or The following scopes → mcp.access).

Click Create Rule.

A brand-new custom authorization server (including default on the free org) has no access policy — without a policy and a rule, Okta will not mint any token. Interactive MCP login fails if the rule only allows Client Credentials.

3. Add a groups claim (for role-based routing)

For OIDC role-based routing, the token must carry the claim you match roles on.

Create a group (if you don't have one)

In the left sidebar go to Directory → Groups → Add Group. Name it TrustGate-Engineering, save, then open it and use Assign people to add users.

Add the claim

Back in Security → API → Authorization Servers → your server, open the Claims tab → Add Claim:

Name: groups
Include in token type: Access Token → Always (repeat for ID Token if you also send ID tokens)
Value type: Groups
Filter: Matches regex .* (or Starts with TrustGate- to scope it)

Click Create.

Verify

After you mint a token (below), decode it and confirm the groups array carries the user’s group names.

4. OIDC identity-based routing (LLM)

Use this when an LLM consumer should pick registries and models from the caller’s Okta token (for example the groups claim). 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. okta-idp
Status: Active
Issuer: https://{okta_domain}/oauth2/{okta_auth_server_id}
(example: https://dev-123456.okta.com/oauth2/default)
JWKS URL: https://{okta_domain}/oauth2/{okta_auth_server_id}/v1/keys
Audiences: the authorization server audience (example: api://default)
Subject claim (optional): leave as sub unless your tokens use another claim

Click Create Auth.You can also create the same OIDC auth inline later from a consumer’s auth picker (Create Auth entity ”…”).

Create a role that matches Okta groups

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

Role name: e.g. engineering
Claim: groups (the JWT claim path from step 3)
Value: the Okta group name to match, e.g. TrustGate-Engineering
(the UI maps this as “claim contains any of these values”)
Resources: Add resource and select the LLM registries (and optional models) this role may reach

Click Create Role. Create additional roles if you need more group → resource mappings.

Create an LLM consumer with Identity-based routing

Go to Agent Gateway → Consumers → Consumer (new consumer panel).On General:

Name: e.g. okta-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, open it and set the same options on the Auth and Routing tabs, 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 Okta. Access is gated by the custom scope from step 2 (for example mcp.access). Agents such as Cursor do not call Okta with client credentials. They talk to TrustGate’s MCP OAuth facade (authorization code + PKCE):

The agent discovers TrustGate as the authorization server (/.well-known/oauth-protected-resource — often path-scoped to /{consumer_slug}/mcp — and /.well-known/oauth-authorization-server).
It opens TrustGate /oauth/authorize.
TrustGate redirects the browser to Okta’s authorize endpoint using the Web app Client ID from your OAuth2 auth, with redirect_uri={mcp_base_url}/oauth/callback (host root — not under the consumer path).
After the user signs in, Okta returns to TrustGate /oauth/callback; TrustGate finishes the agent handshake.
If the virtual MCP has upstream providers (Notion, Linear, …), TrustGate may show a Connect your accounts page at /{consumer_slug}/mcp/connect after Okta succeeds — that is a separate consent detour, not a substitute for Okta login.

Do not create an Okta API Services app for this credential. API Services apps have application_type: service and Okta rejects them on /authorize with:Clients with 'application_type' of 'service' are not allowed to access the 'authorize' endpoint.Use an OIDC Web Application. Keep a separate API Services client only if you want standalone M2M curl tests — never paste that client into the app’s MCP OAuth2 auth.

Create an OIDC Web Application in Okta

In the Okta Admin Console go to Applications → Applications → Create App Integration:

Sign-in method: OIDC - OpenID Connect
Application type: Web Application → Next
App integration name: trustgate-mcp
Grant types: tick Authorization Code (required). Optionally tick Refresh Token, and Client Credentials if you also want curl M2M tests from this same app.
Sign-in redirect URIs: add exactly
{mcp_base_url}/oauth/callback
Example:
https://default-xxxxxxxx.mcp.neuraltrust.ai/oauth/callback
Match character-for-character (scheme, host, path /oauth/callback, no trailing slash).
Controlled access: assign the users or groups that should be able to connect (or allow everyone in the org for a POC).

Click Save. On the app’s General tab copy the Client ID and Client secret. Confirm the access-policy rule from step 2 allows Authorization Code and the mcp.access scope for this client.

Create an OAuth2 auth in the app

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

Type: OAuth2
Name: e.g. okta-mcp
Status: Active
Setup: Interactive login · IdP with discovery (Okta, Entra ID)
Issuer: https://{okta_domain}/oauth2/{okta_auth_server_id}
(example: https://dev-123456.okta.com/oauth2/default)
Audiences: the authorization server audience (example: api://default)
Client ID / Client secret: from the Web app above
Session mode: Disabled (Okta issues JWTs; session mode is for opaque-token IdPs such as GitHub)
Required scopes: mcp.access (do not add openid / profile / email)

You can leave Token validation · advanced closed — TrustGate can resolve JWKS from the issuer. Open it only if you want to pin JWKS URL explicitly to https://{okta_domain}/oauth2/{okta_auth_server_id}/v1/keys.Click Create Auth.

Create an MCP consumer and attach the auth

Go to Agent Gateway → Consumers → Consumer.

Name: e.g. okta-mcp
Protocol: MCP
Authentication → Method: OAuth2 (MCP does not use OIDC)
OAuth client: select the auth from the previous step (or create one inline via Create Auth entity ”…”)

Click Create Consumer.

Connect from Cursor

Open the consumer → Connect tab. Copy the Cursor snippet (URL only — no API key):

https://{mcpHost}/{consumer_slug}/mcp

Add it as an MCP server in Cursor and start authentication. You should land on Okta (login or an existing SSO session), then optionally TrustGate Connect your accounts, then return to Cursor.After you change the Okta Client ID in the app, confirm the next browser authorize URL’s client_id= matches the Web app — a stale API Services client id means the auth was not saved or the agent is still using an old server config.

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. The Okta app must allow the Client Credentials grant on the access-policy rule (and on the Web app if you enabled that grant type).

curl -s --request POST \
  "https://dev-123456.okta.com/oauth2/default/v1/token" \
  -u "$OKTA_CLIENT_ID:$OKTA_CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&scope=mcp.access"

Decode the access_token and confirm:

iss = https://dev-123456.okta.com/oauth2/default
aud = api://default
scp = ["mcp.access"]

If the browser skips the Okta UI and jumps straight to TrustGate’s connect page, you already had an Okta SSO cookie. To see login again:

Sign out at https://{okta_domain}, or use a private / incognito window.
Clear site data for {okta_domain} (and optionally {mcp_base_url} if a connect ticket is stuck).
In Admin → Directory → People → your user, clear active sessions if available.
Retry MCP auth from the agent.

Troubleshooting

Symptom	Likely cause
`Clients with 'application_type' of 'service' are not allowed to access the 'authorize' endpoint`	The OAuth2 auth uses an API Services client. Create an OIDC Web Application and update Client ID / Client secret in Identity → Auth.
`The 'redirect_uri' parameter must be a Login redirect URI in the client app settings`	Add `{mcp_base_url}/oauth/callback` under the Web app’s Sign-in redirect URIs (exact match).
Okta login never appears	Existing Okta session in the browser — see §7.
Lands on Connect your accounts (Notion / Linear / …)	Okta already succeeded; that page is the optional upstream-provider consent detour. Click Continue to finish returning to the agent.
Authorize URL still has the old `client_id`	Auth not updated in Identity, or the MCP client is pointing at a different gateway / consumer.
`401` / no token minted	No access policy/rule on the authorization server (step 2), or the rule omits Authorization Code.
`missing required scopes`	The client wasn’t granted `mcp.access`, or Required scopes on the auth does not match.
Audience mismatch	Audiences on the auth doesn’t equal the token’s `aud` (`api://default` on the `default` server).
Role never selected	`groups` claim not added to the token type you send, or the role Claim / Value exclude the group (step 3).
Config rejected	Required scopes contains `openid`/`profile`/`email`/`offline_access` — remove them.

Next: Entra ID.

Introduction

Getting started

Console

Core concepts

Routing

Policies

MCP

Observability

Operate

Admin API

API reference

Okta

Prerequisites

The values you will collect

1. Authorization server

2. Add a custom scope (for MCP)

3. Add a groups claim (for role-based 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. Authorization server

​2. Add a custom scope (for MCP)

​3. Add a groups claim (for role-based routing)

​4. OIDC identity-based routing (LLM)

​5. OAuth2 for MCP

​How interactive MCP login works

​6. Get a test token (optional M2M)

​7. Force Okta login again (clear session)

​Troubleshooting

Prerequisites

The values you will collect

1. Authorization server

2. Add a custom scope (for MCP)

3. Add a groups claim (for role-based routing)

4. OIDC identity-based routing (LLM)

5. OAuth2 for MCP

How interactive MCP login works

6. Get a test token (optional M2M)

7. Force Okta login again (clear session)

Troubleshooting