Fediverse OpenWebAuth (FEP-61cf) — Complete Reference

Overview

OpenWebAuth (OWA) is a federated remote authentication protocol that enables browser-based single sign-on across Fediverse services. A user logged in at their home instance can be automatically recognized by other compatible servers without creating local accounts, without third-party cookies, and often without any explicit user interaction.

FEP-61cf (authored by FenTiger, received 2024-02-06, status DRAFT) formally documents the protocol, which was written based on reverse-engineering existing implementations in Hubzilla and (streams).

OpenWebAuth is also known as Magic Auth, Magic Sign On, Remote Authentication, or rMagic. The name "Magic Auth" persists informally because "of how seamless the experience is."

The Problem: No Identity Across Servers

In the current Fediverse, when you browse to a different server, that server has no idea who you are. This causes several painful problems:

1. Private content is inaccessible — if someone on

   podunk.edu

   shares a private video only with

   bob@example.com

   , Bob cannot view it by visiting

   podunk.edu

   . The server doesn't know he's Bob.

2. Remote profiles are limited — when jumping from instance to instance, users lose their identity. They can't interact natively with content.

3. No cross-server permissions — fine-grained access controls (e.g., "only Alice and Bob can see this photo") only work when the server can identify the viewer.

4. No wall-to-wall posting — users can't post directly on someone else's wall or profile on a remote server.

OpenWebAuth solves this: "You can jump from one part of the Fediverse to another, and your permissions will be granted automatically. Anything you were given permission to access unlocks and becomes visible on the page."

Authentication vs Authorization

OpenWebAuth is strictly an authentication protocol — it proves who you are. It is NOT an authorization protocol.

"OpenWebAuth allows

someone@example.social

to log into

example.com

as

someone@example.social

, and

example.com

determines what

someone@example.social

can do on

example.com

. But

example.com

cannot impersonate

someone@example.social

."

The target instance decides locally what an authenticated remote user can do. OpenWebAuth provides the identity; the target provides the permissions.

This is the fundamental distinction from OAuth 2.0, which is an authorization framework — it grants permissions for a client to act on behalf of a user.

Architecture

The protocol has two participants:

• Home instance — hosts the user's identity. Equivalent to the Identity Provider (IdP) in SAML and OpenID Connect. Only the home instance has access to the user's private key.
• Target instance — allows remote users to log in. Equivalent to the Relying Party (RP) in SAML and OpenID Connect. Only uses public keys.

Each user is identified by a public/private key pair. The protocol relies on ActivityPub actor documents for public key discovery.

Login Flow Initiation

Two mechanisms trigger the authentication:

1. Login form — user visits the target instance and submits their Fediverse ID (e.g.,

   alice@example.social

   ) via a login form

2. zid=

   parameter — user follows a link containing

   ?zid=alice@example.social

   , which auto-triggers authentication

The

zid=

Security note: the

zid=

The 5-Step Protocol Handshake

Step 1: Target Redirects to Home Instance

The target instance discovers the home instance's redirect endpoint via WebFinger:

GET /.well-known/webfinger?resource=acct:alice@home.example

Look for a link with

rel="http://purl.org/openwebauth/v1#redirect"

/magic

Construct the redirect URL:

https://home.example/magic?owa=1&bdest=<hex-encoded-destination-URL>

The

bdest

Origin validation: the target MUST validate that the redirect hostname matches the claimed identity's domain to prevent open redirector abuse.

Step 2: Home Instance Requests a Token

The home instance's

/magic

1. Verifies the user has a valid session cookie (i.e., is logged in)
2. Decodes the

   bdest

   URL from hex
3. Performs a WebFinger lookup for the target's token endpoint, seeking

   rel="http://purl.org/openwebauth/v1"

4. Sends an HTTP-Signature-signed request to the token endpoint
5. Includes an

   X-Open-Web-Auth

   header with a random string for additional entropy
