Okta

This manual sets up Okta 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 Okta 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 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.
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 → 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 trust anchor. 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. Validate Okta bearer tokens (LLM or MCP)

Use this when the application already obtains its own Okta 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. okta-idp
Issuer: https://{okta_domain}/oauth2/{okta_auth_server_id}
(example: https://dev-123456.okta.com/oauth2/default)
Audience: the authorization server audience (example: api://default)
Advanced (optional): pin JWKS URL to https://{okta_domain}/oauth2/{okta_auth_server_id}/v1/keys, restrict Allowed algorithms, set Required scopes, or change Subject claim from sub.

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 okta-idp.

Allowed client IDs: the Okta Client ID of every application that may call this application. TrustGate matches the token’s azp claim, else client_id. Okta access tokens carry the client id as cid, which TrustGate does not read — to use this list, add a custom claim on the authorization server (Claims → Add Claim: name client_id, include in Access Token, value type Expression, value access.clientId). Leave the list 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 from Okta (see §5) and send it:

curl https://{llm_host}/{application-slug}/v1/chat/completions \
  -H "Authorization: Bearer $OKTA_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 client id is not in Allowed client IDs.

4. 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 /{application-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 application 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 /{application-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 MCP application’s 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 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": "okta-mcp",
  "type": "oauth2",
  "enabled": true,
  "config": {
    "oauth2": {
      "issuer": "https://dev-123456.okta.com/oauth2/default",
      "audiences": ["api://default"],
      "client_id": "{okta_client_id}",
      "client_secret": "{okta_client_secret}",
      "required_scopes": ["mcp.access"]
    }
  }
}

This is the Interactive login · IdP with discovery setup: leave session_mode off (Okta issues JWTs; session mode is for opaque-token IdPs such as GitHub) and do not add openid / profile / email to required_scopes. jwks_url is optional — TrustGate resolves keys from the issuer.

Create an MCP application and attach the auth

Go to Agent Gateway → Applications → New Application.

Name: e.g. okta-mcp
Protocol: MCP
Authentication → Identity provider: select okta-mcp
Allowed client IDs (optional): the Web app’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. Copy the Cursor snippet (URL only — no API key):

https://{mcpHost}/{application-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 on the auth, 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.

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. 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"]
client_id (the custom claim from §3, if you use Allowed client IDs) = the Client ID you listed

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` on the 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 §6.
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 under Machine identity, or the MCP client is pointing at a different gateway / application.
`401` / no token minted	No access policy/rule on the authorization server (step 2), or the rule omits Authorization Code.
`401` on a bearer call	Token failed verification: wrong issuer, expired, or `aud` not in Audience. Decode it and compare with §5.
`403 forbidden` on a bearer call	Token verified but its `azp` / `client_id` is not in the application’s Allowed client IDs — or the token only carries Okta’s `cid` and the custom `client_id` claim from §3 is missing.
`missing required scopes`	The client wasn’t granted `mcp.access`, or Required scopes on the auth does not match.
Audience mismatch	Audience on the auth doesn’t equal the token’s `aud` (`api://default` on the `default` server).
Config rejected	Required scopes contains `openid`/`profile`/`email`/`offline_access` — remove them.

Next: Entra ID.

Start here

Concepts

LLM Gateway

MCP Gateway

Policies

Operate

Prerequisites

The values you will collect

1. Authorization server

2. Add a custom scope (for MCP)

3. Validate Okta bearer tokens (LLM or MCP)

4. OAuth2 for MCP

5. Get a test token (optional M2M)

Troubleshooting

​Prerequisites

​The values you will collect

​1. Authorization server

​2. Add a custom scope (for MCP)

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

​4. OAuth2 for MCP

​How interactive MCP login works

​5. Get a test token (optional M2M)

​6. Force Okta login again (clear session)

​Troubleshooting

Prerequisites

The values you will collect

1. Authorization server

2. Add a custom scope (for MCP)

3. Validate Okta bearer tokens (LLM or MCP)

4. OAuth2 for MCP

How interactive MCP login works

5. Get a test token (optional M2M)

6. Force Okta login again (clear session)

Troubleshooting