lnurl-auth explained

You may have seen the lnurl-auth spec or heard about it, but might not know how it works or what is its relationship with other lnurl protocols. This document attempts to solve that.

Relationship between lnurl-auth and other lnurl protocols

First, what is the relationship of lnurl-auth with other lnurl protocols? The answer is none, except the fact that they all share the lnurl format for specifying https URLs.

In fact, lnurl-auth is very unique in the sense that it doesn’t even need a Lightning wallet to work, it is a standalone authentication protocol that can work anywhere.

How does it work

Now, how does it work? The basic idea is that each wallet has a seed, which is a random value (you may think of the BIP39 seed words, for example). Usually from that seed different keys are derived, each of these yielding a Bitcoin address, and also from that same seed may come the keys used to generate and manage Lightning channels.

What lnurl-auth does is to generate a new key from that seed, and from that a new key for each service (identified by its domain) you try to authenticate with.

lnurl-auth per-service key derivation illustrated

That way, you effectively have a new identity for each website. Two different services cannot associate your identities.

The flow goes like this: When you visit a website, the website presents you with a QR code containing a callback URL and a challenge. The challenge should be a random value.

lnurl-auth services issuing challenges

When your wallet scans or opens that QR code it uses the domain in the callback URL plus the main lnurl-auth key to derive a key specific for that website, uses that key to sign the challenge and then sends both the public key specific for that for that website plus the signed challenge to the specified URL.

lnurl-auth services receiving signatures from wallet

When the service receives the public key it checks it against the challenge signature and start a session for that user. The user is then identified only by its public key. If the service wants it can, of course, request more details from the user, associate it with an internal id or username, it is free to do anything. lnurl-auth’s goals end here: no passwords, maximum possible privacy.


This article on Nostr