OAuth Discovery

What is OAuth Discovery?

OAuth Discovery is a mechanism for automatically discovering an OAuth 2.0 Authorization Server via a JSON document at /.well-known/oauth-authorization-server (RFC 8414) or /.well-known/openid-configuration (OIDC). It contains all the endpoints an agent needs to initiate an OAuth flow without any manual configuration.

{
  "issuer": "https://example.com",
  "authorization_endpoint": "https://example.com/oauth/authorize",
  "token_endpoint": "https://example.com/oauth/token",
  "jwks_uri": "https://example.com/.well-known/jwks.json",
  "scopes_supported": ["read", "write"],
  "response_types_supported": ["code"]
}

Why do you need OAuth Discovery?

AI agents that need authorized API access must locate the OAuth Authorization Server. Without discovery, the agent requires explicit user configuration — which blocks autonomous operation.

With OAuth Discovery, an agent:

1. Receives the service domain
2. Requests /.well-known/oauth-authorization-server (or /.well-known/openid-configuration)
3. Reads authorization_endpoint and token_endpoint
4. Initiates the OAuth flow without human involvement

This is especially important for MCP servers: the MCP specification requires OAuth Discovery for authorized servers.

How do you implement OAuth Discovery?

Most OAuth providers publish discovery automatically:

Provider	URL
Auth0	https://<tenant>.auth0.com/.well-known/openid-configuration
Keycloak	https://<host>/realms/<realm>/.well-known/openid-configuration
Okta	https://<tenant>.okta.com/.well-known/oauth-authorization-server

If you are running your own OAuth server, publish the JSON at /.well-known/oauth-authorization-server. Required fields per RFC 8414:

• issuer — base URL of your server
• authorization_endpoint — URL for authorization
• token_endpoint — URL for obtaining a token
• jwks_uri — URL with public keys

For protected resources, also publish OAuth Protected Resource Metadata (RFC 9728), which points back to the Authorization Server.

How do we check OAuth Discovery?

The scanner checks two paths in order of priority:

1. /.well-known/openid-configuration
2. /.well-known/oauth-authorization-server

For each path:

1. HTTP 200 — document is accessible
2. Valid JSON — body parses without errors
3. Required fields — issuer, authorization_endpoint, token_endpoint, jwks_uri are present

pass — at least one path returned HTTP 200 with valid JSON and all four fields. fail — neither path responds or required fields are missing.