OAuth Roadmap

[bnewbold]

OAuth is nigh! Protocol support has been a long time coming and we are pumped. It should greatly improve the user and developer experiences building secure apps and integrations on atproto. And could make the handles-and-DIDs identity system a more useful, re-usable, and inter-operable component for other non-atproto apps and protocols to built on.

At the same time, authentication and authorization are complex, security-sensitive, and central to the design of almost every client in the ecosystem. We want to clarify and temper expectations around when specific functionality will be available. This is a flexible/living roadmap for how roll-out will go.

Developer Preview Phase

UPDATE: September 25th blog post announcing this phase

In this phase, early-adopter client developers can start using OAuth as an alternative to App Passwords. More sophisticated use-cases (eg, granular access scopes and additional 2FA methods) may not be available yet, and support in client SDKs will probably be work-in-progress. We roughly expect to enter this phase in late summer 2024.

• Complete written specs and docs describing all the supported flavors and variants of OAuth. These should be complete drafts, but not entirely set in stone: we could still make small changes to the details during this phase.
• Only minimal authorization scopes will be defined, aligning with current access control levels. These basically come down to read/write to the entire repo; and an additional level of access to manage identity and account details. A separate scope for DMs/chats would certainly make sense, but might come later.
• The Bluesky PDS software implementation supports the server side of OAuth. The self-hosted distribution has already supported OAuth in recent weeks; the production PDS instances and bsky.social entryway operated by Bluesky will also have support. This includes basic web interface in the PDS for logging in with password (and/or other auth factors) and approving apps during auth flows.
• The Bluesky Social app itself (web and mobile) may or may not transition to OAuth for auth.
• Ozone (the Bluesky moderation service software) will be updated to use OAuth as a client.

Transition Phase

In this phase, support for client developers should be solid, and most apps will be encouraged and expected to migrate to OAuth. We don't want to be too disruptive and expect major work from small teams and volunteer/hobbyist devs in the ecosystem, so this phase will last at least a few months.

We roughly expect to be in this phase in autumn 2024.

• Auth scopes are more fleshed out, and support the most popular use cases in the ecosystem. They may not be fully generalized or work well with independent apps/Lexicons yet.
• Bluesky Social app (web and mobile) gets full support for OAuth, and most users are transitioned to this auth flow for day-to-day use.
• Bluesky Social client app will likely continue to support legacy auth for some time window, but possibly not the full transition window. The use case for this is supporting independent PDS implementations which have not yet implemented OAuth server-side. There might end up being a fork or advance configuration option to control this, if secure support of two separate auth stacks ends up being too difficult.
• PDS web interface supports more account management functionality, such as account sign-up, or de-authorizing specific linked apps.
• App Passwords continue to be supported, but are described as deprecated.

End State

This is the goal we are working towards.

We roughly hope to get to this point some time in 2025.

• OAuth is the recommended, stable, and dominant/adopted mechanism for auth between atproto clients (including end-devices, web apps, and integrations) and services. atproto SDKs include robust/secure/complete OAuth support.
• Auth scopes are clear to work with both for users and developers. There is a clear path to working with scopes specific to novel apps and Lexicons.
• The "atproto flavor of OAuth" is aligned with IETF OAuth standards. The atproto specs and written docs can reference IETF standards (or at least drafts) for all of the major functionality.
• PDS implementations should not need to support legacy auth (password login followed by refresh tokens). A PDS implementation should be able to support just OAuth and work with popular apps, tools, and integrations in the ecosystem. Supporting alternative auth mechanisms (like API tokens) would be recommended to support developers and smaller projects.
• It is supported and encouraged to use atproto OAuth for authentication in apps and services which don’t otherwise use atproto. For example, "login with atproto" and OpenID Connect (OIDC) use-cases.

Open Questions

Account Management Lexicons:: the PDS web interface is expected to become the primary interface for managing things like handles, account deactivation/deletion, updating email, signup, account migration, etc. While these will remain "in-protocol" behaviors and actions, it isn't clear if the current com.atproto Lexicons supporting them should be required, optional, or even part of atproto itself at all. This is an "end state" question.

