RFC 8414

Definition

Imagine you are building an app that needs to integrate with OAuth, but you are working with multiple identity providers - Google, Microsoft, your company’s internal auth server. Each one has slightly different URLs for authorization, token exchange, and key retrieval. Traditionally, you would hardcode all these URLs, update them whenever a provider changes something, and hope nothing breaks. RFC 8414 solves this headache with automatic discovery.

This specification defines a standard way for OAuth authorization servers to publish their configuration at a well-known URL. Instead of hardcoding https://auth.google.com/oauth/authorize and hoping it does not change, your app can fetch https://auth.google.com/.well-known/oauth-authorization-server and get a complete list of all endpoints, supported features, and capabilities. The server tells you where everything is.

The discovery document contains everything a client needs: the authorization endpoint, token endpoint, JWKS (JSON Web Key Set) location for verifying tokens, supported grant types, available scopes, and much more. This makes your integration more robust (endpoints update automatically), more portable (same code works with any compliant server), and more maintainable (no hardcoded URLs scattered through your codebase).

Example

Building a “Login with” feature: When you implement social login, instead of researching and hardcoding each provider’s endpoints, you fetch their discovery document. Google, Microsoft, Apple - they all publish their OAuth configuration at a predictable URL.

Enterprise SSO integration: Companies often switch identity providers or update their configurations. With discovery, your app automatically picks up changes. When IT updates the auth server, your app just works without redeployment.

Multi-tenant SaaS applications: If your app supports multiple organizations with their own identity providers, discovery is essential. You just need each customer’s base URL - the discovery document tells you everything else.

Mobile app authentication: Mobile apps especially benefit from discovery because app updates are slow to deploy. If an auth provider changes an endpoint, apps using discovery adapt immediately.

Analogy

The Building Directory: When you enter a large office building, you check the directory in the lobby to find which floor houses the company you are visiting. You do not memorize floor numbers for every business - you consult the directory. RFC 8414 is that directory for OAuth endpoints.

The Restaurant Menu: You do not call a restaurant in advance to ask “do you serve vegetarian dishes?” or “what payment methods do you accept?” You look at the menu when you arrive. The discovery document is the OAuth server’s menu - listing all available options and endpoints.

The Airport Information Desk: At an unfamiliar airport, you find the information desk to learn where everything is: gates, lounges, customs, restrooms. Discovery is the information desk for OAuth - one query tells you the location of every service.

The Hotel Room Card: When you check in, your key card comes with a paper sleeve showing hotel amenities and their locations: pool on floor 3, gym on floor 2, restaurant on floor 1. The discovery document is that information sleeve for an auth server.

Code Example

// Discovery endpoint
GET /.well-known/oauth-authorization-server [HTTP/1.1](https://reference.apios.info/terms/http-1-1/)
Host: auth.example.com

// Response
{
  "issuer": "https://auth.example.com",
  "authorization_endpoint": "https://auth.example.com/authorize",
  "token_endpoint": "https://auth.example.com/token",
  "jwks_uri": "https://auth.example.com/.well-known/jwks.json",
  "response_types_supported": ["code", "token"],
  "grant_types_supported": [
    "authorization_code",
    "client_credentials",
    "refresh_token"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post"
  ],
  "scopes_supported": ["openid", "profile", "email"]
}

// Using discovery in code
const metadata = await fetch(
  'https://auth.example.com/.well-known/oauth-authorization-server'
).then(r => r.json());

const authUrl = metadata.authorization_endpoint;

Security Notes