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

```json
{
  "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](/glossary/mcp-server-card): 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](/glossary/oauth-protected-resource) (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.

[← All glossary terms](/en/glossary)