Skip to main content

OAuth clients

The oauthClients block is the allowlist of approved OAuth clients that identify themselves with a Client ID Metadata Document, which includes common MCP clients such as Claude. Only the clients you list can get access tokens for people.

A client that uses a Client ID Metadata Document has a URL as its client ID: the address of a document that describes the client. Most MCP clients work this way, because the MCP authorization specification recommends it. Anyone can create a client ID this way, just by publishing a document, so you list the clients you trust. If every client were allowed, any application could get access tokens that act as your users. For example, a person who opens a link from an unknown application, and is already signed in through single sign-on, could authorize that application without noticing.

Example​

oauthClients:
  - clientID: https://claude.ai/oauth/mcp-oauth-client-metadata
  - clientID: https://agent.example.com/oauth/client.json

Fields​

FieldRequiredDescriptionExample
clientIDYesThe client's Client ID Metadata Document URL, exactly as the client publishes it. Find it in the client's documentation.https://claude.ai/oauth/mcp-oauth-client-metadata

Client IDs are compared exactly, character by character, with no wildcards. For example, https://agent.example.com/oauth/client.json and https://agent.example.com/oauth/client are different clients. To allow several clients from the same publisher, list each one.

oauthClients and the token policy​

oauthClients and the token policy are separate checks, and both apply:

  • oauthClients decides which clients are allowed to request a token.
  • The token policy decides whether a token is issued, and what it contains. Rules can match a client by its client ID with caller.oauthClientID.

Validation​

Client IDs are compared exactly, so Defakto rejects entries that no client could match. When you apply the configuration, Defakto rejects a clientID that:

  • Isn't an https URL with a lowercase scheme and host
  • Includes the default port, :443, or ends its host with a bare :
  • Has no path, or ends in /
  • Contains *, a query string, user information, or a fragment, including a bare ? or #
  • Has an empty path segment (//), or a . or .. segment
  • Contains a \, or an encoded ., /, \, or % (%2e, %2f, %5c, or %25)
  • Has leading or trailing whitespace
  • Is longer than 512 characters

Defakto also rejects:

  • The same clientID listed twice
  • More than 100 entries
  • No oauthClients entries when an identity provider has login