Configure Microsoft Entra ID

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 Microsoft Entra admin center, 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. 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:

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

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

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:

{
  "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:

{
  "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.