Latch - an Elixir atproto OAuth library

As part of building a service for automatically publishing blog posts from RSS feeds into atproto's standard.site lexicon, I implemented atproto OAuth for logging in and getting access tokens to publish for the user. This means that any user with an atproto account, whether they created it on Bluesky, Eurosky, or Blacksky, or any of the other Personal Data Servers available, can log in to your service. Atproto OAuth does not require pre-registering clients with a service, one implementation works across the entire ecosystem.

The OAuth implementation is based on the 2.1 specification with some still in-draft extensions, and comes with some quirks compared to what you'd expect from older generations of OAuth. For example, access tokens can't be used as is, they need to come with a DPoP (demonstrating proof of possession) header signed for the specific request you're making, limiting what the access token can be used for if stolen. Additionally it includes PAR (push authorization request) and some other fun stuff like PKCE, but maybe one of the most significant being CIMD (client ID metadata document), the thing that lets you prove who you are as a client without registering in advance.

The goal of Latch is to provide an idiomatic Elixir implementation that deals with all of this for you, while maintaining flexibility and enabling things like setting up multiple OAuth clients in the same project, and starting them ad-hoc on command. I have strong feelings about designing Elixir libraries and I've tried to apply the best practices here.

Quickstart

For a complete Phoenix example integration of Latch, take a look at the source code for annot.at.

Add Latch to your project.

[object Object],[object Object],[object Object],[object Object],[object Object]

Create a Latch Store module for storing in-progress requests and access tokens. You can create your own Store implementation by implementing the Latch.Store behavior, for example here's an Ecto backed one from annot.at.

[object Object],[object Object],[object Object]

Add it and your Latch instance to your supervision tree.

[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object]

Set up routes to serve the CIMD (client ID metadata document) at /oauth-client-metadata.json and your callback route.

[object Object],[object Object]

and implement your AuthController with:

[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object]

Now the rest of it is fairly recognizable if you've done OAuth before. Call authorize when a user has passed their handle to log in, redirect them to the URL you get back, and then provide a callback URL to finish the flow.

[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object]

Now you can hit private endpoints or write to the user's atproto PDS, according to the scopes you requested. Here's are some example requests. Note that access tokens are managed and refreshed automatically by the library.

[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object]

I've previously written a bit about atproto and Latch on https://blog.annot.at and I'm planning on writing more about it here, especially around how atproto OAuth works, and some of the design decisions that went into making Latch.

Here are some links:

• Github https://github.com/joladev/latch
• Tangled https://tangled.org/jola.dev/latch
• hex.pm https://hex.pm/packages/latch
• HexDocs https://latch.hexdocs.pm/readme.html

Let me know how you find it! Really excited to see more Elixir atproto apps!