Identifying the authorization server

A response that names its sender

OAuth 2.0 Authorization Server Issuer Identification, published as RFC 9207 in 2022, adds one parameter to the authorization response. A server that supports it must include iss in every authorization response it sends, successes and errors alike.

All domains and codes in these examples are fictional. The Redirects and authorization codes lesson showed the parameter in the printer's first callback, and Errors and denied access showed it on a denial:

Success:
https://printer.example/oauth/callback
  ?code=demo-code-7
  &state=demo-attempt-7
  &iss=https%3A%2F%2Fauth.photos.example

Error:
https://printer.example/oauth/callback
  ?error=access_denied
  &state=demo-attempt-7
  &iss=https%3A%2F%2Fauth.photos.example

The value is form-encoded because it sits inside a URL. Decoded, it reads https://auth.photos.example. Errors carry it for the same reason successes do: an error is a message from a server, and the printer should know which server sent it before acting on it.

A response from Pixel Vault, if Pixel Vault supported the parameter, would carry iss=https%3A%2F%2Fauth.pixelvault.example instead. Two responses that were indistinguishable now name their senders.

The issuer identifier

The value of iss is not chosen for this parameter. It is the authorization server's issuer identifier, the name the server uses for itself throughout OAuth. An issuer identifier is a URL that uses HTTPS and has no query or fragment. It can include a path, which lets one host run several authorization servers, for example https://login.example/east and https://login.example/west, each with its own identifier, endpoints, and keys.

You have seen this value before. It is the iss claim in the JWT access tokens the photo service issues, the aud the printer puts in its signed client assertions and request objects, and the iss claim in a JARM response. It is also the issuer value in the server's metadata document, and the specification requires the iss response parameter to be identical to that value.

An issuer identifier names a whole configuration, not just a host. Behind https://auth.photos.example stand a particular authorization endpoint, token endpoint, and key set. That is what makes the parameter useful: once the printer knows which issuer answered, it knows which token endpoint the code belongs at, and whether that is the one it intended to use.

Advertising support

A server that supports the parameter says so in its metadata, a document published at a well-known address derived from its issuer identifier. The photo service's document includes:

GET /.well-known/oauth-authorization-server HTTP/1.1
Host: auth.photos.example

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",
  "authorization_response_iss_parameter_supported": true
}

The document is shortened to the fields that matter here. authorization_response_iss_parameter_supported set to true promises that every authorization response will carry iss. When the field is omitted, its value is false. Pixel Vault's metadata omits it, because Pixel Vault has not adopted the parameter.

The flag matters because of what it lets a client conclude from silence. A response without iss from Pixel Vault is normal. The same response claiming to come from the photo service is not, because the photo service has promised to include it. Without the flag, a client could not tell a server that never sends iss from a response whose iss is missing for a suspicious reason.

Adding the parameter does not break older clients. The original OAuth 2.0 specification requires clients to ignore response parameters they do not recognize, so a client that has never heard of iss carries on as before. Servers that publish no metadata at all can still support the parameter, with the issuer identifier agreed with each client developer and configured in the client directly.

Supporting the parameter is the server's half of the arrangement. The client's half is knowing which issuer it expected and comparing the value correctly, and most mistakes happen there. The Authorization server metadata group, later in Advanced OAuth, explains how clients fetch and validate documents like this one.