Discovering server capabilities
Following the complete exchange said that the printer knows the photo service's authorization and token endpoints from trusted configuration. Until now, that configuration has been a developer reading the photo service's documentation and copying values into the printer's settings: two endpoint addresses, the scopes the service defines, the client authentication methods its token endpoint accepts, and whether it supports PKCE.
Copying works until something changes. The photo service adds an endpoint for pushed authorization requests, starts returning the iss response parameter, or publishes a new signing key. Every client has to notice and update its settings by hand, and every copied address is another chance to paste the wrong one.
What a client needs to know
Before it can start a single flow, a client needs answers to a list of questions about the authorization server. For the photo service, the answers look like this. All domains and values in these examples are fictional.
| Question | The photo service's answer |
|---|---|
| Where does the browser go to authorize? | https://auth.photos.example/authorize |
| Where are codes and refresh tokens exchanged? | https://auth.photos.example/token |
| How may a client authenticate there? | client_secret_basic, private_key_jwt, or no authentication for public clients |
| Which PKCE methods are supported? | S256 |
| Which scopes exist? | photos.read, albums.create, photos.delete |
| Where are the server's public keys? | https://auth.photos.example/jwks |
| Which optional protections does it offer? | The iss response parameter, pushed authorization requests, DPoP |
Some answers are addresses and some are capabilities. A few, such as support for the iss parameter, change what the client must check on every response. A client that guesses wrong either fails outright or, worse, quietly skips a protection the server was ready to provide.
Authorization server metadata, published as RFC 8414, lets the authorization server answer these questions itself, in a JSON document that clients fetch and read. Current security guidance recommends that authorization servers publish it and that clients use it to configure themselves when it is available. Libraries can then turn on newer protections automatically, endpoint addresses are read rather than retyped, and the server can rotate its keys without asking anyone to change a setting.
Starting from the issuer
The document is found from a single value: the authorization server's issuer identifier. It is an HTTPS URL, with no query or fragment, that names the authorization server. For the photo service it is https://auth.photos.example. You have met it already, as the iss value the printer compares on each authorization response in Identifying the authorization server, and as the iss claim in the photo service's JWT access tokens.
The metadata lives at a well-known address derived from the issuer. Well-known addresses are paths under /.well-known/ that standards reserve and register, so that a site can publish a document where software expects to find it. For authorization server metadata, the default name is oauth-authorization-server:
GET /.well-known/oauth-authorization-server HTTP/1.1
Host: auth.photos.exampleThe server answers with a JSON object. Its first member repeats the issuer, and the rest describe the server:
HTTP/1.1 200 OK
Content-Type: application/json
{
"issuer": "https://auth.photos.example",
"authorization_endpoint": "https://auth.photos.example/authorize",
"token_endpoint": "https://auth.photos.example/token",
"jwks_uri": "https://auth.photos.example/jwks",
"code_challenge_methods_supported": ["S256"],
...
}The document is shortened here. Even in this form, it answers several of the questions above without anyone copying a value.
Metadata does not remove the need for trusted configuration, though. It shrinks it. The printer still has to know that https://auth.photos.example is the authorization server for your photo account, and it has to get that value from a source it trusts. Everything else can follow from that one value.
Issuers with a path
One host can run more than one authorization server. A hosting provider might give each customer organization its own issuer on a shared domain, and the photo service could run a separate authorization server for business accounts with the issuer https://auth.photos.example/business.
Well-known paths are defined at the root of a host, so when an issuer has a path, the well-known name goes at the root and the issuer's path follows it. Any trailing slash on the issuer is removed first:
Issuer:
https://auth.photos.example/business
Metadata document:
https://auth.photos.example/.well-known/oauth-authorization-server/businessIt is tempting to append the name to the end of the issuer instead, giving https://auth.photos.example/business/.well-known/oauth-authorization-server. A client that does this looks in the wrong place. With the insertion rule, each issuer on the host still has its own document, and the host's well-known documents all stay under one path.
OpenID Connect discovery
RFC 8414 generalized an older document. OpenID Connect Discovery defines a provider configuration document at /.well-known/openid-configuration, written in the same format and with mostly the same field names. An authorization server that is also an OpenID Connect provider can publish both.
The two differ in where the name goes when the issuer has a path. OpenID Connect Discovery appends it to the issuer, path included:
Issuer:
https://auth.photos.example/business
OAuth authorization server metadata (inserted):
https://auth.photos.example/.well-known/oauth-authorization-server/business
OpenID Connect discovery (appended):
https://auth.photos.example/business/.well-known/openid-configurationFor an issuer without a path, such as https://auth.photos.example, the two documents sit side by side and differ only in their final name. For an issuer with a path, they live in different places, and a client that builds one kind of address while looking for the other kind of document will not find it. A server with a path in its issuer that wants to serve both kinds of client publishes at both addresses.
The documents are close relatives rather than copies. OpenID Connect adds fields of its own, such as the address of its UserInfo endpoint and the algorithms it uses to sign ID tokens, and it requires some fields that RFC 8414 leaves optional, including the key set address. Reading the metadata document goes through the photo service's OAuth document member by member, and Reading provider metadata returns to the fields OpenID Connect adds for sign-in.