Reading the metadata document

The photo service's document

All addresses and values in this example are fictional. A few members are left out, including the authentication methods accepted at the revocation and introspection endpoints:

{
  "issuer": "https://auth.photos.example",
  "authorization_endpoint": "https://auth.photos.example/authorize",
  "token_endpoint": "https://auth.photos.example/token",
  "pushed_authorization_request_endpoint": "https://auth.photos.example/par",
  "device_authorization_endpoint": "https://auth.photos.example/device_authorization",
  "revocation_endpoint": "https://auth.photos.example/revoke",
  "introspection_endpoint": "https://auth.photos.example/introspect",
  "registration_endpoint": "https://auth.photos.example/register",
  "jwks_uri": "https://auth.photos.example/jwks",
  "scopes_supported": ["photos.read", "albums.create", "photos.delete"],
  "response_types_supported": ["code"],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token",
    "client_credentials",
    "urn:ietf:params:oauth:grant-type:device_code",
    "urn:ietf:params:oauth:grant-type:jwt-bearer",
    "urn:ietf:params:oauth:grant-type:token-exchange"
  ],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["client_secret_basic", "private_key_jwt", "none"],
  "token_endpoint_auth_signing_alg_values_supported": ["ES256"],
  "authorization_response_iss_parameter_supported": true,
  "dpop_signing_alg_values_supported": ["ES256"],
  "service_documentation": "https://photos.example/developers/oauth"
}

Very little of this is required. RFC 8414 requires issuer and response_types_supported, and the authorization and token endpoints whenever the server supports grants that use them. Everything else is optional or recommended, and later specifications register members of their own: the pushed authorization request endpoint, the device authorization endpoint, the iss support flag, and the DPoP algorithms all come from the extensions that introduced them. Earlier groups showed others this document can carry, such as the response modes for signed responses and the authentication context values a step-up challenge asks for. A member that would have no values is left out rather than sent as an empty list.

Where each request goes

The members ending in _endpoint are the addresses a developer used to copy by hand. The authorization endpoint receives the browser. The token endpoint exchanges codes, refresh tokens, and the other grants. The pushed authorization request endpoint accepts requests sent ahead of the browser, and the device authorization endpoint is where the living-room frame started its request in Device authorization. Revocation and introspection are the back-channel endpoints from Token revocation and Token introspection, and the registration endpoint is where software can register itself as a client.

A client uses each address exactly as given. Nothing requires the endpoints to share the issuer's host or follow a naming pattern, so a client that built /token onto the issuer would only happen to be right for this server.

jwks_uri points to the key set holding the public keys the photo service signs with. The printer does not need it to use access tokens, which it treats as opaque. The photo API uses it to verify JWT access tokens, as Token formats and validation described, and a client uses it when the server signs something addressed to the client, such as a signed authorization response. Because the address is published rather than copied, the photo service can add photos-2027-01 to the set and later start signing with it, and every verifier that reads the set finds the new key on its own.

service_documentation is for people: a page where developers can read what the document cannot express, such as how to request access to a scope that needs review.

What the server supports

The members ending in _supported describe capabilities. Each one tells a client something it would otherwise have to assume:

• scopes_supported lists the scopes the server chooses to advertise. A server may leave some out. A client uses the list to confirm that the scopes it needs exist, not as a menu of everything it could ask for.
• response_types_supported lists only code. No flow at this server places tokens in a browser redirect.
• grant_types_supported names the grants this server handles: the authorization code and refresh token grants, client credentials for services acting as themselves, the device grant used by the frame, the JWT assertion grant used by Lantern's portal in JWT and SAML assertion grants, and token exchange. When this member is missing, RFC 8414 defines a default of the authorization code and implicit grants, which is one reason servers should list their grants rather than leave clients to assume.
• code_challenge_methods_supported is how a client detects PKCE. Current security guidance requires authorization servers to offer some way to detect PKCE support and recommends this member. If it is missing, the server does not support PKCE, and a client that requires PKCE stops rather than continuing without it.
• token_endpoint_auth_methods_supported lists the client authentication methods the token endpoint accepts. Because it includes private_key_jwt, the server must also list the signing algorithms it accepts for client assertions, here ES256.
• authorization_response_iss_parameter_supported is the promise described in Identifying the authorization server: every authorization response from this server carries iss.
• dpop_signing_alg_values_supported says the server accepts DPoP proofs signed with ES256, which is what the printer's phone app uses.

Notice the two different meanings of none. In the list of authentication methods it is the value for public clients, which identify themselves without authenticating. In a list of signing algorithms it would mean an unsigned JWT, and RFC 8414 forbids it there.

Supported is not the same as allowed

The document describes the server, not any one client. grant_types_supported includes the device grant, but the printer's registration allows only the authorization code and refresh token grants, so a device authorization request from photo-printer is still refused. scopes_supported includes photos.delete, but the printer's registration limits it to photos.read, which is all a photo book needs. Metadata tells a client which options exist. The client's registration decides which of them it may use, and each request is still decided on its own.

The document is also public. Anyone can fetch it, including someone looking for an endpoint to probe. That is not a reason to hide it: everything in it is information the service's documentation would publish anyway, and the server's defenses have to hold whether or not an attacker has read the list.

What the document adds is reliability. A printer that reads it knows to send PKCE with S256 and to expect iss on every authorization response, it knows which client authentication methods the token endpoint accepts, and it learns about a new endpoint or key as soon as the photo service publishes it. All of that rests on one assumption: that the document really came from the photo service and really describes it. Validating metadata and issuer identity covers the checks that make that assumption safe.