# Configure Okta

Use Okta as the identity provider for your Dtwo gateway, with OAuth for Claude Code, Claude Desktop, Codex, and Cursor.

## 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

1. 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**.
2. Set the issuer to **Okta URL** and copy the **Issuer URI**. It looks like `https://<OktaDomain>/oauth2/<ServerId>`. This is your `<Issuer>`.
3. Open the authorization server's **Access Policies** tab and select **Add Policy**:
   - **Name**: `Default Policy`
   - **Description**: `Default Policy`
   - Select **Create Policy**.
4. 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**.

## 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:

```yaml
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.

<div class="doc-tabs" data-tabs>

<div class="doc-tablist doc-tablist-cards" role="tablist" aria-label="AI client">
<button type="button" role="tab" class="doc-tab" data-tab="claude-desktop" aria-selected="true"><img src="/logos/claude.svg" alt="" width="36" height="36" data-no-lightbox>Claude Desktop</button>
<button type="button" role="tab" class="doc-tab" data-tab="claude-code"><img src="/logos/claude.svg" alt="" width="36" height="36" data-no-lightbox>Claude Code</button>
<button type="button" role="tab" class="doc-tab" data-tab="cursor"><img src="/logos/cursor.svg" alt="" width="36" height="36" data-no-lightbox>Cursor</button>
<button type="button" role="tab" class="doc-tab" data-tab="codex"><img src="/logos/codex.svg" alt="" width="36" height="36" data-no-lightbox>Codex</button>
<button type="button" role="tab" class="doc-tab" data-tab="grok-bot"><img src="/logos/grok-bot.svg" alt="" width="36" height="36" data-no-lightbox>Grok Bot</button>
</div>

<div class="doc-tabpanel" data-panel="claude-desktop" role="tabpanel">

**Register Claude Desktop in Okta**

1. Go to **Applications and Resources → Applications** and select **Create App Integration**.
2. Set **Sign-in method** to **OIDC - OpenID Connect** and **Application type** to **Single-Page Application**, then select **Next**.
3. 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
4. Select **Save**, then copy the **Client ID** from the **General** tab — this is the client's `<ClientId>`.

**Connect Claude Desktop**

1. 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.
2. 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://`.
3. Choose **Use your own OAuth client** and enter the `<ClientId>` you copied when you registered the client in your identity provider.
4. Click **Add**.
5. Click **Connect** and sign in when your browser opens. On Team and Enterprise, you'll find **Connect** under **Customize → Connectors**, not in Organization settings.
6. 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.

</div>

<div class="doc-tabpanel" data-panel="claude-code" role="tabpanel">

**Register Claude Code in Okta**

1. Go to **Applications and Resources → Applications** and select **Create App Integration**.
2. Set **Sign-in method** to **OIDC - OpenID Connect** and **Application type** to **Single-Page Application**, then select **Next**.
3. 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
4. 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:

```bash
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 with `https://`.
- `<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 `--scope` out.
- `--scope project`: the project you ran the command in, for everyone who works on it. Claude Code saves the gateway to a `.mcp.json` file 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:

```json
{
  "mcpServers": {
    "<GatewayName>": {
      "type": "http",
      "url": "<GatewayURL>",
      "oauth": {
        "clientId": "<ClientId>",
        "callbackPort": 33418
      }
    }
  }
}
```

</div>

<div class="doc-tabpanel" data-panel="cursor" role="tabpanel">

**Register Cursor in Okta**

1. Go to **Applications and Resources → Applications** and select **Create App Integration**.
2. Set **Sign-in method** to **OIDC - OpenID Connect** and **Application type** to **Single-Page Application**, then select **Next**.
3. 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
4. Select **Save**, then copy the **Client ID** from the **General** tab — this is the client's `<ClientId>`.

**Connect Cursor**

1. Add the gateway to `~/.cursor/mcp.json` to use it in every project, or to `.cursor/mcp.json` in a project to use it there only:

   ```json
   {
     "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 with `https://`.
   - `<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.

2. Open **Customize** in the sidebar, go to **MCPs**, and switch your gateway on.
3. Sign in when your browser opens.

If the gateway doesn't appear, run **Developer: Reload Window** from the command palette.

</div>

<div class="doc-tabpanel" data-panel="codex" role="tabpanel">

**Register Codex in Okta**

1. Go to **Applications and Resources → Applications** and select **Create App Integration**.
2. Set **Sign-in method** to **OIDC - OpenID Connect** and **Application type** to **Single-Page Application**, then select **Next**.
3. 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
4. Select **Save**, then copy the **Client ID** from the **General** tab — this is the client's `<ClientId>`.

**Connect Codex**

1. Add the gateway to `~/.codex/config.toml`. Create the file if it doesn't exist yet.

   ```toml
   [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 with `https://`.
   - `<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's `33419`. `callback_port` and `callback_url` must match that redirect URI exactly.

2. 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.

</div>

<div class="doc-tabpanel" data-panel="grok-bot" role="tabpanel">

**Register Grok Bot in Okta**

1. Go to **Applications and Resources → Applications** and select **Create App Integration**.
2. Set **Sign-in method** to **OIDC - OpenID Connect** and **Application type** to **Web Application**, then select **Next**.
3. 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
4. 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**

1. In the Grok Bot app, open **Connect apps** from the sidebar and choose **Add a custom connector** at the bottom.
2. 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 with `https://`.
   - `<ClientId>` and `<ClientSecret>`: the client ID and secret created when Grok Bot was registered in your identity provider.

3. Choose **Add plugin**, then sign in with your work account when the Bot asks.

</div>

</div>

> 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](/docs/connect-clients) to your organization. That includes turning off direct connections to MCP servers.

---

Having trouble? Email [support@dtwo.ai](mailto:support@dtwo.ai).