Registration access tokens

A credential for one endpoint

A registration access token is an OAuth bearer token that the registration endpoint issues with a new registration. It is bound to one client ID and is meant for one place: that client's configuration endpoint. The server checks that the client named in the address is the client the token was issued for, so the token for app-7c41e2b9 cannot manage any other client.

With dynamic registration, three different credentials can surround one client, and they are easy to confuse:

Why not let a client manage its registration with the credential it already has? Not every client has one. A public client registered with none has nothing to authenticate with, yet it still needs to manage its registration. The two jobs also belong at different endpoints and are used at different times, and a separate credential for each keeps each one where it is needed.

The separation does not make the registration access token the weaker of the two. Reading the registration returns the client's current credentials, including any client secret, and an update can change the redirect URIs. Someone holding only a leaked client secret can obtain tokens as the client. Someone holding the registration access token can take over the client entirely.

Storing a registration access token

RFC 7592 says the token should not expire while the client remains registered. If it did, the client would have no way to read, update, or delete its own registration, and its only way forward would be a new registration with a new client ID. That makes it a long-lived bearer credential that is the sole proof needed at the configuration endpoint, and it deserves the same care as a refresh token:

• The phone installation keeps it in the platform's secure storage, such as the Keychain or Android Keystore-backed storage, next to its private key.
• The deployment pipeline keeps each review site's token in its secrets store and never writes it to a build log.
• A token belongs to one registration and one holder. An app that shipped a single pre-made registration, token included, to every phone would let any one installation change or delete the registration all the others depend on.

On the server side, the token must contain enough randomness that guessing it is hopeless, and the server can store only a hash of it, as it would a client secret. When a client is deleted, its registration access token must be invalidated at the same moment, so that a token for a client that no longer exists cannot even authenticate.

Rotating the token

To limit how long any one token is exposed, the server may issue a new registration access token when the client reads or updates its registration. All domains and tokens in this example are fictional. The new value arrives in the response:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "registration_access_token": "demo-registration-access-token-2",
  "registration_client_uri": "https://auth.photos.example/register/app-7c41e2b9",
  "client_id": "app-7c41e2b9",
  ...
}

The client must discard demo-registration-access-token-1 and use the new token from then on, and the server should stop accepting the old one where it can. RFC 7592 says rotation should happen only in response to a read or an update, rather than by the token quietly expiring at some other moment, because a response is the only way a client learns about a new token.

The server decides when to rotate, not the client. The protocol gives a client no way to ask for a fresh token, so a client that suspects its token has leaked has two options: whatever the service offers outside the protocol, or deleting its registration and registering again under a new client ID, after which people have to approve it again.

Rotation brings back the lost-response problem from Refresh tokens and rotation. If the response carrying the new token is lost on the way, the client still holds the old token, which the server may already have stopped accepting, and the client is locked out of its own registration. A client should store the new token durably before it does anything else with the response. A server could keep the old token valid until the client first uses the new one, avoiding the lockout at the cost of two working tokens for a short time, the same trade-off that lesson described for refresh tokens.