6. If WebFinger discovery fails, returns an HTTP error (preventing open redirection — never redirects on failure)

The signed request uses an

Authorization

Signature

Step 3: Target Instance Provides Encrypted Token

The target instance's token endpoint:

1. Extracts the

   keyId

   from the signed request's

   Authorization

   header
2. Fetches the actor record and public key via the

   keyId

   URL
3. Verifies the HTTP signature
4. Generates a URL-safe random token string
5. Stores the token locally (with a short expiry, typically minutes)
6. Encrypts the token using the actor's public key with RSA PKCS #1 v1.5
7. Encodes the encrypted result as URL-safe Base64 without padding
8. Returns JSON:

{
  "success": true,
  "encrypted_token": "<base64-encoded-encrypted-token>"
}

The token endpoint accepts both GET and POST requests. Some implementations send POST with random bodies.

Step 4: Home Instance Decrypts and Redirects

The home instance:

1. Decodes the JSON response
2. Verifies

   "success": true

3. Decrypts the Base64-encoded token using the actor's private key
4. Redirects the user's browser to:

<bdest>?owt=<decrypted-token>

Step 5: Target Instance Validates Token and Logs In

The target instance:

1. Extracts the

   owt

   query parameter
2. Matches it against the token stored in Step 3
3. If valid, logs the user in as the remote identity
4. Immediately deletes the token — single-use enforcement

After this step, the target instance sets a session cookie for the authenticated remote user. Subsequent page loads on the target don't require repeating the handshake.

WebFinger Link Relations

The protocol defines two custom WebFinger link relations:

http://purl.org/openwebauth/v1#redirect

http://purl.org/openwebauth/v1

If the redirect endpoint is not discoverable via WebFinger, implementations fall back to the hardcoded

/magic

Key Usage Summary

Only the home instance ever touches the private key. The target instance operates exclusively with public keys.

Security Considerations

Information Leakage

