FediForumTM

Social Web Events

Project Map

@fediforum@mastodon.social
@fediforum.org
FediForum June 2025:

OAuth for Clients: Where We Are and Where We’re Going

/2025-06/session/3-a/

Topics:

Convener: Emelia Smith (@thisismissem@hachyderm.io)

Participants who chose to record their names here:

Website: https://github.com/mastodon/mastodon/issues/34316

Notes

Emelia presenting state of the union with Mastodon OAuth (specifically)

Roadmap in GitHub issue -> moving more into the OAuth 2.0 space

Big rework on documentation on OAuth for Mastodon over the past couple of releases.

Mastodon 4.3.0 removed garbage collection of apps that do not have active access tokens, this is indicated in the response for the application registration by the presence of the client_secret_expires_at value being 0

We’ve introduced the /.well-known/oauth-authorization-server endpoint as of Mastodon 4.3.0, and this enables discovery of the features supported by the OAuth Authorization Server:

For instance:

  • Is token revocation supported?
  • Does this server support scopes that my application needs?
  • Can I use PKCE to secure the authorization codes?

This endpoint does not require authentication to call, and will return what the capabilities are of the server that your are wanting to authenticate against. Therefore by requesting the document you get a lot of rich information about how you can interact with that server.

Two examples are:

You can see that the two different software products provide slightly different responses, namely in the number of scopes supported.

Previously access tokens never expired. Working towards adding expiry to all access tokens and supporting refresh tokens, but there are various considerations as to not break the ecosystem. This will be in a future release of Mastodon, and can be detected via the presence of the offline_access scope and refresh_token grant type being supported. As well as via the expires_in property on /oauth/token responses.

New OAuth profile scope in 4.3, and a userinfo endpoint added in Mastodon 4.4 (which is now in beta)

For all authorization code grant flows (the one which involves redirects), we strongly encourage application developers and server developers to support Proof of Key for Code Exchange (RFC7636):

  • https://oauth.net/2/pkce/
  • This prevents the theft of the code returned during the authorization code grant flow, by binding it to a value only the client knows.
  • This is relevant for all client types, both public and confidential; mobile applications, browser-based apps and server-side apps.

https://oauth.net is a great resource for learning about the specification, with fairly approachable language — OAuth does not need to be hard.

Mastodon also has an app registration endpoint - it doesn’t implement the dynamic client registration RFC 7591

Emelia talked to with Aaron Parecki, the editor of the OAuth spec, about the future of OAuth for Mastodon, and how we can support IndieAuth and FedCM - Federated Credential Management.

The result of this conversation was that we need to remove the barrier of client registration before authorization, so we took an idea first proposed in Solid OIDC, and lifted that up to an IETF Internet Draft for the OAuth Working Group. This is known as Client ID Metadata Documents: https://drafts.aaronpk.com/draft-parecki-oauth-client-id-metadata-document/draft-parecki-oauth-client-id-metadata-document.html

We published the first version of this internet draft last year, and just by chance it also solved what AT Proto needed for OAuth, and they became the first implementation of that internet draft.

FedCM allows for seamless login across services via browser-native flows:

Public and Confidential client model, in which public clients do not have client_secret key

Adding expiry date to access tokens, with the addition of refresh tokens

currently, user ends up with multiple entries for the same app in their settings, with new client ID metadata docs these could be collapsed into one for each app

Device code grant flow continues to be something that e.g. IoT devices and others might want - get a simple code that can be entered into other devices. Some issues with the dependency that Mastodon needs for implement these, and we’re working to resolve those issues.

Deliberate choice to use some OIDC types of references as that is a future direction, but this is not where we are yet.

Some additional information in the GoToSocial issue tracker https://codeberg.org/superseriousbusiness/gotosocial/issues/4230

RFC 9700 Best current practices for OAuth 2 security, foundation for OAuth 2.1 work https://www.rfc-editor.org/rfc/rfc9700.html

OAuth 2.1 will deprecate several features that were previously permitted/present in OAuth 2.0. Mastodon 4.3 already implementing some of these changes, such as a removal of the password grant flow. Device code grant flow is its replacement for low-input capable devices.

Longer term, the existing access tokens and clients will be automatically expired at some point, as to help clean up the security related to these tokens never expiring. This is still to be planned, and we’ll be careful with our approach to ensure we don’t suddenly break the ecosystem — i.e., we’ll allow enough time to pass for client developers to upgrade their applications.

A good starting point for any Fediverse server would be to enable the /.well-known authorization server endpoint

Jeremiah (chat): I think the Grant Negotiation and Authorization Protocol (GNAP, RFC 9635) is a worth considering as a replacement for OAuth 2. Tighter specification that addresses many of OAuth 2’s design issues/variations/complications. It’s influenced several follow-up addendum RFCs for OAuth 2, but there’s only so much that can be retrofitted. It’s being adopted by several financial institution use cases.

Emelia: At this time, we are not considering GNAP, but instead continuing forwards with OAuth 2.1 with a vision towards OpenID Connect.

General comment - this presentation should have been recorded, and would be an excellent piece of content as a one-off recorded talk to put on PeerTube and share with Fedi developers.

Emelia: We will be preparing more content on these changes soon, but we’re still to work out the details for this.

Expiring access tokens are a necessity to improve the security model overall. In Mastodon, this will be introduced gradually, in a backwards compatible way, as to not break existing clients. In the case of a hard expiration of old tokens, we’ll likely do something like revoking access tokens and clients that have not been used in the past 2 years. (Still TBD, but would be targeted for Mastodon 5.0.0)

Samir: Request for Mastodon rate limits to be access token based instead of IP address. Emelia: Rate limit already per user. There is a global rate limit, but then if you have an access token, it has its own rate limit. Could be a case of unauthenticated rate limit being applied when an access token being used. If so, that would be a bug.

C2S: Work in progress, needs to be a working group convened to make it better and more useful. Discussion of whether Mastodon’s API should become standard. It’s the dominant one, but there could be other use cases where other APIs would better serve the use case. Multiple APIs could coexist in implementations.

Emelia: The current stance is that whilst the Mastodon API has become a defacto API for the fediverse, we don’t actually want it to be so, and encouraging application developers to build APIs that work for their clients, and to get together with server developers to expand the usefulness of ActivityPub Client to Server APIs for application developers.

Samir: When will PKCE be a requirement? In Mastodon 5.0.0 is the target. Emelia: A bunch of issues with clients still need to be fixed, as learned from Hollo’s implementation, and we’re working with client application developers to help them move towards better interoperability and security.

Emelia: Dynamic client registration is one time per server, not per user, which limits the amount of information that needs to be stored by authorization servers.

Emelia: Treat access token tokens, refresh tokens, and code parameter as passwords. Encrypt and salt them. Make sure they are not logged.