Alternative Auth Mechanisms: the flavor of OAuth used with atproto will require some form of publicly available client metadata. This is reasonable for most client apps, but would be friction for simple demo scripts and basic bots. We hope to have an simple alternative mechanism similar to "developer API tokens" on other platforms, where developers can generate secret tokens via the PDS web interface and pass them to CLI scripts and bots for persistent auth with limited scopes. Not yet clear if this will be an evolution of app-passwords or a new concept, and if this will be an optional or required part of the protocol, or something left up to PDS implementations to decide on. This is probably a "transition phase" question.

Service Auth: atproto uses a separate flavor of authentication between servers and services, and OAuth will not directly impact this. It is possible that this aspect of auth in atproto will also evolve in the future.

[tom-sherman]

Exciting stuff!

Re-reading the proposal, particularly the part that mentions the specs to be used: PAR, PKCE, and DPoP. I'm wondering how widespread these implementations are in the ecosystem? Or do we expect there to be lots of work in auth libraries to support atproto login?

A specific related question: what's missing from https://authjs.dev to take advantage of this? Would be great if you folks could show a demo of it working with Auth.js!

[bnewbold]

That is a great question! And something we are looking to explore and learn about in these early phases. Also which cryptographic systems (curves, etc) to support or not support.

For the typescript/javascript ecosystem specifically, we will have SDK support for both the server-side and client-side in various environments (web/browser, node.js).

We also want to have full support in the Go SDK but haven't started that yet, and will be looking at Python.

This is all thinking from the perspective of "atproto projects" and "atproto SDKs" though. It would also be great to support generic OAuth libraries for integrations. I suspect that those libraries would have support for the necessary components (PAR, PKCE, DPoP), but might not work out-of-box because there is a need for handle/PDS lookup, etc. Will learn by trying!

[tom-sherman]

This is all thinking from the perspective of "atproto projects" and "atproto SDKs" though.

Just wanted to call out that this also only works for those atproto projects built with a similar stack to Bluesky ie. Client rendered and controlled.

On Frontpage we have a much more isomorphic approach (data fetching on server and client) and so these SDKs aren't really suitable for us.

I'll definitely keep you folks posted on our attempts to integrate this 😅 we'll be looking to do it in the first phase for sure.

[devinivy]

The SDKs we provide for OAuth should support both BFF and browser-based clients 👍

[snarfed]

Exciting!

Are you all still thinking through whether or how much you plan to integrate and require OAuth directly into ATProto itself? Notably:

OAuth is the recommended, stable, and dominant/adopted mechanism for auth between atproto clients (including end-devices, web apps, and integrations) and services. atproto SDKs include robust/secure/complete OAuth support.

recommended is a useful word there, but notably it's not required. You also mention the phrase "login with atproto," which sounds great, but if it's OAuth-based, would obviously require PDSes to support OAuth.

Long term, do you foresee that OAuth is more of a nice-to-have for PDSes, or closer to a requirement?

[bnewbold]

Good question! I don't have a firm answer and not sure we have internal consensus on this. I think this will probably be a later-stage decision, maybe even when going to a standards body? My expectation is that there will be huge pressure to support OAuth for actual interop in the ecosystem, but that there may be corner-cases with "headless" or non-client-connected PDS instances that just don't bother with any auth, or only have a local command-line interface or something like that.

The flip question is how this would be enforced if it was a "hard requirement". I can't imagine OAuth being a "MUST" for something like a Relay to subscribe to a PDS.

[ngerakines]

Do you have any guidance on what language to use for client applications with login forms? I'm particularly interested in staying true to the idea that their atprotocol network handle is the thing that they use and also reducing confusion about handles or identifiers for other services.

[bnewbold]

Great question! I don't have any concrete guidance for you right now, but this is something that we should probably provide both specific best practices on, and a polished example that folks can just copy.

Some thoughts:

• love what you have so far!
• what does "create account" flow look like? linking to a default provider will empower/centralize that provider, but providing multiple leads to the activitypub "how to chose" problem
• it is possible to support any of: handle, DID, PDS hostname. should we recommend/nudge that implementors support all those, or just focus on handles?
• should "bluesky" be mentioned at all, or just atproto? atproto is the commons protocol and vision we want to promote, but pragmatically Bluesky is probably the more popular brand

