Proposal: OAuth Scopes

[dholms]

Note: a more complete proposal was published in July 2025: https://github.com/bluesky-social/proposals/tree/main/0011-auth-scopes

We’re continuing work on rolling OAuth out to the atproto network. Just recently, the Bluesky PDS distribution gained the ability for any network application to create an account on it (#3621). This week, we’re also updating the Bluesky’s PDS deployment (bsky.social) to allow for the same. This will allow any app in the network to allow users to create accounts “from that app” (through an OAuth flow) rather than directing the user to create an account through the Bluesky application.

A core missing piece of the OAuth stack is the ability for applications to request more tightly scoped authorization from the user’s PDS. Currently the scope level is roughly analogous to what a user receives from using an “app password”. Ideally a client will be able to request access to only the record types and methods that it needs for its application experience.

This document isn’t quite at the “RFC stage” yet (though we of course encourage comments on it!). We’re hoping to get to a more complete proposal within the next few weeks. In the meantime, this document is primarily meant to circulate the current ideas that we’ve been chewing on. We especially wanted to get it out ahead of AtmosphereConf as we know this topic is top of mind for many in the developer community. We encourage feedback, questions, and thoughts!

PDS Resources

OAuth scopes relate to resources that a PDS owns.

These are, roughly, and at a high level, the resources that the PDS owns and for which we want to allow access to network applications.

• Identity
• Account
• Repo
• Service auth
• Blobs

To demonstrate, the needs for a client similar to the Bluesky app:

• Access to view/edit account details (email, etc.)
• Create/manage blobs
• Request for custom rate limits & quotas
• CRUD public repo records of particular collections:
  • app.bsky.feed.post (create, delete)
  • app.bsky.feed.like (create, delete)
• Use service proxying to authenticate users on the bluesky appview
  • Audience: did:web:bsky.app#bsky_appview
  • Methods: <any>
• Use service proxying to authenticate users on the bluesky chat service
  • Audience: did:web:api.bsky.chat#bsky_chat
  • Methods: <any>
• Use service proxying to authenticate users on feeds
  • Audience: <any>
  • Methods: app.bsky.feed.getFeedSkeleton (& friends)

Encoding these resources as conventional OAuth strings may look something like the following:

# Please note that these scopes are only meant for illustrative purproses
# and are NOT part of the proposal

# account details
- account:email

# create/manage blobs
- blobs:create
- blobs:update
- blobs:maxSize:10000000

# CRUD public repo records
- repo:app.bsky.feed.post:*
- repo:app.bsky.feed.like:create
- repo:app.bsky.feed.like:delete

# service proxying for appview
- serviceAuth:*@did:web:bsky.app

# service proxying for chat
- serviceAuth:*@did:web:api.bsky.chat

# service proxying for feeds
- serviceAuth:app.bsky.feed.getFeedSkeleton@*

Evolvable resource semantics

The problem with the strings listed above is that they’re a little magical. They would probably need to be defined in the OAuth spec or in the Lexicon language (if we start referencing them in Lexicons which we’ll get to later). In a multi-party, low-coordination network like atproto, we also need a way to evolve them over time. Fortunately we have a system for making application semantics both legible and evolvable: Lexicon!

The idea is that we can push these descriptions of resources into the schema layer. A schema that represents the repository resource could look like the example below. Note that this syntax is not nailed down and is only meant to give intuition.

{
  "lexicon": 1,
  "id": "com.atproto.permissions.repo",
  "defs": {
    "main": {
      "type": "auth-resource",
      "description": "Grants access to records in the public repo",
      "parameters": {
        "type": "params",
        "required": ["collection"],
        "properties": {
          "collection": {
            "type": "string",
            "description": "The collection being granted access to"
          },
          "create": {
            "type": "boolean",
            "default": false
          },
          "udpate": {
            "type": "boolean",
            "default": false
          },
          "delete": {
            "type": "boolean",
            "default": false
          }
        }
      }
    }
  }
}

Right now, we would only expect auth-resource schemas to be defined in the com.atproto namespace. These are not meant to enable dynamic runtime coordination. Rather they would be high-context and require the implementation of the PDS to change so that it could understand the semantics in the schema. The auth-resource schema is only meant as a coordination mechanism for evolving these semantics over time or introducing new resources to the PDS.

These auth-resources could then be encoded as OAuth scope strings as such:

com.atproto.permissions.blob?create=true&maxSize=1000000 // uploading blobs up to 1MB
com.atproto.permissions.repo?collection=app.bsky.feed.post&create=true // create bluesky posts

Coordinating scope bundles

For an app like the Bluesky app to function, it would need to request a lot of these scopes. This presents a UX issue (long lists of scopes are pretty ugly), but also a security UX issue. Users that are routinely presented with long lists of scopes will become less discerning as to which scopes they approve and it becomes easier to sneak unwanted scopes in.

Therefore, we want the authorization server to be able to bundle scopes and give them human-readable descriptions.

We’re faced with a unique problem in the atproto network because the PDS (the authorization & resource server) is generic, but needs to provide human-readable descriptions of scopes for application-specific records and methods - resources that it doesn’t necessarily understand!

Atproto is a multi-party network: clients, PDSs, and application developers all need to coordinate in an n-to-n-to-n manner.

The developer of a given application (in the sense of a “network application”, or a set of Lexicons describing an atproto app) is in an ideal position to both bundle and describe these scopes.

Just as we coordinate record semantics using Lexicon, we can also coordinate authorization semantics using Lexicon.

The idea is to introduce a new lexicon schema type auth-bundle (name pending) that defines these bundles of scopes. Again note that this is not a final version of the schema and is only meant to give intuition.

{
  "lexicon": 1,
  "id": "app.bsky.auth.base",
  "defs": {
    "main": {
      "type": "auth-bundle",
      // This description is shown to the user
      // Note: will also need to add a mechanism for internationalization
      "description": "Creation of bluesky posts & likes and authenticate the user towards Bluesky AppViews.",
      "permissions": [
        {
          "ref": "com.atproto.permissions.repo",
          "params": {
            "collection": "app.bsky.feed.post",
            "create": true,
            "update": true,
            "delete": true
          }
        },
        {
          "ref": "com.atproto.permissions.repo",
          "params": {
            "collection": "app.bsky.feed.like",
            "crate": true,
            "update": true,
            "delete": true
          }
        },
        {
          "ref": "com.atproto.permissions.repo",
          "params": {
	          "collection": "app.bsky.feed.like",
	          "create": true,
	          "delete": true
	        }
        },
        {
          "ref": "com.atproto.permissions.serviceAuth",
          "params": {
	          // Need some mechanism for parameterizing this with an `aud`. More on this below
	          "aud": "...",
	          // Perhaps add in a wildcard mechanism for *any* method
            "lxm": [
              "app.bsky.actor.getPreferences",
              "app.bsky.actor.putPreferences",
              "app.bsky.actor.getProfile",
              "app.bsky.actor.putProfiles",

              "app.bsky.feed.getActorLikes",
              "app.bsky.feed.getAuthorFeed",
              "app.bsky.feed.getFeed"

              // ...
            ]
          }
        },
        {
          "ref": "com.atproto.permissions.serviceAuth",
          "params": { "lxm": "app.bsky.feed.getFeedSkeleton" }
        }
      ]
    }
  }
}

Restricting application authority

Because the goal of the auth-bundle is to hide a large set of permissions under a single human-readable name, we cannot give applications the unmediated ability to bundle any resource into their authorization scopes. Therefore, we need to restrict which resources are able to be included in an auth-bundle document.

Roughly this is “only resources (records & methods) related to the NSID of the auth-bundle document”.

The first mechanism that we’re looking at is basing this on the syntax of the auth-bundle NSID. Generally, we try to refrain from relying on hierarchy in the NSID structure (see the lexicon resolution spec for more details). However in this case, the semantic would be “An auth-bundle schema can contain resources for any sibling or children NSIDs” with the possible added semantic that .auth is reserved as a special keyword that is essentially ignored when doing this syntactic check.

So for instance:

app.example.baseAuth can reference app.example.record and app.example.method

app.bsky.auth.base can reference [app.bsky.feed.post](http://app.bsky.feed.post/) and app.bsky.graph.muteActor

The other mechanism that we’re looking into is basing this on the Lexicon documents authority, that is the repository that the document is contained in. So app.bsky.auth.base would be able to reference app.bsky.feed.post by nature of it being in the same repository. This is nice because it avoids special keywords and hierarchical semantics, but is somewhat unsatisfying because it mixes hosting of lexicons in with the auth scope semantics.

Service Authentication

Service auth is a weird one because it can be parameterized by the client with the audience that the auth is for. Unlike all of the other permissions that can be described by the Lexicon developer, the audience for service auth is a client choice.

Especially with sensitive services (like a DMs service for instance), it is important that a user is aware which service they are giving authentication access to the client to.

One option is to parameterize the auth-bundle document so that clients can request a scope like app.bsky.auth.base?appviewAud=did:web:bsky.app . In this case appviewAud would be a parameter that is defined in the app.bsky.auth.base document.

Another option is to rely on a particular syntax that parameterizes all audiences for any service auth in a given document. This could look something like app.bsky.auth.base@did:web:bsky.app. The downside of this syntax is that any scopes with different audiences (for instance any audience for app.bsky.feed.getFeedSkeleton) would need to be requested as a different scope.

The final option is to not allow service auth to be specified in the auth-bundle schema, meaning that clients must also request the decomposed auth-resource strings (in which they will supply the audience as a parameter) when requesting service auth.

In any of these options, the audience would be shown to the user as the hostname that the requested DID resolves to.

Clients using both auth-bundles & auth-resources

Clients can use both auth-bundles and auth-resources to obtain the authorization that they need to operate. This way, if an application designer does a bad job bundling scopes, a client can request exactly the authorization they need. Clients can also request scopes from across application spaces.

For instance, a client may request the following scopes:

// uploading blobs
com.atproto.permissions.blob?create=true&maxSize=1000000 
// basic bluesky auth (with bluesky appview)
app.bsky.auth.base@did:web:api.bsky.app#bsky_appview 
// auth to all feed generators
com.atproto.permissions.serviceAuth?aud=*&lxm=app.bsky.auth.feeds 
// basic bluesky DMS auth (with bluesky chat service)
chat.bsky.auth.base@did:web:api.bsky.chat#bsky_chat 
 // create statussphere statuses
com.atproto.permissions.repo?collection=xyz.statusphere.status&create=true

Reliance on Lexicon Resolution

This entire proposal relies on Lexicon resolution and also significantly increases the security concerns of that resolution. You can read more about the lexicon resolution spec Here.

If Lexicon resolution fails, the client will receive an error. Should this occur, the client could fallback to requesting all the individual permissions. This would provide a less ideal UX but it provides a decent degradation.

It will be important that PDSs (fairly) rapidly refresh lexicon documents. This will allow updates in authorization semantics to evolve over time to support new features, and also allow application designers to rapidly patch up any possible security holes in their auth-bundle documents. We expect a TTL of 5 minutes or so will suffice for refreshing auth scope schemas.

Caching of Lexicon can also be enabled by a Lexicon aggregator when performing lexicon resolution. This introduction of a party that a PDS trusts to perform lexicon resolution may help with both availability concerns and some security concerns (for instance throttling dramatic changes to a bundle of auth scopes).

We also intend to have some way to “bind” access tokens to a specific version of the scope requested. We haven’t quite nailed down the mechanism for this. A likely candidate is just be an integrity check against the CID of the scope document.

Why no wildcards?

One major design decision that we ended up making was to not allow hierarchical wildcards in scopes. For instance app.bsky.feed.*. Because this was such a big discussion point for us, it seemed like it warranted an explanation

The upsides of wildcards are:

• they allow dynamism into the scope which requires both fewer publishes of auth-bundle documents for new features and fewer refreshes of access tokens for those new scopes
• they are a more succinct syntax for listing a bunch of records/methods in the same namespace

However introducing wildcards also comes with some usability & security issues.

First, wildcards seem most useful if they have exclusions (for instance, app.bsky.feed.*, but not app.bsky.feed.generator). At least in Bluesky’s case this would be necessary. This may be a data-modeling error on our part (we probably shouldn’t have put feed generator records in the same namespace as likes 😅), but also if we made that mistake, it is likely that other application developers will as well. Exclusions are inherently unsafe as it is much more likely to forget to exclude a sensitive feature (because “it works on my computer”) than to add a missing feature to a scope. Even if we disallow exclusions, this speaks to a general problem of overloading schema names with authorization semantics which seems prone to footguns.

Wildcards also introduce a notion of hierarchy between NSID hostnames (for instance, app.bsky.*) which does not exist in the lexicon resolution protocol. While we could restrict wildcards to the top-level, this becomes a somewhat confusing semantic.

Finally, wildcards don’t buy us any new capability that we do not have from being able to just refresh auth scope documents. It seems better for the ecosystem to just make sure that scope refreshes work better than to try to get around that through dynamism in the syntax of the scopes.

All that being said, wildcards may still pop up specifically in the context of service auth audiences. For instance, being able to call app.bsky.feed.getFeedSkeleton on any service.

[Bossett]

Agree that you don't really want a wildcard because you may end up with highly fragmented namespaces for security and not semantic purposes.

re: wildcards and bundling - has there been consideration of versioning the auth-bundles and therefore allowing an app to request new permissions by identifying that the version has moved up? I'm concerned about the case where a developer needs to handle both 'which individual permissions are missing' and 'which bundles have been granted', which may lead to over/under-privileged tokens (which can be an issue if they're long-lived) especially where you are interacting with someone else's app via an API.

My other comment is around some kind of generic structure - I think there's a need for non-data attributes. Actions such as 'initiate account recovery', or 'delete my account' are an example of a permission that you may want to grant but doesn't really have a data equivalent. Having a spec for these transactional scopes would avoid some not-great workarounds in the future (i.e. 'you have perms on this collection, therefore you can take this action...').

[dholms]

There was a quick note on versioning in the proposal, but it's pretty vague/handwavey because we haven't quite figured out the mechanism for it:

We also intend to have some way to “bind” access tokens to a specific version of the scope requested. We haven’t quite nailed down the mechanism for this. A likely candidate is just be an integrity check against the CID of the scope document.

I do think it'd be useful for a client to prod an Authorization server with a version so that it refreshes its cache, but a client probably shouldn't be able to request arbitrary versions on scopes because they may be outdated for security reasons

[dholms]

Totally right on non-data attributes!

There would be an auth-resource for account level actions. Maybe something like:

{
  "lexicon": 1,
  "id": "com.atproto.permissions.account",
  "defs": {
    "main": {
      "type": "auth-resource",
      "description": "Grants access to the user's account details",
      "parameters": {
        "type": "params",
        "properties": {
          "viewEmail": {
            "type": "boolean",
            "default": false,
            "description": "Grants access to view the user's email address"
          },
          "updateEmail": {
            "type": "boolean",
            "default": false,
            "description": "Grants access to update the user's email address"
          },
          "resetPassword": {
            "type": "boolean",
            "default": false,
            "description": "Grants access to reset the user's password"
          }
        }
      }
    }
  }
}

These would not be able to be bundled into auth-bundles and the more sensitive scopes would be highlighted more aggressively on the authorization page

[iameli]

This is cool.

So Streamplace needs like...

• Full access to place.stream.* record create/update/delete, naturally
• Create access to app.bsky.feed.post records for "I'm Live" notifications
• Create & delete access to app.bsky.graph.block records for blocking and unblocking users directly from chat
• Create & delete access to app.bsky.graph.follow records for following and unfollowing users encountered through the platform

Maybe a few more. Perhaps app.bsky.auth provides a "posts and follows and blocks and stuff (but not sensitive account management)" auth-bundle. That bundle will probably include more scopes than we strictly need, but would be useful to use anyway for the sake of presenting a conceptually clean authorization to the user. Potentially an acceptable tradeoff, just worth noting that we've suddenly granted Streamplace more power than it actually needs for the sake of UX simplicity. (I guess I could imagine a mechanism where you're allowed to request a subset of the permissions of an auth-bundle while still operating under the same description but that seems weird and complicated.)

