Visual RFC.
ALL RFCs / RFC 8414
Read the RFC ↗

RFC 8414 / START HERE

OAuth server metadata, before the details

OAuth 2.0 is an authorization framework. Authorization Server Metadata is a JSON configuration document describing one authorization server’s endpoints and capabilities.

An app starts with an issuer identifier, such as a configured HTTPS server address. It derives a well-known metadata location, retrieves the document and checks that the returned issuer exactly matches the one it expected.

Start the guide See the 6 chapters ↓

The idea in one picture

  1. OAuth client

  2. Configuration document

  3. Authorization server

A simplified picture of the idea; the chapters explain the actual mechanisms.

Why it exists

Apps need the correct places for browser authorization, token requests and signing keys, plus information about supported methods. A shared format reduces custom configuration, while exact issuer checking helps prevent server impersonation.

A familiar example

Think of a service directory issued by an office. You check which office the directory describes before using its desk locations. A neat directory is not permission to use every service, and a signed directory still needs an acceptable signer.

Helpful background

You can start here without reading another RFC. If these ideas are unfamiliar, these short introductions may help.

OAuth 2.0RFC 6749 · beginner overview ↗OAuth device authorizationRFC 8628 · beginner overview ↗JWTRFC 7519 · beginner overview ↗

What you’ll learn next

Begin with chapter one, or choose a topic.

  1. Construct the metadata request locationStart with an issuer identifier and insert the application’s well-known path before the issuer’s own path.
  2. Read a metadata response as configurationA successful response is a JSON object. Its fields describe roles and capabilities; they are not a token response or an access grant.
  3. Apply defaults without inventing capabilitiesSome omitted lists have specified defaults; others deliberately have no default. An advertised feature is still separate from client policy.
  4. Compare issuer and strings exactlyUse the original expected issuer and the returned value after JSON decoding. Do not silently normalize two different identifiers into a match.
  5. Read signed metadata with the right trust boundaryOptional signed metadata carries a bundle of claims. The party attesting to them and the authorization server being described are distinct concepts.
  6. Preserve TLS, key and resource boundariesCorrectly shaped metadata can still be unsafe if the connection, issuer, keys or resource association are wrong.
Start with chapter one →

This introduction explains RFC 8414 (2018). Read the original RFC ↗