OAuth 2.0 & JWT, quickly

Auth51 extends OAuth rather than replacing it. So it’s worth being precise about the parts it keeps unchanged: if you know these four things already, you know most of how an intent token is issued and verified.

Grants: how a client gets a token

OAuth 2.0 (RFC 6749) is, at heart, a set of grants: procedures by which a client proves it’s allowed something and receives an access token in return. The authorization-code grant is the one behind “Sign in with…”; the client-credentials grant is how a backend service authenticates as itself with no user present. Each grant ends the same way. The authorization server issues a token scoped to what was approved.

Auth51 adds one grant to this family, agent_checksum, for the case in which a client needs to prove which registered agent is asking, rather than only which application. Everything about how that grant is requested and answered follows the ordinary OAuth token-endpoint shape.

Access tokens are bearer tokens

The token a grant produces is, by default, a bearer token (RFC 6750): the spec defines it as a token that “any party in possession of” it can use. That property makes tokens trivial to pass between services. It is also a liability, because the token is the credential, so a copy is a working key. That observation is the motivation for proof-of-possession, two pages on.

JWT: what a token is made of

A JSON Web Token (RFC 7519) is the format most access tokens take: a header, a set of JSON claims, and a signature, base64url-encoded and dot-separated. Standard claims carry the issuer (iss), audience (aud), subject (sub), expiry (exp), and scope. A resource server verifies the signature and reads the claims, with no call back to the issuer required.

An intent token is an ordinary JWT. It adds claims (a key binding, an intent object, an agent_proof) that servers which understand auth51 act on, and servers that don’t simply ignore. That backward compatibility is a property of JWT rather than something auth51 invents.

JWK: how the signature is checked

To verify a JWT’s signature, a resource server needs the issuer’s public key. JSON Web Key (RFC 7517) is the format for those keys, and a JWKS endpoint is where an authority publishes them. The same standard gives us the thumbprint of a key, a compact hash of its public parameters, which is what proof-of-possession needs to name a key without carrying the whole thing.