[Bossett]

I was just thinking of the UI here when you posted this - would this be something like:

This app is requesting:

• <auth bundle name> (maybe list the 'common' tree'd NSIDs so 'access to limited items in place.stream')
• create/delete to app.bsky.feed.post ('author provides reason')
• create/delete to app.bsky.graph.block ('author provides reason')
• create/delete to app.bsky.graph.follow ('author provides reason')

That way you're mixing an auth-bundle and an explicit permission set, but it's still user-consumable (i.e. 4 items)? Could then provide some dev guidance like 'aim to use no more than X items for user sanity...'.

It would be very cool if there was a UI way to present 'create and delete to block and follow under app.bsky.graph for <author provided reason>' to further 'compress' here - this could be some JS client-side wizardry if you wanted to go all-out.

[dholms]

We plan to offer multiple "bundles" of auth scopes. So ideally you would be able to find a bundle that works for you. Posts + Blocks + Follows & nothing else is probably a little bit unique. But maybe it could be composed of two bundles: app.bsky.auth.graph (for managing graph relationshipsandapp.bsky.auth.post` which provides a nice human-readable description for creating post records).

A client dev can always get exactly the scopes they want by just requesting auth-resources, but of course there's a UX tradeoff on that - the resource description is given to the user in a more generic way rather than descriptively. This system does give us the ability for client devs to figure out what bundles of permissions are needed most and then to pave the cow paths.

[mary-ext]

How should an app like PDSls are expected to work going forward where the expectancy is that it gets permission to do writes on any and all records, even on unknown ones?

[dholms]

We plan to have some special-cased com.atproto permissions for doing that 👍 Basically "Full-access to repository"

[mikestaub]

This is a great start to a complex topic, but I worry that we are just reinventing https://github.com/cedar-policy/cedar with the Lexicon system. Have you considered integrating with some existing authz framework/library vs doing everything custom?

[blowdart]

In the lexicon definition you have the type as "auth-resource". This, to me, appears to be a bad name. "Auth" can either be authentication or authorization or both. Which is it here? It reads like a resource permission, and that would be a clearer name.

You're right about this granularity being difficult for both users and developers to parse, and I have concerns about the size of the access token that is going to carry them. Remember the jwt needs to be sent with every request, in a header. While there's no RFC standard for this different web servers put their own limits on header size, for example, Apache is 8k, as is NodeJS, IIS is 16k. Additionally, some also place limits on the total size of all the headers.

Descriptions of bundles and permissions/auth-resources need to cope with internationalization :) Providing a standard default description in multiple languages that any PDS implementation can use would help present users with the same experience in authorization regardless of service.

[langedev]

I like what is here. It feels very elegant to reuse the tools (lexicons) devs will already have to learn.

I'm a little worried about overloading the description field here. In the current docs, it says "Each primary definition schema object includes these fields:" and then lists description. That is true, and will continue to be true. That said, Auth-bundle is planning to have description be explicitly user-facing. Every other lexicon uses description as notes or comments to developers using the lexicon, they aren't explicitly user-facing. I worry about the confusion this adds for new developers. I doubt there would be any major problems here, besides funny formatting a developer may put in their auth-bundle, but I would vote to change the name from what everyone else has. I wish we could have this field be called "description" and everything else be called "comment", but we're past that. Perhaps something dumb like "user-description" would work. Maybe "summary"?

I'd still be happy with description, but the docs would have to make clear that this description is very different from the rest in a way that I feel would be annoying to write.

[travishaagen]

@dholms ! great meeting you last weekend! I haven't fully wrapped my head around your auth-bundle and auth-resource proposal, but here are some thoughts about scopes and permissions.

• Scopes
  • @blowdart is right that a JWT should be as small as possible, because they are sent in every request
  • Agree that namespacing scopes is a good practice, but the shorter-the-better
  • Permissions like read, write, delete, etc. could use single letters to represent them
    • Example: “some.namespace:w”
    • Could assume “w” also has “r”, and “a” has all permissions
  • Scopes are not well suited for fine-grained access control
    • Goal is to keep JWT small
    • They are bearer tokens, so permissions are retained during the lifetime of the token (e.g., expiration)
• Consent screens
  • Consent is requested for sharing personal data with third-parties
  • An app would request consent on first access (or after access is revoked and then the app is again used)
  • These should be succinct and not a complex permissioning page
  • You could represent “groups of scopes” with fewer line items, rather than one item per scope
  • Example,
    • The “B” App is requesting access to,
      • Your account profile
      • Your email address
      • Store and retrieve information
• Permission API and UX
  • The permissioning could be complex, so I think it is worth considering an actual permissioning system that doesn’t necessarily require OAuth scopes.
  • The PDS can decide on every API call whether the permission can be granted, which is what they would be doing anyhow with scopes.
  • There would be a Permission API where applications can request desired access and a User can choose to enable it or not.
  • This would make it easier for apps to request access to data that didn’t originate from the app itself, and to make it clear what the implications are.
  • There could be pop-ups, kind of like “can we send you notifications?” that appear when a certain context is triggered. You might jump back to your primary PDS client application (e.g., BlueSky) to read more details and make your choice.
• When would scopes be better than permissions?
  • Offline access (App isn’t open) where the App might access APIs hosted by multiple servers
  • If the PDS issues tokens and hosts all the APIs that can be accessed with a token, then the above isn’t a concern
• Token Exchange
  • The idea of “Token Exchange” can be useful in some cases, where you exchange one token for another that has different scopes.
  • These tokens are often not returned to the client application, but are used for upstream requests.
  • Not advocating for this, but I’m also not aware of all current use cases, so this is one way to increase flexibility without increasing the size of App issued tokens

[afbase]

@travishaagen

With regard to the token exchange, is this like token attenuation that you might see with bisuits (example here) or macaroons?

[travishaagen]

@afbase : OAuth "Token Exchange" was originally described in RFC 8693.

At my day job, we took some ideas from it for the following use cases,

• We could have multiple OAuth token issuers (e.g., authenticated users vs employees), and an API Gateway (proxy) would initiate token-exchange, so all upstream services only needed to trust tokens issued by the token-exchange issuer. These tokens were only used in the cloud, short lived, and never exposed outside the cloud.
• It can be a rule engine, where you exchange one token (e.g., only has permission to talk to an edge API gateway), and the exchanged token is given additional scopes (permissions) so that backend-to-backend calls could be made to another service that expects a different scope (e.g., legacy system).
• We also used it to help with the transition to OAuth. It could exchange legacy session IDs for access tokens with limited scope. In this way, it can be a bridge between non-OAuth authentication tokens and OAuth.

It's just a tool in the tool kit. Simple is always better.

[tomthebuzz]

Like the auth-bundle and auth-resource approach as a common starting point. Also think we should double click on the aud path for detailing the service authentication.

From an Agoris (caring communities) PoV we will have regional cooperations caring for around 15-30k citizens. Some will want to use their own node / hosting / pds / theming and others will want to use a more centralized and regional full service approach.

In any case we will have private, commercial and a mix of both user groups that each offer and consume services. And it is up to the service provider to spec as to whom they want to offer their services both from a domain, user group and regional perspective.

I think we can design almost all requirement with the Lexicon based approach. Having worked with enterprise scale IAMs and Keycloak a lot we also might want to discuss the generic use of „allow“ vs. „deny“ in the schemas in order to be more flexible in designing specific policies.

Also echoing other voices we should think about whether we can learn from the current IPSIE efforts to see what we can re-use instead of reinventing.