[ngerakines]

love what you have so far!

Thanks!

what does "create account" flow look like? linking to a default provider will empower/centralize that provider, but providing multiple leads to the activitypub "how to chose" problem

With PDS supporting a minimal web interface to support OAuth, does that mean they could / will support a basic sign-up form if enabled? Might be worth exploring as a practical feature that encourages account distribution across the network.

it is possible to support any of: handle, DID, PDS hostname. should we recommend/nudge that implementors support all those, or just focus on handles?

I think it would be good to encourage applications and users to refer to handles directly, especially in the @handle format. Using DIDs is going to be intimidating, and referring to the PDS could lead to accidents ("I used the wrong PDS, got confused, and created a second DID ...").

should "bluesky" be mentioned at all, or just atproto? atproto is the commons protocol and vision we want to promote, but pragmatically Bluesky is probably the more popular brand

Yeah, for now, I'm not mentioning atprotocol and giving a node to "bsky.social" in the placeholder. If someone gets to the app and knows to use their own domain, then they probably know enough about atprotocol already, and anyone else would recognize the "user.bsky.social" reference.

[tom-sherman]

should "bluesky" be mentioned at all, or just atproto? atproto is the commons protocol and vision we want to promote, but pragmatically Bluesky is probably the more popular brand

I fear calling it a Bluesky thing damages the idea of atproto in the long run. Bluesky == atproto is already a common misconception and oauth is a good opportunity to start to change that.

What i'd recommend: Bluesky start to refer to IDs/logins/accounts as eg. "Web Handles" (just an example, what it's called doesn't really matter that much). Other apps can also then start to use this term on a level playing field.

[chockenberry]

Will this work with Apple's AuthenticationServices (e.g. ASWebAuthenticationSession)? This is the standard mechanism used on iOS and it's fully integrated with the password autofill APIs - it's very easy for both developers and customers to use.

The reason I ask is because I can't find any information about authorization endpoints or callback urls (ASWebAuthenticationSession needs both).

[bnewbold]

I think something like that is the intent for login flow using OAuth in the Bluesky Social app itself, on iOS. cc: @haileyok who might know more.

[chockenberry]

I'm really confused about where the client_id comes from and why there doesn't appear to be a client_secret. And without this knowledge, I've got no idea how to form a URL that I can pass to ASWebAuthenticationSession.

[anderspitman]

Hey @chockenberry, the client_id is the URL of the client metadata document which your app hosts, typically something like https://example.com/client-metadata.json. client_secret is not necessary. Secrets are somewhat less used nowadays since frontend JavaScript apps and native apps can't really protect a secret. PKCE is used to cover a lot of the same benefits as a secret.

[matthieusieben]

The authorize endpoint is returned as result of the Pushed Authorization Request ("PAR").

The callback URL is whatever you defined in the client metadata JSON.

The client_id is the URL where that client metadata is hosted.

If you implement all this from scratch, please, please, read the OAuth specification thoroughly as failing to properly validate the retuned values, as described in that spec, may have critical security implications.

[chockenberry]

I do not want to implement this from scratch. That's the point of using ASWebAuthenticationSession. As an app developer, I don't know what PKCE or PAR are for - and to be honest, I don't want to know. I already know how hard it is to get this stuff right, and I want to use a system framework where someone more capable than me has done the work. There are also secondary issues, like export restrictions on apps with encryption, that make me want to use stuff provided by the system.

And I'm not alone here - every app developer is going to want the same thing. This is a quick overview of how ASWebAuthenticationSession works.

I hand it a URL like this:

https://mastodon.social/oauth/authorize?response_type=code&redirect_uri=tapestry://oauth&scope=read+write+push&state=749495069&client_id=REDACTED&client_secret=REDACTED

The system then presents a web view, handles usernames, passwords, two factor, passkeys, etc. When authorization in the web view finishes, I get back:

tapestry://oauth?code=REDACTED&state=749495069

Note that the app gets this information because it has registered "tapestry:" as a URL scheme in its application settings (Info.plist).

