chadtmiller.com/monolith
An atproto PDS
OAuth: the authorization server
The server is the OAuth authorization server for its own accounts, as
atproto/oauth.md says a PDS may be: an app signs an
account in through it, with the account's password, or a passkey
(PASSKEYS.md), on the server's own pages, and is given a
DPoP-bound access token and a refresh token. This
page says what the server serves of that: its metadata, the clients it
takes, pushed authorization requests, the authorization page and the API it
calls, the token and revocation endpoints, DPoP, and getSession with an
OAuth access token. What every method shares, and how the server is
checked, is in PDS.md; the password sessions beside these are
in SESSIONS.md.
Clients whose client_id is an https:// URL (web, native and
confidential clients, whose metadata the server fetches) are in
OAUTH-CLIENTS.md; OAuth access tokens on the other
methods, and what scopes allow, in OAUTH-SCOPES.md;
what the pages show a person, and how they are built and served, in
OAUTH-PAGES.md; permission sets (include: scopes)
in OAUTH-PERMISSION-SETS.md; and the second
issuer, for MCP clients, which sign in on the same pages without PAR or
DPoP and are given a token for the MCP endpoint alone, in
OAUTH-MCP.md.
What is not served yet: the account pages (/account) and their API, whose
sessions and devices an account lists and ends with a token instead
(OAUTH-ACCOUNT.md); and sign-up from the
authorization page.
Sources
This section is informative.
| File | Is | Licence |
|---|---|---|
atproto/oauth.md | atproto's OAuth profile | CC-BY, atproto/LICENSE.txt |
atproto/permission.md | atproto's permissions and their scope strings | CC-BY, atproto/LICENSE.txt |
rfc/rfc6749.txt | OAuth 2.0 | IETF Trust (BCP 78) |
rfc/rfc7636.txt | PKCE | IETF Trust |
rfc/rfc8252.txt | OAuth for native apps: loopback redirect URIs | IETF Trust |
rfc/rfc8414.txt | authorization server metadata | IETF Trust |
rfc/rfc9728.txt | protected resource metadata | IETF Trust |
rfc/rfc9126.txt | pushed authorization requests (PAR) | IETF Trust |
rfc/rfc9449.txt | DPoP | IETF Trust |
rfc/rfc9207.txt | the iss parameter of authorization responses | IETF Trust |
rfc/rfc7009.txt | token revocation | IETF Trust |
The atproto pages are the site's own sources, unchanged, from
github.com/bluesky-social/atproto-website. RFCs are copied whole, as the
IETF Trust's legal provisions allow. Where this page and those differ, this
page says why, under "Where the reference departs from the specs".
The issuer
The server's issuer is the origin of PDS_PUBLIC_URL (ACCOUNTS.md), with
no trailing slash: http://127.0.0.1:2583 for
PDS_PUBLIC_URL=http://127.0.0.1:2583. Its endpoints are that origin with
these paths:
| Path | Is |
|---|---|
/.well-known/oauth-protected-resource | protected resource metadata |
/.well-known/oauth-authorization-server | authorization server metadata |
/oauth/jwks | the server's public keys |
/oauth/par | pushed authorization requests |
/oauth/authorize | the authorization page |
/oauth/authorize/redirect | the redirect back to the client |
/@atproto/oauth-provider/~api/<endpoint> | the API the authorization page calls |
/oauth/token | the token endpoint |
/oauth/revoke | revocation |
Note: atproto/oauth.md asks for https; an http issuer is what a
server on http://127.0.0.1 has, as the reference's development server
has http://localhost:<port>, and clients take it when told to allow
http.
Metadata
GET /.well-known/oauth-protected-resource answers 200 application/json (RFC 9728), with Access-Control-Allow-Origin: *:
{"resource": "<issuer>", "authorization_servers": ["<issuer>"], "scopes_supported": [],
"bearer_methods_supported": ["header"], "resource_documentation": "https://atproto.com"}
GET /.well-known/oauth-authorization-server answers 200 application/json (RFC 8414) with these, where <issuer> is the issuer:
| Field | Value |
|---|---|
issuer | <issuer> |
authorization_endpoint | <issuer>/oauth/authorize |
token_endpoint | <issuer>/oauth/token |
revocation_endpoint | <issuer>/oauth/revoke |
pushed_authorization_request_endpoint | <issuer>/oauth/par |
jwks_uri | <issuer>/oauth/jwks |
require_pushed_authorization_requests | true |
require_request_uri_registration | true |
request_uri_parameter_supported | true |
request_parameter_supported | false: the server takes no request objects (JAR) |
scopes_supported | ["atproto", "transition:email", "transition:generic", "transition:chat.bsky"] |
subject_types_supported | ["public"] |
response_types_supported | ["code"] |
response_modes_supported | ["query", "fragment", "form_post"] |
grant_types_supported | ["authorization_code", "refresh_token"] |
code_challenge_methods_supported | ["S256"] |
ui_locales_supported | ["en-US"] |
display_values_supported | ["page", "popup", "touch"] |
authorization_response_iss_parameter_supported | true |
token_endpoint_auth_methods_supported | ["none", "private_key_jwt"] |
token_endpoint_auth_signing_alg_values_supported | the JWS algorithms the server verifies, ES256 among them |
dpop_signing_alg_values_supported | the JWS algorithms the server verifies DPoP proofs in, ES256 among them |
protected_resources | ["<issuer>"] |
client_id_metadata_document_supported | true |
prompt_values_supported | ["none", "login", "consent", "select_account", "create"] |
and no other field. GET /oauth/jwks answers 200 application/json
{"keys": [...]}: the public keys of whatever the server signs that
clients may verify, which may be none ({"keys": []}).
The protected resource metadata answers with Access-Control-Allow-Origin: *. The authorization server metadata, the JWKS, and the /oauth/par,
/oauth/token and /oauth/revoke endpoints answer browsers' cross-origin
requests: their answers carry Access-Control-Allow-Origin: *,
Access-Control-Allow-Methods: *, Access-Control-Allow-Headers: Content-Type,DPoP and Access-Control-Max-Age: 86400, and OPTIONS on
each answers 200 with those, and with no DPoP-Nonce, Cache-Control or
Pragma. The three endpoints' other answers also carry
Access-Control-Expose-Headers naming DPoP-Nonce, and WWW-Authenticate
when they carry one, and Cache-Control: no-store and Pragma: no-cache.
Clients
A client is named by its client_id. The server takes loopback clients
(atproto/oauth.md, "Localhost Client Development"): a client_id that is
http://localhost or http://localhost/, then nothing or ? and a query
whose parameters are only:
scope, at most once: a scope string, as RFC 6749 §3.3 has it (scope tokens of printable ASCII but"and\, separated by single spaces), that includesatprotoand names no scope twice. Without it, the scope isatproto.redirect_uri, any number of times: anhttp:URL whose host is127.0.0.1or[::1], with no user or password. Without one, the redirect URIs arehttp://127.0.0.1/andhttp://[::1]/.
The query is decoded as a URL's query is (+ is a space). Anything else
(another scheme, host or port, a path, a fragment, another parameter, a
scope or redirect_uri that is not as above) is refused wherever a
client_id is taken: 400 invalid_client_metadata, but 400 invalid_redirect_uri for a redirect URI with a user or password. A
client_id that is neither a loopback one nor an https:// one
(OAUTH-CLIENTS.md) is 400 invalid_client_metadata too.
A loopback client's metadata, as the authorization page shows it, is:
{"client_id": "<the client_id, as given>", "scope": "<its scope>", "redirect_uris": ["<its redirect URIs, in order>"],
"response_types": ["code"], "grant_types": ["authorization_code", "refresh_token"],
"token_endpoint_auth_method": "none", "application_type": "native",
"subject_type": "public", "authorization_signed_response_alg": "RS256",
"dpop_bound_access_tokens": true}
A loopback client is public: it does not authenticate, and its requests
carry no client_secret or client assertion that the server checks.
DPoP
Every request to /oauth/par, /oauth/token and /oauth/revoke, and every
XRPC call with an OAuth access token, carries a DPoP proof (RFC 9449) in
one DPoP header: a JWT whose header has typ: dpop+jwt, an alg the
server verifies (ES256 always), and the public key that signs it as jwk,
and whose claims are:
| Claim | Is |
|---|---|
jti | a string, never used before (below) |
htm | the request's method, as sent (POST) |
htu | the request's URL: what is compared is the scheme, host (in lower case), port (the scheme's default if none) and path, so a query or fragment in either is ignored |
iat | a number, seconds since the epoch, no more than 190 seconds before the server's clock and no more than 180 after |
nonce | a string: a nonce the server gave (below) |
ath | at XRPC, base64url of the SHA-256 of the access token; at the three endpoints above, absent |
and an exp, if given, not more than 180 seconds past. The proof is
checked in this order, and the first failure answers:
- One
DPoPheader, not empty, holding a JWT withtyp: dpop+jwt, ajwkthat is a public key, analgthe server verifies, and a signature by that key;iatpresent, a number, and in the window;exp, if present, not more than 180 seconds past. Otherwiseinvalid_dpop_proof. nonce, if present, a string;jtia non-empty string;htmthe request's method;htua string, a URL,httporhttps, with no user or password, matching the request's. Otherwiseinvalid_dpop_proof.noncepresent: otherwiseuse_dpop_nonce. A nonce the server does not take:use_dpop_nonce.ath: absent at the three endpoints, the access token's hash at XRPC. Otherwiseinvalid_dpop_proof.- The
jtinot seen before: otherwiseinvalid_dpop_proof. A proof that passes 1-4 is spent, whatever the request then answers: sent again, it is refused as replayed, as the reference refuses it (probed: a proof of agetSessionrefused for its token, sent again, isinvalid_dpop_proof). It is kept durably (below, "Single-use values") only once its request has passed the checks of its token or grant: at XRPC, once the access token is found good; at the token endpoint, once its code or refresh token is; at PAR, once the request is kept; at revocation, once a token is revoked. A proof of a request refused for anything after step 5 is held in memory alone until its 200 seconds pass, and not across a restart: sent again after one, it is checked as a proof never seen, and its request, the same as before, is refused again for its token or grant. So a stranger's proofs, of tokens and codes that are not good, write nothing to disk. The server holds at most 1000000 such proofs in memory, and past that forgets the oldest first, likewise.
The URL a proof names is the one the client sent to: the issuer's origin and the request's path.
Status and headers. At the three endpoints, invalid_dpop_proof is
401 with WWW-Authenticate: DPoP algs="<the algorithms>", error="invalid_dpop_proof", and use_dpop_nonce is 400 with no
WWW-Authenticate. At XRPC both are 401 with WWW-Authenticate: DPoP algs="…", error="<error>". WWW-Authenticate may carry an
error_description as well, and the server may choose the algs list.
Nonces. Nonces rotate every 60 seconds, by the clock: period n is the
60 seconds from n × 60 seconds after the epoch. Every answer of the three
endpoints, and every answer to an XRPC call made with the DPoP scheme, carries
DPoP-Nonce: <nonce>, the nonce of the period after the current one, and
the server takes the nonces of the previous, current and next periods. So a
nonce works from when it is first given for at least two minutes, and at
most three. The three endpoints and XRPC give and take the same nonces. A
nonce is a string of base64url characters no one without the server's
secret can predict; the secret is kept in PDS_DATA_DIR, so nonces given
before a restart still work after it.
Single-use values
The server keeps a record of values that may be used once, each in a namespace and until a time, and refuses one it already holds there until that time: it survives restarts, and forgets each entry once its time has passed. What uses it here:
| Namespace | Value | Kept for |
|---|---|---|
| DPoP proofs | a proof's jti, across all clients, endpoints and XRPC | 200 seconds |
| PKCE | a code_challenge whose code was exchanged | 24 hours |
| states | a client's state, kept as the SHA-256 of its client_id and state, so each entry is of one size whatever their length | 24 hours |
Pushed authorization requests
POST /oauth/par (RFC 9126) takes a form (application/x-www-form-urlencoded)
or JSON (application/json); another Content-Type, or none, is 415
with error: invalid_request, and JSON that does not parse 400 invalid_request. A body longer than 102400 bytes (100 KiB), as received,
by its Content-Length or as it comes, is 413 with error: invalid_request, as the reference's; one of exactly 102400 is read. The
server decodes no Content-Encoding: a body with one other than
identity is 415 with error: invalid_request, as the reference
answers one it does not know (probed: foo). The reference decodes
gzip, and holds the decoded body to its 100 KiB (probed: a gzipped PAR
is kept; one of 200 KiB decoded is 413); the harness sends no encoded
body. Other methods are 405. A parameter given twice is 400 invalid_request (RFC 6749 §3.1). The parameters:
| Parameter | Is |
|---|---|
client_id | required, non-empty |
response_type | required: code |
redirect_uri | one of the client's redirect URIs; may be left out when the client has exactly one |
scope | required: one left out is refused at step 11 below, as a scope without atproto |
state | required, non-empty |
code_challenge, code_challenge_method | required: PKCE (RFC 7636) with S256 |
login_hint | optional: a handle or a DID, in any case |
prompt | optional: none, login, consent, select_account or create |
response_mode | optional: query (the default), fragment or form_post |
ui_locales | optional: language tags as fr-CA en (each [a-z]{2,3} with an optional -[A-Z]{2}, separated by single spaces) |
display | optional: page, popup, touch or wap |
max_age | optional: an integer, 0 or more |
dpop_jkt | optional: the JWK thumbprint (RFC 7638) of the client's DPoP key |
Other parameters (resource, request, client_secret, ...) are ignored.
A redirect URI matches one of the client's if it is equal, or if both are
loopback URLs (127.0.0.1 or [::1]), the client's has no port, and they
are equal but for the port (RFC 8252 §7.3).
The request is checked in this order, and the first failure answers, all
400 but where said:
-
The body, as above.
-
client_idpresent and non-empty: elseinvalid_client. -
The parameters' forms:
response_typeone ofcode,token,none,code id_token token,code id_token,code token,id_token token,id_token;redirect_uri, if given, anhttps:URL, anhttp:URL on127.0.0.1or[::1](neverlocalhost), or a private-use scheme URI (com.example.app:/path);scopea scope string as above;code_challenge_methodS256orplain;prompt,response_mode,ui_locales,display,max_ageas above;login_hintnon-empty;id_token_hintandclaims, if given, a JWT and a JSON object; elseinvalid_request. -
The DPoP proof, as above: required here (else
401 invalid_dpop_proof). -
The client: its
client_idas under "Clients". -
dpop_jkt, if given, the proof's key's thumbprint: else401 invalid_token, withWWW-Authenticate: DPoP … error="invalid_token". -
claims,id_token_hintornoncegiven:invalid_request. -
response_typenotcode:unsupported_response_type. -
Every scope token one the client's metadata declares: else
invalid_scope.redirect_urione of the client's, or left out when it has exactly one: elseinvalid_request. -
code_challenge_methodgiven withoutcode_challenge, or nocode_challenge:invalid_request. -
scopeleft out, or withoutatproto:invalid_scope; withopenid:invalid_scope. -
code_challenge_methodnotS256:invalid_request. -
prompt=none:invalid_request(a public client may not sign in silently). -
login_hintneither a handle nor a DID, once lower-cased:invalid_request. -
An
include:scope whose set does not resolve, or is not a set (OAUTH-PERMISSION-SETS.md, "At PAR"):invalid_scope. -
statemissing or empty, or the same as one this client gave in the last 24 hours:invalid_request. -
A request larger than the server keeps:
invalid_request. That is aclient_idlonger than 18470 bytes, astatelonger than 1024, acode_challengethat is not 43 characters (an S256 challenge always is, so no verifier matches another), aredirect_uriorlogin_hintlonger than 2048, ascopelonger than 4096, orui_localesof more than 16 tags. The reference keeps them whatever their length, up to its body's 100 KiB (probed: astateof 100000 bytes and acode_challengeof 10000 are kept).Note: 18470 is the longest loopback
client_idnaming oneredirect_uriof 2048 bytes and ascopeof 4096, every byte of both percent-encoded:http://localhost/?redirect_uri=(31 bytes),&scope=(7) and three bytes for each of their 6144. A loopback client's ID carries its scope and redirect URIs, so a cap below that refuses a client whose every part is within its own cap (knotless's CLI's ID, for one, is 2857 bytes). -
Requests already kept and pending (not yet approved, ended or past their time) from the client address (
LIMITS.md, "The client address"; an IPv6 address by its first 64 bits): 1000 of them, and this one is429witherror: invalid_request; 20000 from all addresses together, likewise. The reference keeps any number (probed: 600 from one address, all kept).
Note: so a request kept holds at most a few KiB, and the server at most 20000 of them: the requests that pass 1 to 17 and are refused at 18 cost nothing.
PAR has no rate limit otherwise ("Rate limits", below).
A request that passes is kept, and answered 201 {"request_uri": "urn:ietf:params:oauth:request_uri:<id>", "expires_in": 300}, where <id>
is the server's, unguessable, and expires_in is 299 or 300. It expires
300 seconds from now, unless the authorization page extends it.
What is kept of it:
scope: its scope tokens, each once, in the order first given, keeping only those the server knows:atproto,transition:email,transition:generic,transition:chat.bsky, the permissions ofatproto/permission.mdthat parse (below), and theinclude:scopes that parse (OAUTH-PERMISSION-SETS.md), unexpanded. The others are dropped, and the user is never asked for them.login_hint, lower-cased.prompt:createif givencreate, elseconsent, whatever was given: a public client never skips consent.- the DPoP key's thumbprint:
dpop_jkt, or else the proof's. - the rest as given.
Which permissions parse. A permission scope is as
atproto/permission.md gives it: a resource, then optionally : and the
positional parameter, then optionally ? and name=value pairs joined by
&, percent-encoded as a URL's query is. It parses if its resource is
repo, rpc, blob, account, identity or space, each of its parameters is
one that resource takes, given in one place only, with a value that
resource allows, and each required one is there:
| Resource | Parameters (positional first) | Values |
|---|---|---|
repo | collection (one or more, required), action (any of) | an NSID or *; create, update, delete |
rpc | lxm (one or more, required), aud (required) | an NSID or *; a DID with a # service fragment, or *; not both * |
blob | accept (one or more, required) | a MIME type type/subtype, type/* or */* |
account | attr (required), action | email, repo or status; read or manage |
identity | attr (required) | handle or * |
space | spaceType (required), authority, skey, collection (one or more), action (one or more), manage (one or more) | as OAUTH-SCOPES.md ("Spaces") says |
So repo:*, repo:com.example.foo?action=create,
rpc:app.bsky.feed.getTimeline?aud=*, blob:image/*,
account:email?action=manage and identity:* are kept, and repo,
repo:com.example.*, rpc:app.bsky.feed.getTimeline, rpc:*?aud=*,
blob:*/png, account:*, identity:other, transition:other and
foo:bar are dropped. A kept permission keeps the string it was given.
The authorization page
GET /oauth/authorize?client_id=<client_id>&request_uri=<request_uri> is
the page the client sends the user's browser to. It is a navigation, and is
refused otherwise: a request without Sec-Fetch-Mode: navigate,
Sec-Fetch-Dest: document, and a Sec-Fetch-Site of same-origin,
same-site, cross-site or none, or with an Origin other than the
issuer's, is a 400 error page invalid_request. Its other methods are
404.
Pages. The server answers HTML. Each page has, in a <script> element,
statements window["<name>"]=JSON.parse("<s>");, where <s> is a JSON text
written as a JavaScript string literal; these are what is checked of a page.
An error page has __errorData, {"error", "error_description"}, with the
error's status; a 400 error page whose error this page does not name is
invalid_request. The authorization page has __authorizeData,
__sessions and __passkeyOptions. The rest of a page, its assets, and
how its script calls the API are in OAUTH-PAGES.md.
Devices. The page sets cookies that name the browser, its device: a
browser that sends back the cookies it was last given is the same device,
and one that sends none, or ones the server did not set, is a new one. Any
answer of the page or the API may give the device new cookies, and a
sign-in that signs an account in always does; the ones it had before are
then old. For 30 seconds
after a device was last given new cookies, a browser that sends old ones
is still that device, and is given new ones (as two tabs of one browser,
one a step behind); after that, a browser that sends old ones ends the
device: every account is signed out of it, for every browser holding any
of its cookies, and that browser is a new device. So cookies taken from a
browser before a sign-in do not carry the sign-in past those 30 seconds,
and using them then signs out the browser that signed in, as the
reference does (probed: a second browser holding the cookies from before
a sign-in lists the account at once, and the signed-in browser still does
after it; 31 seconds after the sign-in, the second lists none, and then
neither does the signed-in one). The device cookies are HttpOnly,
SameSite=Lax, Path=/. The page also sets the cookie csrf-token (not
HttpOnly, SameSite=Lax, Path=/), whose value the page's script sends
as the x-csrf-token header of every API call.
Checks. After the navigation check:
client_idandrequest_uripresent: else a400error pageinvalid_request. Arequest_urithat is noturn:ietf:params:oauth:request_uri:and an id:400error pageinvalid_request.- The client: a
client_idrefused as under "Clients" is a400error page with that error. - The request: one the server does not keep (never made, or ended) is a
400error pageinvalid_request. Then, a request already approved, past its time, made by another client, or loaded before on another device is ended, and the browser is redirected to the client (below) witherror=access_denied. A request ended once approved takes its code with it: a code not yet exchanged is spent, and the token endpoint refuses it.
Otherwise the request is now this device's, and expires 300 seconds from
now; the page answers 200, Cache-Control: no-store, with:
__authorizeData:{requestUri, clientId, clientMetadata, clientTrusted: false, clientFirstParty: false, scope, promptMode, permissionSets}, and alsouiLocales(the request's, as given),loginHintandselectedDidwhen they have values.scopeandpromptModeare the request's, as kept;permissionSetsis asOAUTH-PERMISSION-SETS.mdsays ({}for a scope with noinclude:).loginHintis the request'slogin_hint, but the handle of the account it names if it is the DID of an account here.selectedDidis the DID of the account signed in on this device thatlogin_hintnames by DID or handle, if one is, and only whenpromptModeisconsent: withcreatethere is none.spacesandspaceHandlesare there when the scope, with what its sets grant, has aspacepermission, asOAUTH-SCOPES.mdsays ("Spaces", "On the authorization page").__sessions: the accounts signed in on this device and remembered (below), each{account, loginRequired}, in any order.loginRequiredistrueonce the account's last sign-in on this device (below) is more than seven days old.__passkeyOptions: a new challenge's options for the device, which the page signs in with by a passkey (PASSKEYS.md, "The page's options"). The reference has none, and it is not compared.
An account, here and in the API, is {did, pds, email, emailVerified, emailAuthFactor, handle, deactivated}: pds is the server's DID,
did:web:<PDS_HOSTNAME>; emailVerified whether the account's email is
confirmed, emailAuthFactor whether its email factor is on (EMAIL.md),
and deactivated whether it is deactivated (LIFECYCLE.md); name, the
displayName of the account's
app.bsky.actor.profile record self, when it has one with a
displayName; and picture, when that record has an avatar (a blob
ref, or a legacy {cid}), its URL as PROXY.md makes an avatar's:
on the AppView's CDN with PDS_BSKY_APP_VIEW_CDN_URL_PATTERN, else
https://<PDS_HOSTNAME>/xrpc/com.atproto.sync.getBlob?did=<did>&cid=<cid>.
A request without request_uri is refused: a 400 error page
invalid_request (PAR is required).
The API
The page's script calls POST /@atproto/oauth-provider/~api/<endpoint> with
a JSON body. Any other method or endpoint is 404; the server may choose
its body.
Every call is checked,
in this order, each failure 400 with a JSON body {"error": "invalid_request", "error_description"}:
Sec-Fetch-Mode: same-originandSec-Fetch-Site: same-origin.Origin, if present, the issuer's.Referer: the issuer's origin, path/oauth/authorize, and arequest_uriquery parameter of the form above. The call is then for that request. (passkey-registertakes the passkey page's instead,PASSKEYS.md, "passkey-register".)- The
x-csrf-tokenheader and thecsrf-tokencookie both present and equal. Content-Type: application/json(else415, with the same body), and the body: at most 102400 bytes, as PAR's (else413, with the same body), a JSON object with exactly the endpoint's fields, of their types, and no others.
Answers are JSON with Cache-Control: no-store. The endpoints:
sign-in {locale, identifier, password, remember?, emailOtp?}:
locale a tag as en or fr-CA; identifier a handle, a DID, or an
email (below); password 1 to 512 characters; remember a boolean. An
identifier that is none of these is 400 invalid_request, before any
account is looked up. An email here is narrower than what createAccount
takes: matched without regard to case, it is the whole of
(?!\.)(?!.*\.\.)[A-Z0-9_'+\-.]*[A-Z0-9_+-]@([A-Z0-9][A-Z0-9\-]*\.)+[A-Z]{2,},
its part before @ at most 64 characters, each label after it at most 63,
and the whole at most 254: so a@b.c1, a@b.c, ü@x.io and a!b@x.io are
not. An account whose email is not one signs in by handle or DID. The account's
password signs in, by handle, email or DID, as createSession takes them
(ACCOUNTS.md); an app password does not, nor does any password for an
account created without one. A wrong one is 400 invalid_request. It
answers {account}, and:
- with
remember: true, or withrememberleft out when the account is already signed in on this device, the account is signed in on this device, its sign-in time there is now, and the page lists it from then on; - otherwise (
remember: false, or left out when it was not signed in there), the account is not, or no longer, signed in on this device, and the answer hasephemeralTokentoo: a string that stands for this sign-in, for this account, device and request, for 15 minutes.
Before any account is looked up, once the identifier's form passes, the
sign-in costs one point of the login limits createSession costs
(LIMITS.md, "Rate limits": the identifier as sent and the client
address), in the same buckets, with PDS_RATE_LIMITS_ENABLED. Past one, it
is 429 with {"error": "invalid_request", "error_description"} and
Retry-After, the seconds until that window ends, rounded up, and no
password is hashed; it carries no RateLimit-* headers. The reference
limits OAuth's sign-in in no way (probed: 40 wrong passwords for one
identifier from one address, each 400 invalid_request, and the right one
then taken). Every sign-in, refused or not, answers no sooner than 400 ms
after its body was checked, as the reference's (probed: 401 to 403 ms for
a wrong password and for an identifier no account has), and hashes as
LIMITS.md says ("Passwords"): on the server's hashing threads, the same
hashes for an identifier no account has, so its time shows nothing.
The request itself need not still be kept: signing in does not use it, as
the reference's does not (probed: a sign-in whose Referer names a
request never made is 200). What bounds a stranger's guesses at a
password is the limit above.
The email factor. With the account's email factor on (EMAIL.md), the
right password alone does not sign in, as createSession without an
authFactorToken does not: without emailOtp, the server mails the
account an auth_factor code (kind signInAuthFactor) and answers 401
with error: second_authentication_factor_required, signing nothing in,
as the reference does (probed: the reference's 401 where a server that
checks only the password answers 200). The code given as emailOtp
signs in, and is used up. A device the account signed in on, remembered,
within the last 30 days needs no code, as the reference's sign-in allows
it (allowOtpBypassFor). An emailOtp that is not the account's current
code is 400 invalid_request, mailing nothing. What it answers to a wrong
code, and on a remembered device, is compared (harness/checks/email.mjs, the email
factor's step). An app password does not sign in here, factor or not; a
passkey does, with no code (PASSKEYS.md, "passkey-sign-in").
consent {did, scope?} approves the request for the account did,
which must be signed in on this device, or else the call must carry
Authorization: Bearer <ephemeralToken> of a sign-in of that account, on
this device, for this request. did is a DID, and scope, if given, a
scope string (as under "Clients"); either otherwise is 400 invalid_request, as the body check says. scope narrows the request's
scope to the tokens in both, so that tokens of scope the request does not
have are dropped: in the request's order, or in scope's if scope names
fewer distinct tokens than the request has, counting every token it names,
those the request does not have too. It answers {url}, a URL on the
issuer, <issuer>/oauth/authorize/redirect?… with redirect_mode,
redirect_uri (the request's), iss (the issuer), state (the request's),
and code, an authorization code. The request is then approved: it cannot
be approved again, and its code expires 300 seconds from now.
If the request cannot be approved, consent still answers 200 {url},
with error and error_description in place of code, and the request is
ended, with its code if it had one. Checked in this order, the first
failure answering:
- A request the server keeps: else
400 invalid_request, and nourl. - The request not already approved, not past its time, and not loaded on
another device (a request never loaded is now this device's): else
access_denied. didsigned in on this device, or the ephemeral token as above: elseinvalid_request.- The narrowed scope has
atproto: elseaccess_denied.
reject {} ends the request and answers {url} as consent does,
with error=access_denied; a request already approved is ended with the
same error, and its code with it. A request the server does not keep is
400 invalid_request.
sign-out {did} signs the account out of this device, if it was
signed in, and answers {"success": true}.
passkey-options {} and passkey-sign-in {locale, credential, remember?} sign an account in with a passkey, as sign-in signs it in
with its password, and passkey-register {credential}, called from
the passkey page, adds one: PASSKEYS.md says what each takes and
answers.
The redirect
GET /oauth/authorize/redirect is where the page sends the browser with
the url the API answered. It is a navigation from the page: it needs
Sec-Fetch-Site: same-origin, Sec-Fetch-Mode: navigate, Sec-Fetch-Dest: document, an Origin, if present, of the issuer, and a Referer that is
the authorization page (the issuer's origin, /oauth/authorize, and a
request_uri of the right form). It takes redirect_mode, redirect_uri,
and either code (then state, iss, code, and id_token,
access_token, expires_in, token_type if given) or error (then
state, iss, error, error_description, error_uri), and sends those
that are given to redirect_uri:
query:303toredirect_uriwith them in its query;fragment:303toredirect_uriwith them as its fragment, encoded as a query is;form_post:200HTML with a<form method="post" action="<redirect_uri>">holding each as<input type="hidden" name="…" value="…">, which the page submits.
Anything else, or a URL with neither code nor error, is a 400 error
page invalid_request.
The page's own refusals that name the client (a request ended under
"Checks") redirect the browser to the request's redirect_uri the same
way, at once, with iss, state, error and error_description.
The token endpoint
POST /oauth/token takes a form or JSON, as /oauth/par does (415
otherwise; other methods 404), but with a body of up to 2097152 bytes
(2 MiB) as received, past which it is 413 (the reference's 100 KiB is
not compared: the harness sends nothing so long), with a DPoP proof. Its answers carry
Cache-Control: no-store and Pragma: no-cache. It checks, in this order,
each failure 400 unless said:
- The body, as for PAR.
client_idpresent and non-empty: elseinvalid_grant.grant_typeauthorization_code,refresh_token,passwordorclient_credentials, with that grant's fields: forauthorization_code,code(non-empty),redirect_uri(a redirect URI of the form above) andcode_verifier(optional: 43 to 128 ofA-Za-z0-9-._~); forrefresh_token,refresh_token(non-empty). Elseinvalid_grant.- The DPoP proof, as above.
- The client, as under "Clients".
- A DPoP proof present: else
401 invalid_dpop_proof. grant_typeauthorization_codeorrefresh_token: elseinvalid_grant.
The code grant then checks, all invalid_grant:
codeone the server gave, not spent, and given less than 300 seconds ago: else refused, and if a session was made from that code, the session is ended (a code used twice ends what the first use made). The code is now spent, and its request ended (no longer kept: its page is then a400error page, and the API answers400), whatever follows. A code whose request a change of its account's state ended is spent (LIFECYCLE.md, "OAuth sessions").- Its request's client is this one; the proof's key is the request's.
redirect_uriis the request's, as kept.code_verifierpresent, and its SHA-256, base64url, is the request'scode_challenge.- That
code_challengenot exchanged before (single-use values). - The code's account neither taken down nor deactivated now
(
LIFECYCLE.md).
It answers 200:
{"access_token": "<token>", "token_type": "DPoP", "refresh_token": "<token>",
"scope": "<the request's scope, as kept and narrowed, its include: scopes expanded>", "expires_in": 900, "sub": "<the account's DID>"}
and starts a session: the account, the client, the DPoP key, the scope,
when it started, and its current tokens. The tokens are strings of
A-Za-z0-9-._~+/ (RFC 6750's b64token) that only the server can make;
the server may choose what they hold. expires_in is the access token's life in
seconds: 900 (899 to 900 as answered), or less if the session ends sooner.
The refresh grant checks, all invalid_grant:
refresh_tokena session's: its current one, or one it had before. Neither: refused.- One it had before (a replaced refresh token): refused, and the session ends.
- The session's client is this one, and the proof's key is the session's: else refused, and the session ends.
- The session not past its end, two weeks from when it started: else refused, and the session ends.
It answers as the code grant does, with the session's scope (its
include: scopes expanded again, OAUTH-PERMISSION-SETS.md), a new access
token and a new refresh token, which replace the old: the old access token
stops working at once, and the old refresh token is now a replaced one.
Revocation
POST /oauth/revoke (RFC 7009; other methods are 404) takes a form or
JSON, as the token endpoint does, its body up to 2 MiB,
with client_id, token (non-empty) and optionally token_type_hint
(access_token or refresh_token), and a DPoP proof. A body without
client_id, without token, or with another token_type_hint is 400 invalid_request; then a DPoP proof, if there is one, is checked as above,
and a bad one answers its error. Past those, it answers 200 {} whatever
the token: and if there was a proof, the client is the one the token's
session is for, the proof's key is the session's, and the token is the
session's current access token, its current refresh token, a replaced
refresh token, or the code it was made from, the session ends. Otherwise
nothing changes.
OAuth tokens on XRPC
com.atproto.server.getSession takes an OAuth access token as
Authorization: DPoP <access token>, the scheme in any case, with a DPoP
proof of the call: htm GET, htu the issuer's origin and the path
/xrpc/com.atproto.server.getSession, and ath the token's hash. Checked
in this order:
- With a
DPoPheader, the proof, as under "DPoP":401 invalid_dpop_proofor401 use_dpop_nonce. - The access token one the server issued, at any time: else
401 invalid_token. - A
DPoPheader: else401 invalid_dpop_proof. - The proof's key the one the token was issued for: else
401 invalid_token. - The token its session's current one, the session not ended, and the
token not past its
expires_in: else401 invalid_token.
These answers are XRPC errors, {"error", "message"}, with
WWW-Authenticate: DPoP algs="…", error="<error>". Every answer to a call
with the DPoP scheme carries DPoP-Nonce, and answers to calls without it
carry none.
It answers {did, handle, active: true} for the session's account, and
also email, emailConfirmed: false and emailAuthFactor: false when the
session's scope has transition:email, account:email or
account:email?action=manage.
An OAuth access token sent as Bearer is not a token the server gave out
as one: 400 InvalidToken, as PDS.md says. A password session's token
sent as DPoP is 401 invalid_token. The other methods that take a token
take an OAuth access token as OAUTH-SCOPES.md says.
Errors
The three endpoints' errors are JSON {"error", "error_description"}
(RFC 6749 §5.2). What is compared is the status and error;
the server may choose the words of error_description.
Rate limits
OAuth's endpoints, its pages and the API they call, /oauth/jwks and the
metadata documents cost nothing of the rate limits LIMITS.md gives XRPC,
and their answers carry no RateLimit-* headers. The sign-in alone is
limited: it costs the login limits of createSession (above, "The API");
the passkey calls cost nothing (PASSKEYS.md). Otherwise a client may
call them as often as it likes, as the reference's:
what bounds what they hold is PAR's caps (above), the single-use values'
times, and the free space below. A call with an OAuth access token is
limited as LIMITS.md says ("OAuth access tokens").
Free space
Below PDS_MIN_FREE_BYTES (LIMITS.md, "Disk"), what would keep
something is refused, changing nothing, once its checks above have passed
and before anything is kept: a PAR is 507 with error: temporarily_unavailable; the authorization page a 507 error page
temporarily_unavailable; the API's sign-in, consent and reject
507 {"error": "temporarily_unavailable", "error_description"}, a
sign-in that would mail an email factor's code refused so before the code
is made or mailed; passkey-register and passkey-sign-in likewise
(PASSKEYS.md); the token
endpoint and revocation 507 with error: temporarily_unavailable. A
call with an OAuth access token is refused or answered as the same call
with a password session is: a write 507 InsufficientStorage, a read
answered, its proof's jti held in memory alone ("DPoP").
Durability
As DURABILITY.md says of the rest, what the server answered survives it
being killed: a request PAR answered, until it expires, with the device it
was loaded on; a code consent answered, and its spending; a session the
token endpoint answered, its refresh, and its end by revocation, a replay
or a failed refresh; the accounts signed in on each device, by password or
passkey; the single-use values, until their time; and the nonce secret.
The passkeys themselves are kept as PASSKEYS.md says ("Durability").
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 PAR with no DPoP proof, binding the key at the token request | atproto/oauth.md: clients must start DPoP at PAR | 401 invalid_dpop_proof |
takes a PAR without state, or with an empty one | atproto/oauth.md: state is required | 400 invalid_request |
takes a state the client used before | atproto/oauth.md: servers should reject duplicate states | 400 invalid_request for the same client within 24 hours |
| takes a parameter twice, the last winning | RFC 6749 §3.1: parameters must not be repeated | 400 invalid_request |
| issues access tokens for 60 minutes | atproto/oauth.md: access tokens should live less than 30 minutes | 15 minutes (expires_in: 900) |
| serves an authorization request given on the page's URL, without PAR | RFC 9126 §5 with require_pushed_authorization_requests | a 400 error page |
keeps a PAR's state, code_challenge and other parameters of any length, up to 100 KiB, and any number of requests | none: the server's own bounds | 400 invalid_request past PAR's step 17, 429 past step 18 |
| limits its sign-in in no way | none: the server's own bound | the login limits of createSession |
keeps every DPoP proof's jti, that of a call refused for its token too, across a restart (as far as the harness can tell: it is never restarted) | none: the server's own bound | a proof of a call refused for its token held in memory alone; sent again after a restart, 401 invalid_token |
Clients rely on none of these.
How it is checked
harness/checks/oauth.mjs drives both servers as a client would: its own
DPoP keys and proofs, PKCE, PAR, the authorization page and its API through
harness/lib/oauth.mjs (a browser without a browser: the page's
navigations and API calls with their Sec-Fetch-*, Origin, Referer,
cookies and CSRF header), the token and revocation endpoints, and
getSession; and also @atproto/oauth-client-node, a client app's own
library, as a loopback client. At the start it compares the metadata. Then
its steps, among the others of compare.mjs:
- sign-in: a full flow for an account, with a random client (loopback
client_ids with scopes and redirect URIs drawn from a list), scope,login_hint,prompt,response_mode, identifier,remember, and a narrowed consent or a rejection; the session joins the account's. - PAR, page, API, redirect, token, revoke refused: one request with one
thing wrong, from the lists above, on each side; PAR's among them a body
of exactly 100 KiB, taken, and one byte past,
413. - DPoP refused: a request to one of the endpoints or to
getSessionwhose proof has one thing wrong, with a nonce fresh on each side. - refresh: with a session's current or replaced refresh token, its key
or another, then
getSessionwith the old and new access tokens. - revoke: a session's current or replaced token, then
getSessionand a refresh. - getSession: with a session's access token, current, replaced or ended.
- device cookies: a page loaded on a new device, its cookies copied to
a second browser, and a sign-in with
remember: trueon the first: whether the sign-in gave the device new cookies (of those butcsrf-token), compared; then, at once or 31 seconds later, a new request's page loaded with the copied cookies, in the browser that signed in, and with the copied ones again, each page's__sessionscompared. - the client library:
authorize, the page,callback,getSessionthrough its session, a refresh,signOut, andrestoreafter it. - crashes: before each kill, a fresh nonce and a
getSessionfor some sessions, compared; after the restart, thatgetSession's proof sent again (a replay on both sides), agetSessionwith the nonce given before the kill and no retry, and sometimes a refresh. Where thegetSessionbefore the kill was refused for its token (a session already ended), its proof was held in memory alone ("DPoP", step 5): sent again after the restart, the server refuses it for its token again,401 invalid_token, while the reference, never restarted, answers it as replayed. The server is held toinvalid_tokenalone there (below).
Compared, on both sides: statuses; errors (error of the OAuth JSON,
the error parameter of WWW-Authenticate and of redirects, and
__errorData.error); which answers carry DPoP-Nonce and
WWW-Authenticate; the metadata documents, but for the algorithm lists
(which must each include ES256), request_parameter_supported and the
reference's request_object_* fields; the CORS headers; the page's
__authorizeData and __sessions; the API's answers; the redirects'
targets and parameters; the token answers but for the tokens and
expires_in; and getSession's answers. Taken out first: the server's URL,
DIDs (named by the order the accounts were made), each request's
request_uri, codes, states (each side's own, checked to be echoed),
tokens, ephemeral tokens, and nonces. expires_in is held to this page on
the server (899 to 900 for tokens, 299 to 300 for PAR) and to the
reference's own values on the reference (3599 to 3600, 299 to 300). The
departures above are checked on the server alone: PAR's caps with a
state of 1024 bytes (kept) and 1025, a code_challenge of 42 and 44
characters, ui_locales of 16 tags (kept) and 17, and a loopback
client_id of 18471 bytes. A loopback client_id of exactly 18470
bytes, one whose scope is near 4096 bytes, and knotless's CLI's own are
kept on both sides (compared, among PAR's refusals). harness/checks/limits.mjs times the
sign-in in every run, and its --limits run holds the server alone to
the sign-in's limit, PAR's 1000 pending requests from one address, and
the free space (LIMITS.md, "How it is checked").
Not compared:
- What a request answers once a code, request or session is past its time:
the harness does not wait five minutes, nor two weeks. Nor does it use an
access token past its
expires_in, which differs between the sides: a session whose server access token is within three minutes of its end is refreshed, compared, before a step uses it. - The
algsanderror_descriptionofWWW-Authenticate, anderror_descriptionandmessageanywhere. - Two refreshes at once with one token: which lands first is a race.
__customizationData, and the rest of a page's HTML here:--pageschecks the pages in a browser (OAUTH-PAGES.md).