Introducing OAuth Client ID Metadata Documents

Between March and May 2024, I had been working on a lot of changes in Mastodon’s OAuth implementation, trying to bring it closer to standards and improve security, reducing a lot of the rough edges that I’d come across whilst making IFTAS FediCheck production-ready.

A lot of that work has now landed in Mastodon 4.3.0, perhaps the biggest change was implementing OAuth Authorization Server Metadata discovery, which enables client applications to discover the OAuth endpoints, scopes, and grant flows supported by the authorization server, so for example a client application that wants to use the new profile scope can check if the Mastodon server actually supports it before doing the Authorization Code Grant flow, if it doesn’t then it can downgrade to using read:accounts to access the same endpoints. Allowing client applications to adopt newer scopes whilst still supporting older Mastodon versions.

Some other changes made were adding support for PKCE which improves the security of authorization codes and adding official support for multiple redirect URIs for client applications.

Enter Client ID Metadata Documents

In May, Aaron Parecki, the Editor of the IETF OAuth Working Group, reached out to me to ask how we could get support for both FedCM and IndieAuth into Mastodon. We setup a call to discuss, and the outcome of that call was that we needed to solve the issue of many clients to many authorization servers and not having a singular client_id value that can be used across different Mastodon servers, since Mastodon only supports a custom API similar to OAuth Dynamic Client Registration, and that results in a unique client_id per server.

As I’d worked on the Solid Project during my time at Inrupt, maintaining the solid-client-* npm packages, I was aware of an extension to OIDC (which is an identity layer on top of OAuth 2) that the Solid Project had written called Solid OIDC Client Identifier Documents. These seemed exactly what we needed for a federated or decentralized environment such as that which exists in Mastodon and the wider Fediverse. I talked Aaron through this extension. He countered that IndieAuth supported a similar discovery mechanism for client information via MicroFormats, but agreed that simple JSON documents were far easier to parse and work with than MicroFormats.

One of us proposed that we take Solid OIDC Client Identifier Documents and lift those up to the level of an OAuth IETF RFC, such that we could use them outside of the Solid ecosystem. Aaron kickstarted that process by staring to draft up an IETF Internet Draft. I asked if I could be a co-author, Aaron said yes, and kindly opened that door to me.

I’d only previous been involved in the IETF standards process during the design of the WebSockets protocol back in 2010, and that was just mailing list participation. Now I’m actually co-authoring an internet draft, wild.

Since then, Bluesky has adopted OAuth Client ID Metadata Documents, as has IndieAuth, superseding their MicroFormats based discovery mechanism. We’ve also presented the draft at IETF 120 in Vancouver.

Mastodon does want to support them, however, there’s some additional changes we still need to make in the Mastodon codebase before we implement them. I’m currently looking at writing this as a Doorkeeper extension, instead of just implementing directly in Mastodon.

Additionally, the work needs funding since I’d likely be doing the bulk of it, and I’m self-employed and the amount of work here certainly exceeds the amount of funding I receive from the community.

What does a Client ID Metadata Document look like?

A Client ID Metadata Document is a JSON document that can be hosted at any URL, so long as that URL exists within the document as the client_id value. The valid properties in these documents are the same as those used in OAuth Dynamic Client Registration.

An example document, hosted at https://app.example/client_id.json is as follows:

{ 
  "client_id": "https://app.example/client_id.json", 
  "client_name": "Application Name", 
  "redirect_uris": ["https://app.example/callback"], 
  "post_logout_redirect_uris": ["https://app.example/logout"], 
  "client_uri": "https://app.example/", 
  "logo_uri" : "https://app.example/logo.png", 
  "tos_uri" : "https://app.example/tos.html", 
  "scope" : "openid profile offline_access webid", 
  "grant_types" : ["refresh_token","authorization_code"], 
  "response_types" : ["code"] 
}

This document contains all the information necessary for an Authorization Server to automatically register an OAuth Client application just through knowing the client_id .

How do I use this in FedCM?

For now, FedCM is still being designed, and there’s a number of open issues to properly support OAuth/OIDC and Client ID Metadata Documents (e.g., allowing type any).

So it’s not currently possible within released implementations, however, Aaron has done up some examples that show this working with pre-releases.

What’s next?

We’ve several areas of the internet draft where we still need to document expected functionality or behaviors, and we need to resolve the cacheability of Client ID Metadata Documents (such that Authorization Servers don’t need to continuously request a fresh copy of the document).

We also need to have a good developer experience for local development, which is likely to take the shape of a small service which produces Client ID Metadata Documents on a public URL for localhost.

Once those are resolved, it’ll go through the standard IETF internet draft and RFC process. We were targeting IETF 121 in Dublin, but we’ve both been busy so may not make that in time, but we will still be talking about it there.