I then pass that code to the endpoint that generates the access and refresh tokens which are stored securely in the user's keychain.

Notice how I haven't mentioned PKCE or PAR here?

My fear is that what you're proposing and building aren't compatible with ASWebAuthenticationSession. And if that's the case, you're going to have problems internally (with your own app) and with all the apps that want to post information (game scores, news, etc.).

I think my next step is to build an app that tries to post something on Bluesky and put it on Github. If it works, it will be an example for other app developers. If it doesn't, you can figure out what you need to do to make it work.

[anderspitman]

Late to this party. @bnewbold not sure if this is the best place or if I should comment directly on bluesky-social/atproto-website#326. Let me know.

A few things:

• I probably just missed this in the draft spec, but it seems like maybe you could have mostly retained OIDC compatibility? You just run OIDC then verify the iss is authoritative for the sub you get back in the ID token. What am I missing?

• As you called out in the draft, some clients might have a hard time hosting metadata documents. I think this is especially likely for open source software that's intended to be self-hosted. In this case either every user would have to host client metadata separately, or the developer of the software would have to host it. This would mean all users would share the same client data, and they would have a permanent dependency on the developer continuing to host the metadata. Have you considered implementing something like this. It's the technique I use for LastLogin. Essentially the only piece of information required is the client_id and redirect_uri, which must be a strict suffix of the client_id. This lets you have completely anonymous clients. The user ends up seeing something like "example.com wants to log you in. Do you want to approve?". In the case I'm talking about, the client_id would be something like http://localhost:34832, and the user might see "An app on your local device wants to log you in...".

• I agree with @tom-sherman above. I think it would be good to push a user-friendly name for login flows. I don't hate "web handle". Could even do "Sign in with Fediverse" and then let them use ActivityPub or ATProto? idk but I think "Sign in with ATProto" would be pretty confusing.

[bnewbold]

Thanks for your comment! All good feedback.

OIDC: the main issue is that this is different from how OIDC usually works, so it wouldn't "just work" with existing OIDC libraries and flows. Or worse, folks would try to just use OIDC libraries out of the box and not implement the critical check. Hopefully we can work this out in the long term, but we want to start with something less foot-gun-y and confusing.

Client Metadata: would encourage centralizing that discussion in the IETF working group and venues discussing client metadata generally. We'll most likely follow the updates and final recommendations in that specification, which we hope will be reused by other protocols and projects, not just atproto.

Login flow terminology: I don't think we are in a position to be too prescriptive about this right now. There are some patterns we'd like folks to avoid (like "Bluesky" branding for this), but I don't think we have consensus or at the point where we directly want to push specific phrasing like "Web Handle". We'd like to leave room for more projects/orgs/individuals to be stakeholders in this identity system... if "Web Handle" gets organic traction maybe we'll adopt it!

[anderspitman]

This all makes sense. Thanks!

[anderspitman]

@bnewbold I've started trying to implement atproto OAuth for logging in a client application. So far I'm able to resolve a handle to a DID, retrieve the DID document and the AS metadata, and redirect to the AS. That's where I'm stuck. It's giving me a pretty opaque error:

Any suggestions on how to debug? I'm writing my implementation from scratch because I want to reduce dependencies, and I want to learn the protocol.

[anderspitman]

A clue. I tried it from a different client_id and got: "Missing token_endpoint_auth_method client metadata". I'm guessing that it's caching the bad client metadata. If so, is there a way I can request it to not cache while I'm debugging?

I also noticed that the list of client metadata parameters indicates which ones are required. I'm still missing some of them. I'll start going through and adding them.

I did notice that token_endpoint_auth_method is listed as optional, so the error I'm currently getting might be a bug.

[anderspitman]

Got it! I'm not sure exactly which missing parameter was the problem (just adding token_endpoint_auth_method didn't fix it), but after making my metadata document match the example in this section I got to the next step.

[bnewbold]

The HTTP error responses should hopefully have good messages to help debug. I think we have some additional messages going out soon. In the past I had some success using my own PDS instance and looking at the logs coming out on the PDS side, but that isn't super ergonomic for most client devs. I'd also recommend looking at the python example code, which is pretty "from scratch".

[anderspitman]