The home instance learns which target instances the user visits (because it performs the redirect and token exchange on the user's behalf). Implementations should consider consent screens or privacy policies restricting automatic authentication.

Token Security

• Tokens are single-use — deleted immediately after validation
• Tokens expire within minutes — prevents storage exhaustion (DoS) from unused tokens
• Tokens are encrypted with the actor's public key — only the home instance (with the private key) can decrypt them

Impersonation Prevention

The target instance MUST trust the

owt=

zid=

zid

Additionally, the target validates that the token endpoint's origin matches the

bdest

Open Redirection Mitigations

Three layers of defense:

1. First redirect (target → home): validates that the hostname matches the claimed identity
2. Second redirect (home → target): validates that the token endpoint origin matches the

   bdest

   origin
3. Failed discovery: returns HTTP errors rather than redirecting — never silently redirects on failure

The

zid=

Attack Surface

Links containing

zid=

History: From Magic Auth to OpenWebAuth

Magic Auth in Mistpark (2010)

Mike Macgirvin created Magic Auth as part of Mistpark in 2010 — the project that would later become Friendica. Magic Auth enabled federated single sign-on across decentralized nodes but was tightly coupled to the Zot protocol and "somewhat limited" in Friendica.

Integration into Hubzilla via Zot

As Mistpark evolved through Friendika → Friendica → Red Matrix → Hubzilla, Magic Auth remained embedded in the Zot protocol. In Hubzilla, it became central to features like fine-grained access control, private content sharing, and wall-to-wall posting — all of which depend on knowing who is visiting the server.

Standalone OpenWebAuth (October 2017)

Magic Auth was "separated from Zot and made into its own protocol called OpenWebAuth to facilitate adoption by other platforms." Released in Hubzilla 2.8. The key insight: authentication and communication are orthogonal problems. By extracting auth into a standalone spec, non-Zot projects could adopt it without the full Zot stack.

Zotlabs Era (2018-2022)

Mike Macgirvin launched Zotlabs to advance Zot6 and integrate OpenWebAuth. Multiple experimental projects (Osada, Zap, Roadhouse) eventually converged into the (streams) repository (October 2021).

Broader Adoption (2023+)

• Friendica became the first non-Zot-family project to implement OpenWebAuth (~2023)
• Forte (by benpate) implemented OWA as an alternative to Activity Intents for wall-to-wall posting
• FedIAM implemented the protocol
• FEP-61cf submitted February 2024, formally documenting the protocol

OpenWebAuth vs OAuth 2.0 / OIDC

The "not invented here" criticism (erlend_sh on SocialHub) argued existing OAuth/OIDC standards should be used instead. FenTiger's response: OWA and OAuth solve different problems; OWA is simpler, already deployed, and OIDC Discovery + Dynamic Client Registration have no existing Fediverse implementations.

Implementation Status

Identity Providers (Publishing OWA)

Relying Parties (Accepting OWA)

The Mastodon Barrier

Mastodon issue #7643 (opened May 2018, still open) requests OpenWebAuth support. The fundamental barrier: implementing server-side OWA requires "the Mastodon service to have the concept of authorization of users without an account on the Mastodon server." This is an architectural change, not just a protocol implementation. A partial PR (#25012) was created for client-side functionality only.

Implementation Guidance

Publishing as an Identity Provider (Home Instance)

1. Advertise your redirect endpoint via WebFinger with

   rel="http://purl.org/openwebauth/v1#redirect"

2. Implement the redirect endpoint (traditionally

   /magic

   ):
   • Check the user's session cookie
   • Decode the

     bdest

     parameter from hex
   • Discover the target's token endpoint via WebFinger
   • Send an HTTP-Signature-signed request with

     X-Open-Web-Auth

     header
   • Decrypt the returned token with the actor's private key
   • Redirect the browser to

     bdest?owt=<token>

3. On failure at any step, return an HTTP error — never redirect

Accepting as a Relying Party (Target Instance)

1. Advertise your token endpoint via WebFinger with

   rel="http://purl.org/openwebauth/v1"

2. Implement the token endpoint:
   • Extract

     keyId

     from the

     Authorization: Signature ...

     header
   • Fetch the actor's public key
   • Verify the HTTP signature
   • Generate a random token, store it locally with a short TTL
   • Encrypt with the actor's public key (RSA PKCS #1 v1.5)
   • Return

     {"success": true, "encrypted_token": "<base64>"}

3. On pages that accept

   owt=

   parameter:
   • Match the token against stored tokens
   • Log the user in as the remote identity
   • Delete the token immediately
4. Implement a login form or

   zid=

   parameter handling to trigger the flow
5. Decide what permissions authenticated remote users receive

Handling the

zid=

Parameter

Check for

zid=

zid

alice@home.example

Hardcoded Path Concerns

The

/magic

1. Always check WebFinger first for the redirect/token endpoints
2. Only fall back to

   /magic

   for backward compatibility with older Hubzilla/Streams instances
3. Consider using

   /.well-known/open-web-auth

   for new implementations (proposed by benpate but not yet standardized)

Known Issues and Open Questions

1. DRAFT status — FEP-61cf has not reached FINAL; the spec may change
2. Browser-only — no support for mobile apps, API clients, or desktop applications (unlike OAuth/OIDC)
3. Privacy concern — home instance learns every target the user visits; most implementations don't show consent screens
4. Mastodon architectural gap — supporting accountless remote users requires fundamental changes to Mastodon's data model
5. Hardcoded

   /magic

   path — conflicts with CMS installations; WebFinger-first discovery should become primary
6. Missing spec details — cookie-based login verification and activity attribution to home instance actors are implementation requirements not fully documented in the FEP
7. RSA-only encryption — the token encryption uses RSA PKCS #1 v1.5; no support for Ed25519 or other key types commonly used in newer ActivityPub implementations
8. Redundancy debate — silverpill argued that self-controlled keys (FEP-ae97) could make OWA redundant; the community has not resolved this