FEP-61cf: The OpenWebAuth Protocol


This is a discussion thread for the proposed FEP-61cf: The OpenWebAuth Protocol.
Please use this thread to discuss the proposed FEP and any potential problems
or improvements that can be addressed.


OpenWebAuth is the “single sign-on” mechanism used by Hubzilla, (streams) and other related projects. It allows a browser-based user to log in to services across the Fediverse using a single identity. Once logged in, they can be recognised by other OpenWebAuth-compatible services, without third-party cookies and often without any explicit user interaction.

This document aims to describe the existing protocol in detail as an aid to implementers, evaluators, and anyone who wants to understand its operation.

This draft is based on reverse-engineering the existing implementations and is focused on the minimal requirements for basic interoperability in an ActivityPub network. OpenWebAuth can also work with other protocols such as Zot6 and Nomad but these are not considered here.


This FEP has been updated in response to the discussion on Hubzilla.

Changes in this revision:

  • Expanded the second paragraph to make it more explicit that this is a description of existing practice.

  • Changed the terminology to use “home instance” and “target instance”. Mentioned that these are equivalent to the terms “IdP” and “RP” used by other authentication protocols.

  • Mentioned that the home instance has a chance to apply policies such as requiring the user’s explicit consent.

  • Clarified that public keys can be discovered in a variety of ways but that this document focuses on using ActivityPub for this purpose.

  • Added a note on the purpose of the X-Open-Web-Auth header field.

  • Mentioned that unused tokens are deleted after a timeout.

  • Other miscellaneous adjustments based on review comments.

1 Like

Hello! I’m digging into FEPs and saw this one. I think it could solve a lot of issues.

I would love to implement this but am concerned about tying a SSO feature tightly to a hard coded generic path like /magic, which would prevent a website from putting other resources on this path. I think it would be much better to choose a path that is: 1) more clearly linked to OpenWebAuth, and 2) less likely to result in collisions with a normal CMS.

I’m going to humbly suggest something like /.well-known/open-web-auth which works alongside with other hard-coded URLs and should not conflict with other paths on a server.


This may also be related to

1 Like

Firstly - I agree and this is near to the top of my list of things I’d propose changing. The example of “https://my-hobbies.mysite.example/magic” is perhaps a bit contrived, but it’s exactly the kind of thing which a site owner should be able to do.

Streams advertises this endpoint in the webfinger response, which seems like a reasonable approach. I don’t think anybody checks for this, though. All the code I’ve seen hard-codes the endpoint name.

I think this can be changed in a backwards-compatible way as follows:

  • Patch Hubzilla to advertise this endpoint via webfinger too.
  • Patch both Hubzilla and Streams to check the webfinger response for this endpoint and fall back on the existing hard-coded “/magic” if it’s not found.
  • Update the FEP to describe this webfinger lookup.

I think this will work in the sense that all the existing Hubzilla and Streams installs will still be able to talk to each other. Older installs won’t interoperate with anyone who tries to use this feature to move the endpoint, but I think that’s unavoidable.

Secondly - if you try to implement this I’d love to hear your feedback. The main goal of this FEP is to make it possible to analyse or implement this protocol without having to rely on reading unfamiliar source code. I don’t think anybody’s tried to do this yet, so if there’s anything you find tricky or unclear, there’s a good chance the document can be improved.

1 Like

I thought FEP-d8c2 was more about the C2S case, where a client app needs to authenticate itself to a server. I don’t think OWA has much to do with this, since it’s fundamentally browser-based.

It seems to be possible to get the same functionality as OWA using a combination of OIDC Discovery and OIDC Dynamic Client Registration. This would have the advantage of using widely known protocols - but also the disadvantage of not actually being implemented anywhere.

1 Like

This is fantastic to see! We could also advertise OAuth 2.0 authorization server metadata endpoints through webfinger responses (OIDC can already theoretically support this)

1 Like

So OIDC Discovery and OIDC Dynamic Client Registration are based on, and very similar to, OAuth 2.0 authorization server metadata (RFC 8414) and OAuth 2.0 Dynamic Client Registration Protocol (RFC 7591)

The Mastodon /api/v1/apps endpoint kind of works like a Dynamic Client Registration endpoint, however, isn’t strictly compatible (there’s a bunch of quirks). I do want to get proper Dynamic Client Registration into Mastodon though, removing the need for this custom endpoint, and actually implementing RFC 7591.


Yeah, that sounds reasonable. Since I’m not on Hubzilla or Streams, I’d be in favor of “just update the FEP first, and declare the existing implementations close-but-not-quite-compliant…” but I know that’s probably a minefield that you probably shouldn’t go down.

For those of us looking at implementing this, is it possible to at least document how Streams uses webfinger to advertize this endpoint? That would give me something to build against while we wait for other implementations to catch up :slight_smile:

1 Like

I’ve added this (and also a reference to the recent report on HTTP signatures).

1 Like

Issuer Discovery is based on webfinger, and I even got this working (in a really hacky PoC sense). I couldn’t find anything else to test it against, though. :frowning:


I’m trying to make sense of the spec, and one thing I’m curious about is how you are supposed to handle permissions, as you might wanna restrict what the authenticated server can do. Are there any recommendations there?

I’m also curious, in which scenarios would you want to use OpenWebAuth, and in which case would you want to use OIDC?


Nobody’s answered so I’ll have a go - but please realise that I’m not an expert on this - I’m just the guy who wrote it up.

It’s common to make a distinction between authentication - who a user is - and authorization - what they are allowed to do.

OpenWebAuth only offers authentication. It says nothing about authorization. This question is up to the designer who makes use of it.

Well this is an area I think would benefit from some broader discussion because they both have their pros and cons.

OIDC offers a wide range of possible “flows” which make it a lot more broadly applicable, such as for phone apps. OWA is entirely browser based.

I imagine that OIDC has had a lot more scrutiny from security experts (just a guess - I have no direct evidence for this).

On the other hand, OWA is much simpler, and it is already implemented on the Fediverse (by the Hubzilla / Streams family of projects).


Great, thanks for the response!

I also notice there is FEP-ae97, which defines how to let clients sign requests, which uses something called DID under the hood.

How interoperable are these standards, could you leverage these together?

depends how many cans of worms you can stand to have open at once :sweat_smile:

the short answer is that DIDs are just a translation layer for combining keys and signing mechanisms across authN/authZ frameworks-- a small tool among the many you need for tackling a big problem. making DIDs work with OIDC and/or with OWA is more work and in some senses introduces fragile redundancy in exchange for being able to federate/interoperate more widely, and it’s definitely possible technologically, but if you’re not experienced with super finicky multi-system authN/Z work, the timelines/level of effort could get out of hand! recommended for well-funded teams, not for individual hackers, i’d say.

1 Like

OpenWebAuth seems to be redundant with FEP-ae97, because if users control their secret keys, they can authenticate themselves.

1 Like

Wouldn’t OpenWebAuth give you further options for authorization? For example the token you send back could be with limited capabilities, so the authenticated server can then publish/view items in the inbox/outbox.

With FEP-ae97 you would always create a new actor right? So if I authenticate myself to a server, it sets up a new inbox/outbox for the user? The inbox/outbox wouldn’t be linked.

Some combinations for OWA and FEP-ae97 could make sense, but I’d probably use a different approach to SSO: FEP-ae97 + FEP-ef61. In such combination actors on different servers will be instances of the same actor because their IDs will be identical (derived from the same key).


That makes a lot of sense, thanks for clarifying. Now the dots are connecting.

1 Like