@bnewbold where's the best place to give feedback on the protocol? I'm working on a universal login middleware with a focus on decentralized protocols. It can be dropped into any JavaScript backend (https://github.com/lastlogin-net/decent-auth-js).

I've got a demo running here: https://decent-auth-demo.lastlogin.io/

It currently works with Mastodon, ATProto, and LastLogin. IndieAuth shouldn't be too hard to add.

My main complaint is still that hosting the client metadata is required. This means my middleware won't work for atproto for self-hosted apps that don't have a public IP. It will still work for Mastodon and LastLogin, since Mastodon supports dynamic client registration and LastLogin support anonymous clients (only the clien_id URL is required to display to the user).

One other nitpick is that I don't think you should show the client name to the user for unverified clients. Even if you show the client_id URL as well, if a malicious client used the name "Google" it could still trick some users.

[bnewbold]

Starting a new top-level discussion here on github is the best current option, but we can also just thread here.

Can understand that client metadata is hosting is friction for some use-cases. I think all the options on the table (eg, dynamic client registration) have entangled security, trust, and developer friction trade-offs. We think it is important to reduce the number of options and variations as much as possible, or the overall complexity gets overwhelming for folks trying to do interoperable implementations. So we probably aren't going to change that overall requirement, though there might be ways to improve the localhost option for some use-cases (not sure if that would help you). There might also be design patterns or supporting infrastructure that emerges to help reduce the friction of hosting client metadata.

@matthieusieben could confirm where we landed in the end (I know there is a spec-alignment PR in the works that hasn't been deployed yet), but I don't think we display the client_name field for unverified clients, as discussed in the "Security Considerations" section of the spec.

[matthieusieben]

The client_name should not be displayed indeed. There is an issue in the current implementation that causes the name to be displayed anyway. It will be fixed when the following PR lands.

@anderspitman thanks for the report.

[llksz]

Hi all,

I'm currently implementing the atproto OAuth flow for a native application (mobile/desktop) and have a question regarding best practices for user handle resolution.

In my implementation, I'm currently resolving user handles using ordinary DNS (unencrypted). However, I'm wondering whether it's considered best practice for native clients to use a more secure DNS resolution method, such as DNS over HTTPS, to enhance privacy and security.

Could you please advise on what is generally recommended or expected for native OAuth clients in this context?

Thanks

[jalcine]

I meant to reply to this with #2656 (comment)

I guess GitHub's discussions e-mail support is broken

[anderspitman]

I went with DoH since I'm working on frontend JavaScript apps and that was easiest. For a native app I would probably just use whatever the system uses for DNS, assuming the programming language has a simple DNS API.

[matthieusieben]

This is why we display a warning as the user enter their passwords during an OAuth flow. As long as the users make sure they enter their password on the right (HTTPS) website, they should be fine.

It is a good idea to use DoH as it should help protect users from phishing attacks.

[llksz]

@matthieusieben Thanks for your response. Thinking about it a bit more, I guess I'm more concerned with user privacy than security. I must also admit that I was a little startled when I realized that the user handle is transmitted in plain text. 😅

[jalcine]

You should probably look at what https://oauth.net/ recommends (which is really "whatever works"). Having a strict requirement for DoH or some kind of check of DNSSEC might be a bit of overkill; but I can see that being a nice feature in an application.

…

On Tue, Oct 1, 2024, at 13:17, llksz wrote: Hi all, I'm currently implementing the atproto OAuth flow for a native application and have a question regarding best practices for user handle resolution. In my implementation, I'm currently resolving user handles using ordinary DNS (unencrypted). However, I'm wondering whether it's considered best practice for native clients to use a more secure DNS resolution method, such as DNS over HTTPS, to enhance privacy and security. Could you please advise on what is generally recommended or expected for native OAuth clients in this context? Thanks

[mary-ext]

It would be very nice if the option to give longer-lived or shorter-lived tokens were up to the user, rather than what seemed more "secure".

I distrust backends/BFFs more than SPAs. With backends, even if there is an open source code available somewhere it is still essentially a black box that I can't peek into any time, meanwhile with SPAs I could easily do so even if it comes down to making sense of bundled/minified code.