Authorization Server Metadata

Authorization Server Metadata

Authorization Server Metadata (RFC 8414) provides a well-known endpoint that clients can use to discover OAuth server capabilities and endpoints. This enables automatic configuration of OAuth clients without manual endpoint configuration.

Process

---
title: Authorization Server Metadata Discovery
---
sequenceDiagram
autonumber

actor Client
participant Authorization Service

Client-->>Authorization Service: Requests metadata document
Note right of Client: GET /.well-known/oauth-authorization-server
Authorization Service-->Authorization Service: Builds metadata from configuration
Authorization Service-->>Client: Returns JSON metadata document
Client-->Client: Configures OAuth endpoints from metadata

Loading

Client

The Client entity represents a client application that needs to discover the OAuth server's endpoints and capabilities.

Authorization Service

The Authorization Service entity returns the metadata document describing its endpoints and supported features. This is provided by TokenAuthority.

Endpoints

GET /.well-known/oauth-authorization-server

The client calls this well-known endpoint to retrieve the authorization server metadata. This endpoint is always available at the root of the host, not under the engine mount path.

HTTP Method: GET

URL: /.well-known/oauth-authorization-server

Example Request:

GET /.well-known/oauth-authorization-server

Example Response:

{
    "issuer": "https://example.com",
    "authorization_endpoint": "https://example.com/oauth/authorize",
    "token_endpoint": "https://example.com/oauth/token",
    "revocation_endpoint": "https://example.com/oauth/revoke",
    "registration_endpoint": "https://example.com/oauth/register",
    "response_types_supported": ["code"],
    "grant_types_supported": ["authorization_code", "refresh_token"],
    "token_endpoint_auth_methods_supported": ["none", "client_secret_basic", "client_secret_post", "private_key_jwt"],
    "code_challenge_methods_supported": ["S256"],
    "scopes_supported": ["read", "write"],
    "service_documentation": "https://example.com/docs/oauth"
}

Response Fields:

Field	Description
issuer	The authorization server's issuer identifier (URL).
authorization_endpoint	URL of the authorization endpoint.
token_endpoint	URL of the token endpoint.
revocation_endpoint	URL of the token revocation endpoint.
registration_endpoint	URL of the dynamic client registration endpoint (if enabled).
response_types_supported	Array of supported response types. TokenAuthority supports ["code"].
grant_types_supported	Array of supported grant types. TokenAuthority supports ["authorization_code", "refresh_token"].
token_endpoint_auth_methods_supported	Array of supported client authentication methods.
code_challenge_methods_supported	Array of supported PKCE code challenge methods. TokenAuthority supports ["S256"].
scopes_supported	Array of supported scopes (if configured).
service_documentation	URL to human-readable documentation (if configured).

MCP Integration

The Model Context Protocol (MCP) specification requires OAuth servers to provide authorization server metadata for automatic client configuration. MCP clients use this endpoint to discover:

1. The authorization endpoint for initiating OAuth flows
2. The token endpoint for exchanging codes and refreshing tokens
3. Supported authentication methods and PKCE requirements
4. The registration endpoint for dynamic client registration

Configuration

The metadata response is automatically generated from TokenAuthority configuration:

TokenAuthority.configure do |config|
  # Required: Sets the issuer claim
  config.token_issuer_url = "https://example.com"

  # Define scopes - keys become scopes_supported in metadata
  config.scopes = {
    "read" => "Read your data",
    "write" => "Create and modify your data",
    "admin" => "Administrative access"
  }

  # Optional: Link to documentation
  config.authorization_server_documentation = "https://example.com/docs/oauth"

  # Controls which auth methods are advertised
  config.dcr_allowed_token_endpoint_auth_methods = %w[none client_secret_basic]
end

The scopes_supported field in the metadata response is automatically derived from the keys in config.scopes. If scopes are not configured, the scopes_supported field is omitted from the metadata.

References

• RFC 8414: OAuth 2.0 Authorization Server Metadata
• MCP Authorization Specification