Start for Free

How RFC 8414 OAuth 2.0 Authorization Server Metadata Works

Clifford Spielman Technical Writer

How RFC 8414 OAuth 2.0 Authorization Server Metadata Works

Also known as Authorization Server Metadata or OAuth Discovery, RFC 8414 standardizes how an OAuth 2.0 client learns about an authorization server's configuration. The server publishes a JSON metadata document at a well-known HTTPS location. That document includes the server’s issuer identifier, which is the URL that identifies the authorization server, and can advertise endpoints, supported grant types, response types, authentication methods, signing keys, and other capabilities.

The practical benefit is that a client does not need every server detail beforehand. Once it knows the authorization server's issuer identifier, it can retrieve a standardized configuration that describes how to interact with the server.

Why OAuth RFC 8414 Is Needed

OAuth 2.0 defines how clients interact with authorization and token endpoints, but the core framework does not provide a general-purpose metadata document that tells a client where those endpoints are or what other capabilities an authorization server supports. That leaves deployments to provide those details through documentation, manual configuration, or other means.

OpenID Connect (OIDC) already addresses a closely related problem through OIDC Discovery. But that mechanism is defined for OpenID Providers, leaving OAuth authorization servers that do not use OIDC without a standard way to publish the same kind of metadata.

RFC 8414 generalizes that approach so it can be used by OAuth authorization servers even when OIDC is not part of the deployment. It gives authorization servers a standard way to publish their configuration and gives clients a standard way to consume it.

How RFC 8414 Works: Step-by-Step

The exchange between the OAuth client and authorization server is intentionally small, with the steps being to construct the metadata URL, send an HTTP GET request, read the JSON document, validate the issuer, and use the advertised configuration.

  1. Construct the metadata URL: For a general-purpose OAuth authorization server, the default well-known suffix is: 
/.well-known/oauth-authorization-server

With an issuer of https://example.com: 

https://example.com/.well-known/oauth-authorization-server

Issuer identifiers can also contain a path. In that case, RFC 8414 inserts the well-known component between the host and the issuer path. For an issuer of https://example.com/tenant1, the metadata URL becomes: 

https://example.com/.well-known/oauth-authorization-server/tenant1

That detail matters in multi-tenant systems and also distinguishes RFC 8414 from the original OIDC Discovery URL construction rules.

Duende IdentityServer exposes the RFC 8414 metadata endpoint at /.well-known/oauth-authorization-server relative to the IdentityServer base address. It can also expose the OIDC Discovery document at /.well-known/openid-configuration. 

https://example.com/.well-known/oauth-authorization-server/tenant1

That detail matters in multi-tenant systems and also distinguishes RFC 8414 from the original OIDC Discovery URL construction rules.

2. Request the metadata: The client retrieves the metadata document with HTTP GET. For the issuer above, the request is: 

http
GET /.well-known/oauth-authorization-server HTTP/1.1
Host: example.com

A successful response uses HTTP 200 and returns a JSON object with the application/json content type.

3. Read the metadata:

A metadata response can advertise endpoint locations, signing-key information, supported protocol features, and other server capabilities. A representative response looks like this:

Json 

json
{
  "issuer": "https://example.com",
  "authorization_endpoint": "https://example.com/authorize",
  "token_endpoint": "https://example.com/token",
  "jwks_uri": "https://example.com/jwks.json",
  "scopes_supported": ["read", "write"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "client_credentials"],
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "private_key_jwt"
  ],
  "token_endpoint_auth_signing_alg_values_supported": [
    "RS256",
    "ES256"
  ],
  "code_challenge_methods_supported": ["S256"]
}

RFC 8414 defines more metadata members than this example shows, and additional specifications can register their own. The fields in the table below are among the ones a developer is most likely to encounter.

Metadata Field Status / If Omitted What it Tells the Client

issuer

Required

The authorization server's issuer identifier.

authorization_endpoint

Required when applicable

Where authorization requests are sent when the server supports grants that use this endpoint.

token_endpoint

Required when applicable

Where token requests are sent when the server supports grants that use this endpoint.

token_endpoint

Required when applicable

Where token requests are sent when the server supports grants that use this endpoint.

jwks_uri

Optional

Where the server publishes a JSON Web Key Set used for signature validation and, potentially, encryption.

scopes_supported

Recommended

Scope values the server chooses to advertise.

response_types_supported

Required

OAuth response types supported by the server.

grant_types_supported

Optional; default: authorization_code, implicit

Grant types the server advertises.

token_endpoint_auth_methods_supported

Optional; default: client_secret_basic

Client authentication methods accepted at the token endpoint.

token_endpoint_auth_signing_alg_values_supported

Optional; required if private_key_jwt or client_secret_jwt is advertised

JWS signing algorithms the token endpoint supports for JWT-based client authentication methods such as private_key_jwt and client_secret_jwt.

code_challenge_methods_supported

Optional; if omitted, PKCE is not supported

PKCE code challenge methods supported by the server.

This metadata document is more than endpoint discovery. A client can inspect response types, grant types, authentication methods, and PKCE support before it attempts a flow. The document does not negotiate new behavior; it tells the client which capabilities the server advertises so the client can choose among features it already understands.

