A Thought on PDS Administration

Currently the go-to PDS server for folks to run themselves is Bluesky's PDS. It's straightforward to stand up, it is actively developed by Bluesky and the community, and it serves as the reference implementation of the ATProto HTTP API and Bluesky Lexicons.

For folks building and deploying PDSes, it would be good to improve the security practice for folks (and without loss of generality, entities) that administrate a PDS.

Administration Story

At Blacksky we have a team that facilitate user support, PDS administration, and moderation. It's not ideal for all members to have the PDS_ADMIN_PASSWORD to perform their administrative role; for example a user support team member might want to help a user change their associated email with the /xrpc/com.atproto.server.updateEmail endpoint.

1. The PDS_ADMIN_PASSWORD needed to utilize the endpoint

2. To achieve principle of least privilege, we'd need scoping granular enough to allow a user support team member to be scoped just to this endpoint. This is coming down the pipeline soon enough with the auth-resource lexicon schema.

What To Do?

The PDS_ADMIN_PASSWORD is too inflexible for teams. It's not scalable for Blacksky and it's going to be painful to use for other communities in the future.

Instead of an admin password, we should have an admin macaroon which can be attenuated for different teams and team members performing administrative functions.

What is a Macaroon?

I think fly.io is the authority on a succinct description of what a macaroon is:

Macaroon tokens are bearer tokens (like JWTs) that use a cute chained-HMAC construction that allows an end-user to take any existing token they have and scope it down, all on their own. You can minimize your token before every API operation so that you’re only ever transmitting the least amount of privilege needed for what you’re actually doing, even if the token you were issued was an admin token.
- Thomas Ptacek

Instead of a PDS_ADMIN_PASSWORD, we would have a PDS_ADMIN_ROOT_MACAROON. If you manage your own PDS by yourself, PDS_ADMIN_ROOT_MACAROON could operate like PDS_ADMIN_PASSWORD today.

If you're on a team that manages a PDS, then attenuating the macaroon for each team member's role is exactly what can be achieved!

How do I envision OAuth and Macaroons in ATProto?

For now, let's assume that the PDS has a way to derive or set a root macaroon and it is stored securely. The high-level concept is as follows:

1. You have a list of administrator DIDs or groups,

2. A new endpoint, e.g. com.atproto.admin.requestCapability, allows an authorized admin (with OAuth ATProto scope) to request and receive a macaroon; administrators can either attenuate locally to delegate to a team member/service or the PDS has a "self-lease portal" where an admin requests a limited scope token for themselves.

3. The administrator can make a request to the endpoint with their OAuth JWT and macaroon. The OAuth token verifies who you are; the macaroon proves what you're allowed to do.

4. The other two endpoints would be com.atproto.admin.revokeCapability and com.atproto.admin.rotateRootCapability, which complete the lifecycle management of macaroons. Revocation provides surgical control: 'this admin does not need this capability anymore.' Rotation handles broader scenarios ranging from PDS ownership transfer to security best practices around invalidating the root macaroon and re-issuing attenuated ones for active team members and services.

The macaroon coupled with OAuth for administrative operations help achieve the principle of least privilege all the while having flexibility to have a combination of qualities for administration such as:

restricting admin operations to particular endpoint(s),

a PDS team member and/or,

the expiry time of the macaroon

As communities begin to operate their PDSes, the ATProto community can bake in a good set of tailorable security measures for their teams.

Calling all ATProto Admins and ATProto Curious

Blacksky has a one-click PDS hosting service that is coming out in 2026. We are looking for alpha testers. If you'd like to participate, email us at hello@blacksky.app