Scopes, resources, and audiences
An exchange request says two things about the token it wants: where it will be used, and what it should allow there. Those two answers decide whether the new token is narrower than the one it came from, or quietly broader.
Scopes and audiences explained why a token names its audience and why an API refuses tokens addressed to someone else. Token exchange is where a client deliberately asks for a token with a different audience, so the way it names that target, and the access it asks for there, deserve care.
Naming the target
Selecting the intended resource introduced the resource parameter: an absolute URI for the protected resource, with no fragment. Token exchange accepts it with the same meaning. The photo API used resource=https://storage.photos.example, the address it was about to call.
Token exchange adds a second way to name a target. audience carries a logical name for the target service rather than its location. The name has to be one that the client and the authorization server both understand, such as a client ID, a SAML entity identifier, or an OpenID Connect issuer identifier. All identifiers in these examples are fictional. The storage service is registered with the photo service as client photo-storage, because it makes exchanges of its own, so the photo API could ask with audience=photo-storage instead. Audience values must be unique within one authorization server, so that a name cannot be read as the wrong kind of thing.
| Aspect | resource | audience |
|---|---|---|
| What it names | The location where the token will be used. | A logical name for the target service. |
| Form | An absolute URI with no fragment. | Any value both sides understand. |
| Example | https://storage.photos.example | photo-storage |
| Suits | A client that knows the address it will call. | A target known by an identifier, such as another domain's issuer. |
A request can repeat either parameter or use both, and that is rarely wise. The photo service also runs an archive service, at https://archive.photos.example, which keeps the originals of photos you have not opened for a long time. Suppose the photo API, unsure which service holds a file, named both the storage service and the archive in one exchange and asked for storage.read archive.read. Token exchange reads that request the way Requesting access to multiple resources described for ordinary token requests: every scope at every target, in a single token that both services would accept. The specification lets a server refuse a request that names too many targets. An exchange costs one round trip, so the photo API asks for one target at a time, when the call to that target is about to happen.
Whatever the request names, the authorization server decides the new token's aud claim. When the request uses resource, the JWT access token profile says aud should carry the same value, which is why the storage token's audience is exactly https://storage.photos.example. The storage service then makes the audience check that Audience restrictions and validation described, and an exchanged token gets no exception from it.
Narrowing what the token allows
The scope in an exchange request is written in the target's terms. The printer's token carries photos.read, which the photo API understands. The storage service has its own scopes, storage.read for reading stored files and storage.delete for removing them, and the archive has archive.read. The authorization server's exchange policy connects them. For the photo service it reads:
| Client | Subject token carries | May receive | At |
|---|---|---|---|
photo-api | photos.read | storage.read | https://storage.photos.example |
photo-api | photos.delete | storage.delete | https://storage.photos.example |
photo-storage | storage.read | archive.read | https://archive.photos.example |
Every row narrows. The new token concerns the same person, works at one service, allows only the matching action, and lives for a short time. No row turns read access into delete access. If the photo API, holding the printer's read-only token, asked for storage.delete, the server would refuse with invalid_scope: an exchange cannot add what you never allowed the printer. Asked for storage.read storage.delete, a server might instead issue storage.read alone and list it in the response's scope. Either way, it never issues storage.delete.
A client should also ask for less than the policy allows when a call needs less. Suppose the photo editor's token carried both photos.read and photos.delete. When the editor only displays thumbnails, the photo API asks for storage.read alone to fetch them. A token taken from that call cannot delete anything.
A request may also leave scope out. The server then chooses according to its policy, and the response must include scope whenever the issued scope is not identical to the one requested. A client that needs particular access should ask for it, and check what came back.
When the target is refused
Audience restrictions and validation introduced invalid_target, and token exchange uses it for the same purpose: the server is unwilling or unable to issue a token for a target named in resource or audience. Beyond an unknown or malformed value, an exchange adds two reasons of its own: a request that names too many targets at once, and a target this client may not reach through exchange.
The sharing API at https://share.photos.example, from the Scopes and audiences lesson, is a service the photo service knows well. If the photo API asked to exchange the printer's token for a sharing token, it would still receive invalid_target, because no row in the policy lets the photo API act for you there. A target that exists is not a target this client may reach.
invalid_target concerns where, and invalid_scope concerns what. A scope with no meaning at the named target, such as photos.read at the storage service, falls between the two. Resource indicators allows invalid_target for an invalid combination of resource and scope, and a server may answer invalid_scope instead. Neither changes if the same request is sent again. Errors and failure cases looks at how a client should respond to these and the other ways an exchange can fail.