Finally, RFC 8414 does not tell a client which authorization server to use. The client starts with an issuer identifier obtained through configuration or another mechanism. RFC 8414 describes how to use that issuer identifier to locate and retrieve the server’s metadata.

4. Validate the issuer before using the document: The metadata is useful only if the client can trust that it describes the authorization server it intends to contact. RFC 8414 therefore requires the returned issuer value to match the issuer identifier used to construct the metadata URL. If the values do not match, the client needs to reject the metadata.

After validation, the client can use the document to locate endpoints, retrieve signing keys, and determine which advertised protocol features it can use. The flow is straightforward: 

sequenceDiagram
    participant C as OAuth Client
    participant AS as Authorization Server

    C->>AS: GET /.well-known/oauth-authorization-server
    AS-->>C: 200 OK + metadata JSON

RFC 8414 vs. OIDC Discovery and Related Specs

RFC 8414 sits next to several specifications that also help clients understand who they are communicating with and how to interact with those resources. They solve related, but different, discovery and identification problems.

The following table describes these related specifications:

Specification Primary Subject Main Purpose

RFC 8414

OAuth authorization server

Publishes authorization-server endpoints and capabilities as metadata.

OIDC Discovery

OpenID Provider

Allows an OIDC Relying Party to discover an OpenID Provider and retrieve its OIDC/OAuth configuration.

RFC 9728

OAuth protected resource metadata

Publishes protected-resource metadata, including authorization servers that can be used with the resource. It also defines a protected_resources member that an authorization server can publish in its RFC 8414 metadata to identify supported protected resources.

RFC 9207

Authorization response

Adds an iss parameter so the client can identify which authorization server produced an authorization response.

OIDC Discovery is the closest comparison to RFC 8414. Both specifications define well-known metadata endpoints, but they handle path-based issuers differently. OIDC Discovery appends /.well-known/openid-configuration after the issuer path, while RFC 8414 places its well-known component before the path.

RFC 9728 works from the other side of the relationship between an authorization server and the protected resources that rely on it: it describes the protected resource rather than the authorization server. Its authorization_servers metadata member can list issuer identifiers for authorization servers that can be used with that resource.

RFC 9207 addresses a different problem. It is not a discovery document; it identifies the authorization server in an authorization response and uses the issuer identifier defined by RFC 8414.

Security Considerations: HTTPS and Issuer Validation

Because RFC 8414 publishes server capabilities at a predictable location, attackers can read the same metadata as legitimate clients. Authorization servers and clients therefore cannot rely on endpoint or capability details being hidden; they need the same protections they would use if that information were exposed another way.

Not only can potential attackers read the same metadata as legitimate clients, they can also provide malicious metadata documents to clients, potentially directing clients to attacker-controlled endpoints or keys.

RFC 8414 therefore requires clients to retrieve metadata over HTTPS. TLS helps ensure that the client is communicating with the intended server and that the metadata is not intercepted or altered in transit, reducing the risk of man-in-the-middle and related attacks. The RFC specifically requires authorization servers to support TLS 1.2 while also noting that appropriate TLS versions change as deployments and known vulnerabilities evolve.

Verifying the issuer provides a second check in order to prevent accepting malicious metadata. It confirms that the metadata actually describes the authorization server the client intends to query.

A separate security consideration is the relationship between authorization servers and protected resources. RFC 8414 does not establish which protected resources are associated with a particular authorization server.

To help address that gap, RFC 9728 adds metadata that describes the relationship in both directions: a protected resource can advertise suitable authorization servers, and an authorization server can use the protected_resources member to list such resources it can be used with. Despite this, RFC 9728 does not define a universal way to determine which authorization server to use with a given protected resource.

FAQs

Does RFC 8414 replace OpenID Connect Discovery?

No. OIDC Discovery is still the discovery specification for OpenID Providers. Rather, RFC 8414 generalizes the OIDC Discovery metadata model and applies it to systems that use OAuth, whether or not they also use OIDC. The two specifications are intentionally compatible and often expose much of the same metadata. This allows OAuth implementations to use a standard discovery mechanism without requiring OIDC.

In fact, Duende IdentityServer's OAuth and OIDC metadata documents contain identical content.

Does RFC 8414 Discover Which Authorization Server a Client Should Use?

No. The client needs an issuer identifier before it can construct the RFC 8414 metadata URL. How the client obtains or selects that issuer is outside the metadata-retrieval mechanism defined by RFC 8414.

Are All RFC 8414 Metadata Fields Required?

No. Requirements vary by field and by the capabilities the server supports. issuer and response_types_supported are required, while some endpoint fields are conditionally required and many capability fields are optional or recommended.

Can an Authorization Server Publish Both OAuth and OpenID Connect Metadata?

Yes. RFC 8414 allows an authorization server to publish metadata at multiple well-known locations. In practice, a server that supports both OAuth and OIDC can expose the OAuth authorization-server metadata document and the OIDC Discovery document. Duende IdentityServer supports both endpoints.

Further Reading

For the full RFC as well as related specifications and resources, please see the following: