Skip to main content

Microsoft Entra ID

Use this guide when people sign in through Microsoft Entra ID, as in Host an MCP server. Defakto authenticates to Entra ID with a federated credential, so no client secret is stored anywhere.

Before you begin​

You need:

  • Permission to create app registrations in your Entra ID tenant, such as the Application Developer role
  • Your tenant's Directory (tenant) ID, from the Microsoft Entra admin center
  • Your trust domain's OAuth Issuer. Find it in the Defakto console, under your trust domain's Settings > Trust domain URLs, or in the output of defakto trust-domain info <trust-domain>.

Step 1: Register Defakto in Entra ID​

  1. In the Microsoft Entra admin center, browse to Entra ID > App registrations, and select New registration.
  2. Enter a Name, such as Defakto.
  3. For Supported account types, select Single tenant only.
  4. Select Register, and record the Application (client) ID from the Overview page.
  5. Select Authentication, then Add Redirect URI, then the Web platform. Enter your publicBaseURL followed by /oauth/upstream-callback, for example https://td-server.defakto.example.com/oauth/upstream-callback, and select Configure.

Step 2: Add a federated credential​

A federated credential lets Defakto authenticate to the app registration without a client secret. Entra ID trusts JWTs that your trust domain's OAuth server signs, and checks them with its published keys. Microsoft calls this workload identity federation, and describes the steps in Create a trust relationship with an external identity provider.

  1. In the app registration from step 1, select Certificates & secrets, then the Federated credentials tab, then Add credential.

  2. For Federated credential scenario, select Other issuer.

  3. Enter these values, exactly as shown:

    FieldValue
    IssuerYour trust domain's OAuth Issuer
    Subject identifierurn:defakto:oauth-client:<application-client-id>, with the Application (client) ID from step 1
    NameA name for the credential, such as defakto
    Audienceapi://AzureADTokenExchange

  4. Select Add.

Step 3: Add Entra ID to the configuration​

Add Entra ID to oauth-server.yaml, along with the MCP clients that people use:

oauth-server.yaml
section: OAuthServer
schema: v1
spec:
  endpoints:
    publicBaseURL: https://td-server.defakto.example.com

  identityProviders:
    - name: corp-entra
      issuer: https://login.microsoftonline.com/<tenant-id>/v2.0
      login:
        clientID: <application-client-id>
        clientAuth:
          method: private_key_jwt
          audience: api://AzureADTokenExchange
        scopes: [openid]

  oauthClients:
    - clientID: https://claude.ai/oauth/mcp-oauth-client-metadata
  • issuer is your tenant's issuer, with the Directory (tenant) ID.
  • login.clientID is the Application (client) ID from step 1.
  • login.clientAuth authenticates with the federated credential from step 2. audience must match the credential's Audience.
  • oauthClients is the allowlist of MCP clients, such as Claude, that can request access tokens for your MCP servers. See OAuth clients.

Apply the configuration to your trust domain. You can apply Managed Configuration through the Defakto API, Terraform, or the Defakto CLI. See applying configuration. For example, with the CLI:

defakto config set trust-domain --id <trust-domain-id> oauth-server.yaml