DPoP
DPoP (Demonstrating Proof of Possession, RFC 9449) ties a token to a key pair. The client sends, with every request, a short signed proof made with the private key, and the token names the public key it belongs to. Whoever copies the token without the key cannot use it.
SeekAuth uses DPoP for the clients that cannot keep a secret: single-page apps and native apps. Their private key is made in the browser and cannot be read out of it, so a token lifted from memory, a log or an extension is of no use elsewhere.
Which tokens are bound
Section titled “Which tokens are bound”| Client | At /token |
Its tokens |
|---|---|---|
| Single-page app, native app (public, no secret) | A proof is required with every grant. Without one: invalid_dpop_proof “public clients must send a DPoP proof”. |
Bound: token_type DPoP, the access token carries cnf.jkt, and the refresh token only works with a proof from the same key. |
| Web client (confidential, with a secret) | A proof is optional. | Bound only if a proof was sent; otherwise Bearer. The Rust WebClient sends none. |
| Machine client | Not used. | Never bound: Bearer. |
A refresh keeps the binding of the token it refreshes. cnf.jkt is the key’s RFC 7638 thumbprint.
What a proof is
Section titled “What a proof is”A proof is a JWT in the DPoP header, made for one request:
| Part | Rule |
|---|---|
Header typ |
dpop+jwt |
Header alg |
ES256, the only algorithm accepted |
Header jwk |
The public key: EC, curve P-256 |
htm |
The request’s method, exactly (POST) |
htu |
The request’s URL without query string or fragment (scheme and host compared case-insensitively) |
iat |
Now: accepted from 300 seconds in the past to 60 seconds in the future |
jti |
A unique id, 1 to 128 characters |
ath |
With an access token: the base64url SHA-256 of the token. Not at /token, which takes no access token. |
A request carries exactly one DPoP header, and the token goes in Authorization: DPoP <access token>. A bound token sent as Authorization: Bearer is refused, and so is an unbound token sent with the DPoP scheme.
Each proof works once. SeekAuth remembers every proof it accepted for as long as it could still be accepted (its iat plus six minutes), across all its servers, and refuses one it has seen. SeekAuth does not use server nonces (DPoP-Nonce): a proof needs no round trip first.
In the browser
Section titled “In the browser”The SDKs do all of this for you. auth-js makes a P-256 key pair once, with WebCrypto, as non-extractable: the page can sign with it but never read the private key, not even its own code. It is kept in IndexedDB (key dpop-key:{issuer}|{clientId}) and shared by the app’s tabs. The SDK sends a proof:
- with every
/tokencall (logins and refreshes); - with
/userinfo; - with every request made through
authFetch, so your API receives the token and a fresh proof for that very request; - with the first step of a step-up.
If the key is lost (site data cleared), so is the session: the refresh token only works with that key, and the user logs in again.
In your API
Section titled “In your API”An API that accepts a browser’s tokens must check the proof as well as the token. With the Rust SDK, the AuthUser extractor does it: for a token with cnf it requires the DPoP scheme, checks the proof against the request’s method and URL, the token’s ath and the time, requires the proof’s key to be the one in cnf.jkt, and refuses a proof it has seen. Set the URL your API is reached at with with_base_url when it runs behind a proxy; see Calling your API.
The SDK remembers the proofs it has seen in the process (up to 100,000). An API that runs several replicas should also share what it saw, for example a SET NX in Redis under the key’s thumbprint and the proof’s jti, for as long as the proof could be accepted.
With another library, check the proof as the table above says, then that its key’s thumbprint equals the token’s cnf.jkt.
Errors
Section titled “Errors”| Where | Answer |
|---|---|
SeekAuth’s own endpoints (/token, /userinfo, /session-ticket) |
400, { "error": "invalid_dpop_proof", "error_description": "…" }, with WWW-Authenticate: DPoP error="invalid_dpop_proof", algs="ES256". |
| The account API | 401 token_invalid: every failure to verify the token, its proof included. |
An API using auth-client |
401, { "code": "invalid_dpop_proof", "message": "…" }, with WWW-Authenticate: DPoP error="invalid_dpop_proof". |
The descriptions say which rule failed: a stale proof, the wrong method or URL, a key that does not match the token, a replayed proof. A proof that fails at a refresh does not use the refresh token up.
Testing code that checks proofs
Section titled “Testing code that checks proofs”The Rust crate’s testing feature has DpopKey, which makes keys and signs proofs (proof(method, url, iat, access_token)) for the tests of an API. See auth-client.