chadtmiller.com/monolith
An atproto PDS
OAuth: web, native and confidential clients
OAUTH.md says how the server is the authorization server for
its accounts, with loopback clients. This page adds the clients whose
client_id is an https:// URL: discoverable clients, whose metadata
the server fetches from that URL (atproto/oauth.md, "Client ID Metadata
Document"). They are web or native clients, and public or confidential:
a confidential client authenticates itself with a JWT signed by a key it
publishes (private_key_jwt, RFC 7523). Confidential clients may sign an
account in silently, without the authorization page, once the account has
approved them.
Everything OAUTH.md says holds for these clients too, where this page
does not say otherwise: what this page adds to a step of OAUTH.md's
checks, it says where in that order it comes.
Sources
This section is informative.
| File | Is | Licence |
|---|---|---|
rfc/draft-client-id-metadata-document.txt | OAuth Client ID Metadata Document (draft 00) | IETF Trust |
rfc/rfc7523.txt | JWT profile for OAuth client authentication | IETF Trust |
and those OAUTH.md lists, atproto/oauth.md above all ("Clients",
"Confidential Client Authentication", "Tokens and Session Lifetime",
"Authorization Interface").
Client IDs
A local name is a domain name with fewer than two labels, or whose last
label is test, local, localhost, invalid or example, in any case:
names no client on the internet can own.
A client_id that begins with https:// is a discoverable client's, and is
taken if it is a URL (as the WHATWG URL standard parses it) with:
- no user or password, and no fragment (no
#); - a path that is not
/and does not end in/, written as the parser would write it: no.or..segments, nothing it would percent-encode; - a host that is a domain name, not an IP address, not
localhost, with at least two labels, and not ending in.local; - no port (
atproto/oauth.md: "there must not be a port number"); - a host that is not a local name.
A failure of the last is 400 invalid_client_id; of any other, 400 invalid_client_metadata. A query is allowed, and is part of the client ID.
A client_id that is neither a loopback one (OAUTH.md) nor one of these is
400 invalid_client_metadata, as OAUTH.md says.
The document
Fetching it. The client's metadata is the JSON document at its
client_id: the server sends GET <client_id>, with Accept: application/json, and takes the answer only if:
- it is not a redirect: the server follows none;
- its status is
200; - its
Content-Typeisapplication/json, compared without case, with any parameters (; charset=utf-8) ignored; - its body is at most 512 KiB (524 288 bytes), and is a JSON object;
- it came within 10 seconds.
Any other answer, or no answer, is 400 invalid_client_metadata. The
server fetches only over https, and through the one guard every request it
sends to a URL others name goes through (PROXY.md, "SSRF protection"):
only from hosts that resolve to public unicast addresses
(draft-client-id-metadata-document §6.5, atproto/oauth.md "Security
Considerations"), unless PDS_DISABLE_SSRF_PROTECTION=true, for
development and testing only, lets it fetch from any address.
Keeping it. A document the server took, and found good (below), is kept
for 10 minutes from when it was fetched, by its URL, and used for every
request naming that client in that time: the server does not fetch it
again, whatever the URL now serves. A document refused is not kept: the
next request fetches it again (draft-client-id-metadata-document §4.4).
Kept documents and JWKS are in memory only: a restart forgets them all.
What it must say. The fields the server knows, each of the type given
(else 400 invalid_client_metadata); any other field is ignored:
| Field | Type | If absent |
|---|---|---|
client_id | a non-empty string | refused |
redirect_uris | a non-empty array of redirect URIs (below) | refused |
response_types | a non-empty array, each one of code, token, none, code id_token token, code id_token, code token, id_token token, id_token | ["code"] |
grant_types | a non-empty array, each one of authorization_code, implicit, refresh_token, password, client_credentials, urn:ietf:params:oauth:grant-type:jwt-bearer, urn:ietf:params:oauth:grant-type:saml2-bearer | ["authorization_code"] |
scope | a scope string, as OAUTH.md defines one | refused |
token_endpoint_auth_method | one of client_secret_basic, client_secret_jwt, client_secret_post, none, private_key_jwt, self_signed_tls_client_auth, tls_client_auth | client_secret_basic |
token_endpoint_auth_signing_alg | a string | |
jwks | an object whose keys is an array | |
jwks_uri | an https URL (as a redirect URI's, below) | |
application_type | web or native | web |
subject_type | public or pairwise | public |
client_name | a string | |
client_uri | an https URL (as a redirect URI's) | |
logo_uri, tos_uri, policy_uri | an https URL (as a redirect URI's) | |
contacts | an array of email addresses | |
dpop_bound_access_tokens | a boolean | refused |
authorization_signed_response_alg | a string | RS256 |
request_object_signing_alg, authorization_encrypted_response_alg | a string | |
require_auth_time, tls_client_certificate_bound_access_tokens | a boolean | |
authorization_encrypted_response_enc | A128CBC-HS256 | |
authorization_details_types | an array of strings | |
default_max_age | a number | |
userinfo_signed_response_alg, userinfo_encrypted_response_alg, id_token_signed_response_alg | a string |
A redirect URI, in redirect_uris, is one of these, else the document
is 400 invalid_client_metadata:
- an https URL: beginning
https://, a URL, its host notlocalhost,127.0.0.1or[::1]; a host that is a domain name has at least two labels and does not end in.local(an IP address is a host too); - a loopback URL: beginning
http://, a URL, its host127.0.0.1or[::1]; - a private-use URI (RFC 8252 §7.1): a scheme of two or more
dot-separated labels (
net.example.app), a colon, then a single/and a path: no//, user, password, host or port. The scheme, its labels read backwards, must not be a local name.
jwks_uri, client_uri, logo_uri, tos_uri and policy_uri are https
URLs as above (atproto/oauth.md: "Only https: URIs are allowed", and a
jwks_uri "must be a valid fully qualified URL with https:// scheme").
Then, in this order, the first that fails refusing the document with 400 invalid_client_metadata, but invalid_redirect_uri where said:
- Not both
jwksandjwks_uri. - None of
default_max_age,userinfo_signed_response_alg,id_token_signed_response_alg,userinfo_encrypted_response_alg. client_uri's host not a local name.scopepresent, withatproto, and no scope token twice.- No grant type twice; each one
authorization_codeorrefresh_token. client_id, if present, equal to the client ID, character for character (draft-client-id-metadata-document§4.1).subject_typepublic.token_endpoint_auth_methodnone, with notoken_endpoint_auth_signing_alg; orprivate_key_jwt, withjwksorjwks_uri, at least one key injwksif it is given (keys below), and atoken_endpoint_auth_signing_algthat is notnone.- No
authorization_encrypted_response_enc;tls_client_certificate_bound_access_tokensnottrue. dpop_bound_access_tokenstrue.response_typeswithcode;grant_typeswithauthorization_code.- No
authorization_details_typesbut an empty array. application_typenativeonly withtoken_endpoint_auth_methodnone(RFC 8252 §8.4: native apps are public clients).- Each redirect URI: no user or password; a loopback URL only for a
native client; an https URL whose host is a local name never;
a private-use URI only for a native client. Each failure
invalid_redirect_uri. client_idpresent.client_uri, if present, on the client ID's origin, and its path the client ID's or a parent of it (/or the path's directories).- Each private-use URI's scheme the client ID's host, its labels read
backwards (
net.example.app:forhttps://app.example.net/…):invalid_redirect_uri. Each https URL of a native client on the client ID's origin (atproto/oauth.md, "Request Fields"):invalid_redirect_uri.
A web client is one whose application_type is web; a native client, one
whose is native.
The client's keys. A confidential client's keys are those of its
jwks, or of the JWKS at its jwks_uri, that are public keys: a JWK with a
kid, of kty EC (crv P-256, P-384, P-521 or secp256k1, with
x and y), RSA (with n and e) or OKP (crv Ed25519 or Ed448,
with x), with no private member (d, p, q, dp, dq, qi, oth,
k), use, if given, sig or enc, and key_ops, if given, a non-empty
list, without repeats, of verify, encrypt and wrapKey, consistent with
use (verify with sig; encrypt and wrapKey with enc). Other
entries of keys are ignored.
A JWKS at jwks_uri is fetched as the document is, but its
Content-Type, if it has one, must be application/json (it may have none);
it must be a JSON object whose keys is an array; and it is kept 10
minutes, by its URL, apart from the document. A jwks_uri is fetched
whenever its client's document is taken or used, whatever the client's
token_endpoint_auth_method. A JWKS that cannot be had is 400 invalid_client_metadata.
Where it is checked. A discoverable client is loaded wherever OAUTH.md
checks the client: PAR's step 5, the token endpoint's step 5, the
revocation endpoint (where a client that cannot be loaded changes nothing),
the authorization page's step 2, and consent. Loading it is: the client
ID, the document (fetched or kept), the checks above, then the JWKS (fetched
or kept), each failure answering as said, but at consent.
At consent (OAUTH.md, "The API"), the client is loaded, by the
request's client_id, after check 3 (the account signed in) and before
check 4. If it cannot be loaded, consent answers as for a request that
cannot be approved: 200 {url}, the redirect carrying error, and the
request ended. The error is server_error if the document or JWKS could
not be had (no answer, or one refused under "Fetching it") or is not of
the form the field table and the redirect URI forms give (a JWKS: an
object whose keys is an array); and invalid_request if the document
fails one of the numbered checks 1 to 17, invalid_redirect_uri ones too.
A document loaded at consent is not held to the request: a request whose
redirect URI or scope the document no longer has is approved as PAR took
it.
Note: the specs leave all this open; it is what the reference answers.
What the page shows. __authorizeData.clientMetadata is the document as
the server took it: the fields of the table it has, with the defaults of
those it lacks, and jwks, if given, with only the client's keys, each with
only its members named above (and alg, kid, use, key_ops, x5c,
x5t, x5t#S256, x5u, ext, iat, exp, nbf, revoked, as given).
clientTrusted and clientFirstParty are false: the server trusts no
client.
Requests
Redirect URIs. A request's redirect_uri matches one of the
document's as OAUTH.md says: equal, character for character, or, if both
are loopback URLs and the registered one has no port, equal but for the
port. OAUTH.md's forms for a redirect_uri (PAR's step 3) hold too.
Grant types. The token endpoint's step 7 also requires a grant_type
the client's grant_types has: else 400 invalid_grant. A client without
refresh_token among them is given no refresh token: the token answer has
no refresh_token.
Prompt. PAR's step 13 (no prompt=none), and the rule that what is
kept of a request's prompt is consent (or create), hold for public
clients, https ones too. A confidential client's request keeps its
prompt as given, or none.
Client authentication
A client whose token_endpoint_auth_method is private_key_jwt is
confidential, and authenticates every request to /oauth/par,
/oauth/token and /oauth/revoke (atproto/oauth.md, "Confidential
Client Authentication"; RFC 7523 §2.2, §3) with:
client_assertion_type:urn:ietf:params:oauth:client-assertion-type:jwt-bearer;client_assertion: a JWT, three dot-separated parts of base64url characters, each at least two characters, signed by one of the client's keys.
A public client's (none) requests are not authenticated: these
parameters, if it sends them, are ignored. A confidential client's are
checked, in this order:
- Both parameters, as above: else
400 invalid_request. - The assertion verifies, else
400 invalid_client:- its header's
algis one the server verifies (ES256at least), notnone, and itskidnames exactly one of the client's keys fit for thatalg(of itsktyand curve; whosealg, if given, is thatalg; whoseuse, if given, issig; whosekey_ops, if given, hasverify); and the signature is that key's; - its claims:
issandsubtheclient_id;audthe server's issuer, or an array with it;jtipresent;iata number, not after now and not more than 60 seconds before;exp, if present, a number after now;nbf, if present, a number not after now.
- its header's
- Its
jtinot used before by this client: else400 invalid_grant. Once an assertion passes 2, itsjtiis spent for this client, whatever the request then answers (single-use values, below).
RFC 7523 requires an exp; atproto/oauth.md asks only for iat and
jti, and its clients send no exp, so the server takes an assertion
without one. The server does not compare the assertion's alg with the
document's token_endpoint_auth_signing_alg, nor the client's keys with
the DPoP key: a DPoP proof may be signed with the client's own key.
Where. At PAR, after its step 5 loads the client; at the token
endpoint, after its step 6 (a DPoP proof present); at revocation, after
the DPoP proof is checked, where a failure answers 200 {} and changes
nothing, as any refused revocation does.
The key is the session's. The key that authenticated PAR, its kid,
alg and the key itself, is the request's, and then its session's
(atproto/oauth.md: sessions are bound to the client authentication key
used at the start):
- at the code grant, step 2 also requires the assertion's key to be the
request's: else
400 invalid_grant, and the code is spent (step 1); - at the refresh grant, step 3 also requires it to be the session's: else
400 invalid_grant, and the session ends; - revocation ends the session only if the assertion's key is the session's.
A refused authentication (1 to 3) leaves the code or session as it was. A key gone from the client's keys, once the server has fetched them again, cannot authenticate: the session cannot be refreshed.
Lifetimes. A confidential client's session ends 730 days after it
started, or 90 days after its last token answer, whichever comes first,
where a public client's ends two weeks after it started (OAUTH.md). Its
access tokens live as long as a public client's.
Silent sign-in
atproto/oauth.md ("Authorization Interface") lets a server approve a
confidential client's request without asking, once the account approved
the same scopes for the same client before. The server keeps, for each
account, the discoverable clients it has approved and every scope token it
approved each for: each consent (OAUTH.md) of a request of a
discoverable client adds that client and the request's scope, as narrowed.
Loopback clients are not kept: they cannot be told apart. A deactivation
with an OAuth token forgets them all (LIFECYCLE.md).
When the authorization page loads a request of a confidential client
(OAUTH.md's "Checks", after step 3), the server looks at the accounts
signed in on this device and remembered, but a taken-down one, as the page
lists them (LIFECYCLE.md), each of which:
- needs a sign-in if the request's
promptisloginor it signed in on this device more than seven days ago; - needs consent if the request's
promptisconsent, the account never approved this client, or the request's scope has a token the account has not approved for it.
Those that login_hint names (by DID or handle, as OAUTH.md's
selectedDid) and that are not deactivated are the hinted ones: a
deactivated account is never approved without asking, as the reference's
is not (probed: prompt=none with only it hinted is login_required).
Then, the first that applies:
prompt=select_accountand no account signed in: the request ends, and the browser is sent to the client witherror=account_selection_required.prompt=none: more than one hinted account,account_selection_required; none,login_required; one that needs a sign-in,login_required; one that needs consent,consent_required. Each ends the request and sends the browser to the client with that error. Otherwise the request is approved for that account, asconsentapproves one with noscope(but recording nothing), and the browser is sent to the client with itscode, at once.- No
prompt, alogin_hint, and exactly one hinted account, needing neither a sign-in nor consent: approved and sent with itscode, as in 2. - Otherwise, the page, as
OAUTH.mdsays, with these differences:promptModeis the request'sprompt, and absent when it has none;selectedDidis given only when thepromptis absent,loginorconsent; and an account'sloginRequiredistrueif it needs a sign-in.
The browser is sent to the client as OAUTH.md's "The redirect" sends it,
in the request's response_mode, with iss and state: a 303, or the
form_post page.
Single-use values and durability
OAUTH.md's single-use values gain a namespace:
| Namespace | Value | Kept for |
|---|---|---|
| client assertions | a confidential client's assertion jti, per client | 2 minutes |
Note: two minutes outlasts any assertion the server would take again: one more than 60 seconds old is refused at step 2.
As DURABILITY.md says of the rest, what the server answered survives it
being killed: the clients each account approved, and their scopes; the key
each request and session is bound to; spent assertion jtis, until their
time. Kept documents and JWKS do not survive, as said under "Keeping it".
The development fetch
| Variable | Is |
|---|---|
PDS_OAUTH_CLIENT_FETCH | for development and testing only: the origins whose client documents and JWKS are fetched from another base URL, as below |
PDS_OAUTH_CLIENT_FETCH is for development and testing only: a server
open to the internet must not set it. Unset, the server fetches client
documents and JWKS as above. Set, it is a comma-separated list of
<origin>=<base URL>, each origin https:// and a host, with no port or
path; each base URL http:// or https://, a host, an optional port, and
an optional path, with no trailing /:
PDS_OAUTH_CLIENT_FETCH=https://app.pds-harness.net=http://127.0.0.1:4100/server/app.pds-harness.net
A document or JWKS whose URL's origin is listed is fetched from the base
URL followed by the URL's path and query instead (here
https://app.pds-harness.net/c.json?x=1 from
http://127.0.0.1:4100/server/app.pds-harness.net/c.json?x=1), over http
if the base says so. Nothing else changes: the client ID is still the https
URL, the answer is held to the same rules, and the fetch goes through the
same guard, so a base on this machine or a private network is reached only
with PDS_DISABLE_SSRF_PROTECTION=true as well. A value that does not
parse stops the server at start.
Where the reference departs from the specs
The reference PDS does these, which the specs this page rests on say otherwise; the server follows the specs, and the harness does not compare them, but holds the server to this page:
| The reference | The spec | The server |
|---|---|---|
takes a document answered with any 2xx status, as 201 | atproto/oauth.md: the status must be 200 | 400 invalid_client_metadata |
takes token_endpoint_auth_signing_alg: "none" | atproto/oauth.md: none is never allowed | 400 invalid_client_metadata |
takes an http: jwks_uri, logo_uri, tos_uri or policy_uri on a loopback host | atproto/oauth.md: only https: | 400 invalid_client_metadata |
| takes a native client's https redirect URI on another origin | atproto/oauth.md: the same origin as the client_id | 400 invalid_redirect_uri |
The reference's development server also fetches a client_id with a port,
over http, and from private addresses, which its production server does not
(its fetch protections are off in development); the server never takes
such a client_id, and fetches from private addresses only with
PDS_DISABLE_SSRF_PROTECTION=true.
How it is checked
harness/lib/clients.mjs is the web the clients publish on: one local HTTP
server standing for https://app.pds-harness.net and
https://other.pds-harness.net. The server is started with
PDS_OAUTH_CLIENT_FETCH naming it, and PDS_DISABLE_SSRF_PROTECTION=true
to reach it; the reference, which runs in the
harness's process, has its fetches of those origins sent there too. Each
side's fetches come to their own path, so the harness counts what each
fetched. harness/checks/oauth-clients.mjs has the steps, among the others
of compare.mjs:
- documents: a new client ID, its document served with one thing wrong, or none, from the lists above (the answer's status, type, size and body; the client ID's form; each field and each check), then PAR on both sides; and, for one taken, PAR again: the document fetched once by each. A document refused, then put right: fetched again, and taken.
- caching: a document taken, then changed or removed: PAR still takes the kept one on both sides; then put back.
- sign-in with an https client: a web, native or confidential client,
its full flow as
OAUTH.md's sign-in step has it, the page'sclientMetadatacompared; the session joins the account's. - client authentication refused: PAR, the code or refresh grant, or a
revocation of a confidential client's, with an assertion with one thing
wrong (missing, another type, not a JWT, each claim and header fault,
another key, a
kidnamed twice,jtireused), then the request again as it should be. - confidential sessions: a refresh with the session's key, the client's
other key, none, or a reused assertion; a revocation with each; then
getSessionand a refresh. - silent sign-in: a confidential client's request with a
promptand alogin_hintdrawn, loaded in the account's browser (signed in or not, the client approved or not, for those scopes or fewer), compared; acodegiven is exchanged. The lifecycle run (LIFECYCLE.md) loads such requests for accounts deactivated, taken down and back again. - crashes: before each kill, a new client's request, on a new device,
signed in there or not; after the restart (the server keeping no
document) and with the reference's kept documents aged past 10 minutes
(it keeps them in the harness's process, by
performance.now()), the document gone, refused, not JSON or with other redirect URIs, or its JWKS gone; thenconsent, the page again, and the code, if any, exchanged.
Compared, on both sides: what OAUTH.md compares, and, in the documents
and caching steps, how many times each side fetched the document and its
JWKS for each request (a kept one: none). Taken out, as in OAUTH.md, and
also the assertions (each side's own, with its own aud). The departures
above are checked on the server alone.
Not compared:
- What happens once a kept document or JWKS is 10 minutes old, a key is removed, or a session reaches 90 days unrefreshed or 730 days old: the harness does not wait.
- Fetches the server's protections refuse (private addresses, timeouts): every document the harness serves is on its own web, which the development fetch reaches.
- Hosts the reference refuses by a list of its own (
example.comand others), aclient_idwith an empty fragment (…json#) or an upper-case host, and a document whose body begins with a byte order mark: the harness draws none of them. client_name,logo_uriand the rest as a page would show them: onlyclientMetadatais compared.