For a while now I've been meaning to take a look at #
OpenWebAuth, but I've been a bit daunted by the reverse engineering effort that it would take.
This changed when I came across this page:
https://hz.eenoog.org/wiki/pascal/Fediverse(28)20(29)OpenWebAuth(28)20(29)support/HomeThis links to three PRs adding OpenWebAuth to Mastodon and PixelFed. Reading these PRs saved me a lot of time by clearly highlighting the areas of the code which I needed to study. With these and a bit of grepping I've been able to implement most of #
OpenWebAuth locally, so that my toy instance can now log me into Hubzilla, and I can very nearly allow Hubzilla users to log in to me, too.
Here's a quick writeup of how it works, in the "happy case". I'm wondering if it's worth polishing this further and making it into a #
FEP.
- The OpenWebAuth flow can begin in one of two ways:
(a) The user visits the target instance and sees a login screen. They type their Fediverse ID into a form field and click "Login".
(b) The user follows a link to the target instance. This link has a query parameter, zid=, which specifies the user's Fediverse ID.
Either way, the target instance has learned the user's ID, but has not verified it yet.
- The target instance constructs a URL of the form
https://home-instance.example/magic?owa=1&bdest=
The parts of this URL are:
Scheme: Must be HTTPS
Hostname: The same as the hostname portion of the user's ID
Path: Must be
/magic Query parameters:
owa: must be set to 1
bdest: The URL that the user is trying to visit. This is encoded as UTF-8 and then converted to a hexadecimal string.
The user's browser is redirected to this URL.
- The
/magic endpoint at the user's home instance decodes the bdest destination URL. It performs a webfinger lookup on the root URL of the destination site and looks for a link with rel set to http://purl.org/openwebauth/v1. This identifies the target instance's token endpoint.
The home instance constructs and issues a signed HTTPS request to this endpoint. This request must have an
Authorization header starting with the word
Signature followed by the encoded HTTP signature. The
keyId property of the signature points to the public key in the user's actor record, just as for ActivityPub signed requests.
- The target instance's "
token" endpoint extracts the "keyId", fetches the actor record, extracts the public key and verifies the signature.
On success, it generates an URL-safe random string to use as a token. This token is stored locally, associated with the actor who signed the message. The token is also encrypted using the actor's public key and the RSA PKCS #1 v1.5 encryption scheme. The encrypted result is encoded as URL-safe Base64 with no '=' padding bytes.
Next it constructs the following JSON object in response:
{
"success": true,
"encrypted_token":
}
On failure it can also return a result with
success set to false.
- The signed request issued by the
/magic endpoint completes. The home instance decodes the JSON response and verifies that success is true. Next it decodes the Base64-encoded encrypted token and decrypts it using the actor's private key.
If successful, it takes the original
bdest destination URL, adds the query parameter:
owt=, and redirects the user's browser to it.
- The user arrives at their destination URL. The target instance sees the
owt= query parameter and checks its local storage for the token which it saved in step 4.
If found, this token contains the user's verified identity, and the target instance logs them in, overriding any existing login they may have. The token is also deleted from local storage so that it cannot be redeemed more than once.
