# Configure Microsoft Entra ID

Use Microsoft Entra ID as the identity provider for your Dtwo gateway, with OAuth for Claude Code, Claude Cowork, Cursor, and MCP Inspector.

## Overview

Microsoft Entra ID can act as the identity provider for your Dtwo gateway allowing users to sign in with their existing Entra accounts. You register the gateway as an application in your own Entra tenant. Each AI client that connects to the gateway is registered as its own Entra application with the redirect URI that client uses.

This guide uses Entra's **v1.0** token endpoints.

## Verify your gateway's custom domain

Only required for gateways hosted by Dtwo. Skip this step if you run the gateway yourself on a domain you already control in Entra.

Because Dtwo owns the `dtwo.ai` DNS zone, verifying a hosted gateway domain is a two-party handshake:

1. In the <a href="https://entra.microsoft.com" target="_blank" rel="noopener noreferrer">Microsoft Entra admin center</a>, go to **Domain names → Add custom domain**, enter your gateway's domain (for example `<customer>.hosted.us1.prod.dtwo.ai`), and select **Add domain**. Entra responds with a TXT record value in the form `MS=ms########`.
2. Email that `MS=ms########` value to [support@dtwo.ai](mailto:support@dtwo.ai). Dtwo adds the TXT record to DNS and replies once it is live.
3. Return to the **Add custom domain** screen for that domain and select **Verify**.

> Verify the domain before continuing. Adding the gateway's URL to the app registration's `identifierUris` in the next step fails if the domain is not yet verified in Entra.

## Register the gateway application in Entra

1. In the Entra admin center, go to **App registrations → New registration**. Give it a name (for example `Dtwo Gateway`), set **Supported account types** to **Single Tenant Only — Default Directory**, and select **Register**.
2. From the app's **Overview** page, copy the **Directory (tenant) ID** (`<DirectoryId>`) and the **Application (client) ID** (`<ApplicationId>`).
3. Go to **Expose an API**. Next to **Application ID URI**, select **Add** and accept the default (`api://<ApplicationId>`).
4. Under **Scopes defined by this API**, select **Add a scope** and create the scope your clients will request:
   - **Scope name**: `mcp`
   - **Who can consent**: Admins and users
   - **Display name** and **Description**: `Access MCP`
   - Select **Add scope**.
5. Open **Manifest** to edit the raw JSON. Find `identifierUris` — it should currently read `[ "api://<ApplicationId>" ]` — and add your gateway's URL to the list:

   ```json
   "identifierUris": [
     "api://<ApplicationId>",
     "<GatewayURL>"
   ],
   ```

   Replace `<GatewayURL>` with your gateway's MCP URL, found in the Overview tab for your gateway in the Dtwo UI.

6. Select **Save** at the top of the Manifest screen.

## Configure your Dtwo gateway

Go to your gateway in the Dtwo UI and open **Configuration → Advanced**. In the `gateway` section add the following entry:

```yaml
authentication:
  enabled: true
  jwks_info:
    jwt_algorithm: "RS256"
    jwt_jwks_uri: "https://login.microsoftonline.com/common/discovery/keys"
    jwt_issuer: "https://sts.windows.net/<DirectoryId>/"
    jwt_audience: "<GatewayURL>"
  sso_issuer: "https://sts.windows.net/<DirectoryId>/"
  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:

- `<DirectoryId>` — the **Directory (tenant) ID** of the app registration 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 added to `identifierUris` in step 2.

## Register your AI clients in Entra

Each AI client needs its own app registration, because each one has a different redirect URI. The shape is the same every time:

1. Go to **App registrations → New registration**, name it after the client, set **Supported account types** to **Single Tenant Only — Default Directory**, and select **Register**.
2. From **Overview**, copy the **Application (client) ID** — this is that client's `<ClientId>`.
3. Under **Authentication → Add a platform**, add the redirect URI(s) for that client from the table below.
4. Under **API permissions → Add a permission**, open the **APIs my organization uses** tab, search for `<ApplicationId>`, select your gateway application, check the `mcp` scope, and select **Add permissions**. (Skip this if you are running the gateway locally.)

| Client                  | Platform                        | Redirect URI(s)                                                                   |
| ----------------------- | ------------------------------- | --------------------------------------------------------------------------------- |
| Claude Code             | Mobile and desktop applications | `http://localhost:33418/callback`                                                 |
| Claude Cowork / Desktop | Web                             | `https://claude.ai/api/mcp/auth_callback`                                         |
| Cursor                  | Mobile and desktop applications | `cursor://anysphere.cursor-mcp/oauth/callback`                                    |
| MCP Inspector           | Single-page application (SPA)   | `http://localhost:6274/callback` and `http://localhost:6274/oauth/callback/debug` |

Claude Cowork also needs a client secret: go to **Certificates & secrets → New client secret**, add a description, select **Add**, and copy the **Value** before leaving the screen — copy the Value, not the Secret ID, and note that it isn't shown again. This is that client's `<ClientSecret>`.

## Connect your AI client

Configure each client with your gateway's URL and the `<ClientId>` from its app registration in step 4.

### Claude Code

Add the gateway to `~/.claude.json`:

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

### Claude Cowork

In Claude Desktop, go to **Customize → Connectors → Add Connector → Add custom connector**:

- **Name**: for example `Dtwo Gateway`
- **URL**: `<GatewayURL>`
- **Advanced Settings → OAuth Client ID**: `<ClientId>`
- **Advanced Settings → OAuth Client Secret**: `<ClientSecret>`

Select **Add**, then **Connect**.

To make the gateway available to everyone in your organization instead, add it under **Organizational Settings → Connectors** as a Custom Web Connector with the same name, URL, client ID, and client secret. Then return to **Customize → Connectors**, select the newly added gateway, and select **Connect**.

### Cursor

Use the following configuration in Cursor. The key must be `CLIENT_ID`, not `client_id`:

```json
{
  "mcpServers": {
    "gateway": {
      "url": "<GatewayURL>",
      "transport": "http-stream",
      "auth": {
        "CLIENT_ID": "<ClientId>"
      }
    }
  }
}
```

A `CLIENT_SECRET` is optional. To use one, create a client secret on Cursor's app registration under **Certificates & secrets → New client secret** and add its **Value** to the `auth` block.

### MCP Inspector

MCP Inspector is a useful tool for debugging gateway connectivity and authentication issues:

- Set **Connection Type** to **Direct**.
- Set **Client ID** to `<ClientId>`.

Connecting for the first time opens the Microsoft sign-in screen — sign in as the user whose permissions the agent should inherit, and approve the consent prompt. Once authorized, confirm the gateway's tools appear and run a quick call to make sure the connection works.

---

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