Service auth token iteration - method binding & nonces

[dholms]

Background

Service auth tokens in atproto are used for inter-service authentication. When a request is proxied through the PDS to another service - for instance a feed generator, labeler, or appview - the PDS signs a short-lived JWT using the user's atproto signing key and sends it along as an authorization header. This allows the receiving service to verify that the request is being sent on behalf of the requesting user. You can read more about the specifics of this implementation here.

Service auth tokens are short-lived (generally 60s expiration) and intended to be single-use. They currently specify the audience that they're intended for and an expiration but no other details. This means that they can be useful for authentication but not authorization. We've been running into issues lately where we do want to scope down the ability of a given token. A leaked service auth token can be quite disruptive as it essentially gives full access to some service on behalf of the user for the token's lifespan. As well, since some network services (the Bluesky chat service for instance) contain sensitive data, we've had to lockdown the API for requesting service auth tokens (com.atproto.server.getServiceJwt) such that app passwords are not able to request them.

New claims

To improve the security model around service auth tokens, we’re adding two new claims to the spec: lxm and jti.

More details can be found in PR: #2663

lxm

The lxm claim is short for "lexicon method" and specifies a lexicon-defined method that the token is "bound" to. For instance, you may bind a token to app.bsky.feed.getFeedSkeleton which means that that token can only be used for calling getFeedSkeleton.

The name is inspired by the htm/htu claims from the DPoP spec for binding a token to a given http method/url. A simple way to think of this is as a very limited "scope" for the token.

If the lxm claim is omitted from a service auth token, then the token may still be used for simple authentication, but it should not be used for any sensitive resources or to perform any actions on behalf of the user. As more services implement lxm checks, unbound tokens may be deprecated entirely.

jti

The jti claim is an arbitrary string on the JWT payload that can be used to prevent replay attacks.

The Bluesky PDS implementation will add a random 128 bit hex-encoded nonce to every signed service auth token. Receiving services are not required to make use of this nonce, but they may wish to if the resource being requested is sensitive or susceptible to replay attacks.

Creating/validating bound methods

We published a new version (v0.6.0) or @atproto/xrpc-server with updated methods for creating and validating these tokens. Specifically, createServiceJwt and verifyJwt both take a new required (nullable) param lxm.

A bound service auth token can also be requested through the API through com.atproto.sever.getServiceJwt using the new param lxm. Since tokens are now bound to specific methods, app passwords will be able to use this method again. However, they will not have access to some “privileged” methods, such as chat.bsky methods (those used to access & send DMs).

Backwards Compatibility

JWTs with these two claims should be backwards compatible with existing services that do not check for a bound method. The JWT spec says that implementations should ignore claims that they are unfamiliar with, and most implementations adhere to this behavior.

Feed generators will start receiving auth tokens with app.bsky.feed.getFeedSkeleton set as the bound method. We encourage feed generators to start validating this claim, but in the meantime existing authentication should continue to function.

For PDS administrators, we published a new version of the PDS package and distribution (v0.4.46) which should auto-update if you have that enabled. If not, this will require a manual update. We will start verifying bound methods on our services (most notably the Appview and Chat services) starting next week (Aug 12).

Looking forward

Service auth tokens were introduced as a very simple method for inter-service authentication when we introduced the first non-PDS service in the network (the Appview). These two claims are an important iteration on the security model, but are by no means the end state of authentication/authorization in atproto .

We're looking forward to the release of OAuth in the near future. As we flesh out the authorization story with OAuth and introduce richer authorization semantics, we'll be looking toward a richer inter-service authorization system as well, likely one that allows services to delegate authorization on behalf of users.

[snarfed]

I noticed that api.bsky.chat recently started requiring lxm in service JWTs it receives. OK! Agreed, seems like a useful service-level equivalent of OAuth scopes.

It's singular though, right? So I need to generate a new one for each method I call? Eg for chat, if I regularly call getConvoForMembers and then sendMessage, I need to generate separate tokens for each of those calls?

[devinivy]

Yeah, that's right, it's similar in spirit to htm and htu claims from DPoP or to HTTP signatures— it essentially binds the token to a particular request. Pulling the jti claim into the mix solidifies that idea by further preventing replays.

Maybe of note— as long as service auth and service proxying has existed, the PDS has been creating new tokens for each call made to the appview on behalf its users 👍

[snarfed]

Thanks! Makes sense, will do.