Authorization server responsibilities

Keeping the client registry

Client IDs and registration showed what a registration records. Running a registry adds two questions: who may create those records, and how do they stay accurate?

The photo service lets any developer register a client and try it with their own photo account. Before a client can ask other people for access, someone reviews it. Does the printing company control printer.example? Do the redirect URIs belong to that domain? Do the requested scopes match what the application does, and does the name on the consent screen match the company behind it? A later change to a redirect URI gets the same review, because it changes where codes can be sent.

A registry also needs cleaning. Clients whose developers have left, test clients nobody uses, and secrets that were never rotated accumulate quietly. Recording when each client last obtained a token makes them easy to find. A client unused for a year can be disabled, with a message to its registered contacts, and removed later if nobody objects. The same records let the service suspend a misbehaving client within minutes rather than days.

Recording approvals

The authorization server also authenticates people. Your sign-in happens on its pages, which is why the printer never sees your password, and also why those pages repay an attacker's effort. The protections described in Authentication methods and MFA apply here with particular force, because one account at the photo service may stand behind many connected applications.

Once you approve the printer, the server keeps a record of that decision: the grant that Refresh tokens and rotation showed, with its refresh token families hanging from it. Running the server means deciding what else that record drives, and it drives a good deal. When the printer asks again for the same or narrower access, the server can skip the approval screen, because the decision has already been made. When the printer asks for something new, such as albums.create, the server asks you about the new scope rather than treating the old approval as covering it. And the record is what you see on your account's connected applications page: each application, what it can access, when you approved it, when it was last used, and a way to remove it.

Removing a grant has to have an effect, and Token revocation followed how far that effect reaches: refresh tokens stop working at once, while access tokens already issued may keep working until they expire at APIs that validate them locally. A connected applications page that says so plainly is more honest than one that implies access stopped the moment you selected Remove.

Issuing codes, tokens, and keys

The rules for codes and refresh tokens were set out where each was introduced, from single-use codes to refresh tokens stored as hashes in families. Access tokens depend on their format: reference tokens need a lookup record for introspection, while self-contained JWTs need nothing stored but each carries the signature of a key the server must protect.

Running the server adds the decisions those lessons left as policy. RFC 6749 recommends that a code live no more than ten minutes, and many servers use far less. Access token lifetimes, the idle and absolute lifetimes of refresh token families, and which clients receive refresh tokens at all are settings the photo service chooses for each client and scope, and reviews when a client's needs change. The printer's ten-minute access tokens and the 400-day idle lifetime that keeps the yearly calendar connected are both choices of this kind.

The signing key is the most valuable secret the authorization server holds. Anyone with it can mint tokens that every API will accept. It belongs in a key management service or hardware module that signs without releasing the key, with access limited to the service that issues tokens. Rotation follows the overlap described in Storing and using keys. The authorization server's part is to plan it around verifiers it does not control. All key names and dates in this schedule are fictional:

The new key appears a month before it signs anything, so even an API that refreshes its cached key set rarely has plenty of time to see it. The old key stays published for a week after the switch, far longer than its ten-minute tokens need. Its private key signs nothing during that week, so the extra margin costs little.

The server also publishes what clients and APIs need to find all this: its metadata document, its key set, and its introspection and revocation endpoints. These are production services in their own right. An API that introspects every request depends on the introspection endpoint as much as on its own database, and a metadata document that lists the wrong endpoint misconfigures every client that trusts it.

Watching, limiting, and ending access

An authorization server sees every attempt to obtain access, which makes its audit log the place where investigations start. Useful events include client registrations and changes, grants created and removed, tokens issued by client and grant type, failed client authentication, codes presented twice, refresh token reuse, key rotations, and administrative actions. Each needs a time, the client, the person where there is one, the outcome, and a reason. None should contain a code, token, secret, or password, so that reading the log never hands anyone a working credential.

The same endpoints need limits. The token endpoint limits failed authentication attempts per client, so a known client ID cannot be paired with guessed secrets at speed. The device verification page limits user code guesses, as Device authorization described. Sign-in pages limit password attempts, and an open registration endpoint limits how quickly new clients can appear. A limit that is reached should raise an alert as well as reject requests, because a spike is often the first visible sign of an attack.

Finally, the server ends access when circumstances change. Refresh tokens and rotation listed the events that should end a token family or a whole grant, from a password reset to a suspended client. Operating the server means making sure those events actually reach the grant records. The account system that resets passwords, the support tools that suspend clients, and the process for handling a leaked credential each need a way to say which grants to end, and each revocation belongs in the audit log with its reason. Unless the two services have arranged a separate way to send such events, the printer learns about it at its next refresh, when it receives invalid_grant and asks you to reconnect.