Configure Okta
Use Okta as the identity provider for your Dtwo gateway, with OAuth for Claude Code, Claude Desktop, Codex, and Cursor.
On this page
Overview
Okta can act as the identity provider for your Dtwo gateway, allowing users to sign in with their existing Okta accounts. You create a custom authorization server in your own Okta org that issues tokens for the gateway. Each AI client that connects to the gateway is registered as its own Okta application with the redirect URI that client uses.
This guide requires an Okta org that supports custom authorization servers (Security → API → Authorization Servers).
Create an authorization server in Okta
- In the Okta Admin Console, go to Security → API → Authorization Servers and select Add Authorization Server:
- Name: your gateway’s name (for example
Dtwo Gateway) - Audience: your gateway’s MCP URL, found in the Overview tab for your gateway in the Dtwo UI. This is your
<GatewayURL>. - Select Save.
- Name: your gateway’s name (for example
- Set the issuer to Okta URL and copy the Issuer URI. It looks like
https://<OktaDomain>/oauth2/<ServerId>. This is your<Issuer>. - Open the authorization server’s Access Policies tab and select Add Policy:
- Name:
Default Policy - Description:
Default Policy - Select Create Policy.
- Name:
- In the new policy, select Add Rule:
- Name:
Authorization Code - Grant type is: Authorization Code
- Leave the remaining fields at their defaults: User is any user assigned the app, Scopes requested any scopes, no inline hook, a 1-hour access token lifetime, and a 90-day refresh token lifetime.
- Select Create rule.
- Name:
Configure your Dtwo gateway
Go to your gateway in the Dtwo UI and open Configuration → Authentication. Select Custom and fill in:
- Signing algorithm:
RS256 - JWKS URI:
<Issuer>/v1/keys - Issuer:
<Issuer> - Audience:
<GatewayURL> - SSO issuer:
<Issuer>
Select Save Changes, then deploy the gateway.
If you prefer to edit the YAML directly, open Configuration → Advanced and add the following entry to the gateway section:
authentication:
enabled: true
jwks_info:
jwt_algorithm: "RS256"
jwt_jwks_uri: "<Issuer>/v1/keys"
jwt_issuer: "<Issuer>"
jwt_audience: "<GatewayURL>"
sso_issuer: "<Issuer>"
mcp_oauth_resource_metadata_enabled: true
jwt_issuer_verification: true
jwt_audience_verification: true
require_jti: false
require_token_expiration: true
sso_generic_scope: openid profile email
Replace the placeholder values:
<Issuer>— the Issuer URI of the authorization server you created in step 2.<GatewayURL>— your gateway’s MCP URL, found in the Overview tab for your gateway in the Dtwo UI. This is the same URL you set as the authorization server’s Audience.
Save the configuration and deploy the gateway.
Register your AI clients and test the connection
Each AI client needs its own app integration in Okta, because each one has a different redirect URI. Pick your client below to register it, then connect it for yourself to check that sign-in and the gateway work before you roll it out to your organization.
Register Claude Desktop in Okta
- Go to Applications and Resources → Applications and select Create App Integration.
- Set Sign-in method to OIDC - OpenID Connect and Application type to Single-Page Application, then select Next.
- Fill in the app settings:
- App integration name:
Claude Desktop - Client definition: Use Okta-generated client ID
- Grant type: Authorization Code and Refresh Token
- Sign-in redirect URIs:
https://claude.ai/api/mcp/auth_callback - Controlled access: assign the users or groups who may use the gateway through this client
- App integration name:
- Select Save, then copy the Client ID from the General tab — this is the client’s
<ClientId>.
Connect Claude Desktop
- Open the place where you add connectors:
- Free, Pro, and Max: in Claude Desktop, open Customize → Connectors and click Add custom connector.
- Team and Enterprise: open Organization settings → Connectors, click Add, then Custom. If you’re asked for a connector type, choose Web. You need to be an Owner, or on Enterprise, have a custom role that manages the organization’s libraries. This adds the gateway for your whole organization, not just for you.
- Name the connector after your gateway, if asked, and enter your gateway’s MCP URL. Copy it from your gateway’s Overview tab in the Dtwo UI. It must start with
https://. - Choose Use your own OAuth client and enter the
<ClientId>you copied when you registered the client in your identity provider. - Click Add.
- Click Connect and sign in when your browser opens. On Team and Enterprise, you’ll find Connect under Customize → Connectors, not in Organization settings.
- Start a new chat, click + in the message box, choose Connectors, and switch your gateway’s connector on. A connector that’s added but switched off is never used.
Register Claude Code in Okta
- Go to Applications and Resources → Applications and select Create App Integration.
- Set Sign-in method to OIDC - OpenID Connect and Application type to Single-Page Application, then select Next.
- Fill in the app settings:
- App integration name:
Claude Code - Client definition: Use Okta-generated client ID
- Grant type: Authorization Code and Refresh Token
- Sign-in redirect URIs:
http://localhost:33418/callback - Controlled access: assign the users or groups who may use the gateway through this client
- App integration name:
- Select Save, then copy the Client ID from the General tab — this is the client’s
<ClientId>.
Connect Claude Code
In a terminal, add the gateway as an MCP server:
claude mcp add --transport http --scope user <GatewayName> <GatewayURL> --client-id <ClientId> --callback-port 33418
Replace the placeholders:
<GatewayName>: your gateway’s name. This is the name you’ll see for the server in Claude Code.<GatewayURL>: your gateway’s MCP URL. Copy it from your gateway’s Overview tab in the Dtwo UI. It must start withhttps://.<ClientId>: the client ID you copied when you registered the client in your identity provider.
The --callback-port must match the port in the redirect URI registered for Claude Code in your identity provider.
--scope sets where the gateway is available:
--scope user(used above): every project you open in Claude Code.--scope local: only the project you ran the command in, and only for you. This is the default if you leave--scopeout.--scope project: the project you ran the command in, for everyone who works on it. Claude Code saves the gateway to a.mcp.jsonfile in the project, which you commit to your repository.
Then start Claude Code, run /mcp, select your gateway, and sign in when your browser opens.
To share the setup through your repository without running the command, add the gateway to .mcp.json at the project root yourself, using the same values:
{
"mcpServers": {
"<GatewayName>": {
"type": "http",
"url": "<GatewayURL>",
"oauth": {
"clientId": "<ClientId>",
"callbackPort": 33418
}
}
}
}
Register Cursor in Okta
- Go to Applications and Resources → Applications and select Create App Integration.
- Set Sign-in method to OIDC - OpenID Connect and Application type to Single-Page Application, then select Next.
- Fill in the app settings:
- App integration name:
Cursor - Client definition: Use Okta-generated client ID
- Grant type: Authorization Code and Refresh Token
- Sign-in redirect URIs:
http://localhost:8787/callback - Controlled access: assign the users or groups who may use the gateway through this client
- App integration name:
- Select Save, then copy the Client ID from the General tab — this is the client’s
<ClientId>.
Connect Cursor
-
Add the gateway to
~/.cursor/mcp.jsonto use it in every project, or to.cursor/mcp.jsonin a project to use it there only:{ "mcpServers": { "<GatewayName>": { "url": "<GatewayURL>", "auth": { "CLIENT_ID": "<ClientId>" } } } }Replace the placeholders:
<GatewayName>: your gateway’s name.<GatewayURL>: your gateway’s MCP URL. Copy it from your gateway’s Overview tab in the Dtwo UI. It must start withhttps://.<ClientId>: the client ID you copied when you registered the client in your identity provider.
If the file already lists other servers, add this entry next to them.
-
Open Customize in the sidebar, go to MCPs, and switch your gateway on.
-
Sign in when your browser opens.
If the gateway doesn’t appear, run Developer: Reload Window from the command palette.
Register Codex in Okta
- Go to Applications and Resources → Applications and select Create App Integration.
- Set Sign-in method to OIDC - OpenID Connect and Application type to Single-Page Application, then select Next.
- Fill in the app settings:
- App integration name:
Codex - Client definition: Use Okta-generated client ID
- Grant type: Authorization Code and Refresh Token
- Sign-in redirect URIs:
http://127.0.0.1:33419/callback - Controlled access: assign the users or groups who may use the gateway through this client
- App integration name:
- Select Save, then copy the Client ID from the General tab — this is the client’s
<ClientId>.
Connect Codex
-
Add the gateway to
~/.codex/config.toml. Create the file if it doesn’t exist yet.[mcp_servers.<GatewayName>] url = "<GatewayURL>" [mcp_servers.<GatewayName>.oauth] client_id = "<ClientId>" callback_port = <CallbackPort> callback_url = "http://127.0.0.1:<CallbackPort>/callback"Replace the placeholders:
<GatewayName>: the server name. If your organization approves only the gateway, use the exact name your admin gave you. Codex blocks a server with any other name.<GatewayURL>: your gateway’s MCP URL. Copy it from your gateway’s Overview tab in the Dtwo UI. It must start withhttps://.<ClientId>: the client ID you copied when you registered the client in your identity provider.<CallbackPort>: the port in the redirect URI registered for Codex in your identity provider. If it was registered following these docs, it’s33419.callback_portandcallback_urlmust match that redirect URI exactly.
-
Sign in. In the Codex app, open Settings → MCP servers and select Authenticate next to your gateway. From a terminal, run
codex mcp login <GatewayName>instead.
Register Grok Bot in Okta
- Go to Applications and Resources → Applications and select Create App Integration.
- Set Sign-in method to OIDC - OpenID Connect and Application type to Web Application, then select Next.
- Fill in the app settings:
- App integration name:
Grok Bot - Grant type: Authorization Code and Refresh Token
- Sign-in redirect URIs:
https://www.cursor.com/agents/mcp/oauth/callback. Grok Bot signs people in from Cursor’s servers, so it uses a web redirect rather than a localhost one. - Controlled access: assign the users or groups who may use the gateway through this client
- App integration name:
- Select Save. On the General tab, copy the Client ID — this is the client’s
<ClientId>— and the Client secret under Client Credentials — this is the client’s<ClientSecret>.
Connect Grok Bot
-
In the Grok Bot app, open Connect apps from the sidebar and choose Add a custom connector at the bottom.
-
Fill in the connector:
- Name:
<GatewayName> - Type: Remote HTTPS
- Server URL:
<GatewayURL> - OAuth Client ID:
<ClientId> - Client Secret:
<ClientSecret>. This field appears after you enter the client ID.
Replace the placeholders:
<GatewayName>: the name you want to see for the gateway in Grok Bot.<GatewayURL>: your gateway’s MCP URL. Copy it from your gateway’s Overview tab in the Dtwo UI. It must start withhttps://.<ClientId>and<ClientSecret>: the client ID and secret created when Grok Bot was registered in your identity provider.
- Name:
-
Choose Add plugin, then sign in with your work account when the Bot asks.
Only users assigned to an app integration can sign in through that client. If someone gets an access error when connecting, check that they (or a group they belong to) are assigned to the app.
Connecting for the first time opens the Okta sign-in screen — sign in as the user whose permissions the agent should inherit. Once authorized, confirm the gateway’s tools appear and run a quick call to make sure the connection works.
Once it works for you, roll out your gateway to your organization. That includes turning off direct connections to MCP servers.