~ knotless Search/
↑↓ move↵ open⇧↵ all results
0
0
901 lines · 49.0 KB Raw History

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.

FileIsLicence
atproto/oauth.mdatproto's OAuth profileCC-BY, atproto/LICENSE.txt
atproto/permission.mdatproto's permissions and their scope stringsCC-BY, atproto/LICENSE.txt
rfc/rfc6749.txtOAuth 2.0IETF Trust (BCP 78)
rfc/rfc7636.txtPKCEIETF Trust
rfc/rfc8252.txtOAuth for native apps: loopback redirect URIsIETF Trust
rfc/rfc8414.txtauthorization server metadataIETF Trust
rfc/rfc9728.txtprotected resource metadataIETF Trust
rfc/rfc9126.txtpushed authorization requests (PAR)IETF Trust
rfc/rfc9449.txtDPoPIETF Trust
rfc/rfc9207.txtthe iss parameter of authorization responsesIETF Trust
rfc/rfc7009.txttoken revocationIETF 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:

PathIs
/.well-known/oauth-protected-resourceprotected resource metadata
/.well-known/oauth-authorization-serverauthorization server metadata
/oauth/jwksthe server's public keys
/oauth/parpushed authorization requests
/oauth/authorizethe authorization page
/oauth/authorize/redirectthe redirect back to the client
/@atproto/oauth-provider/~api/<endpoint>the API the authorization page calls
/oauth/tokenthe token endpoint
/oauth/revokerevocation

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:

FieldValue
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_requeststrue
require_request_uri_registrationtrue
request_uri_parameter_supportedtrue
request_parameter_supportedfalse: 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_supportedtrue
token_endpoint_auth_methods_supported["none", "private_key_jwt"]
token_endpoint_auth_signing_alg_values_supportedthe JWS algorithms the server verifies, ES256 among them
dpop_signing_alg_values_supportedthe JWS algorithms the server verifies DPoP proofs in, ES256 among them
protected_resources["<issuer>"]
client_id_metadata_document_supportedtrue
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 includes atproto and names no scope twice. Without it, the scope is atproto.
  • redirect_uri, any number of times: an http: URL whose host is 127.0.0.1 or [::1], with no user or password. Without one, the redirect URIs are http://127.0.0.1/ and http://[::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:

ClaimIs
jtia string, never used before (below)
htmthe request's method, as sent (POST)
htuthe 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
iata number, seconds since the epoch, no more than 190 seconds before the server's clock and no more than 180 after
noncea string: a nonce the server gave (below)
athat 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:

  1. One DPoP header, not empty, holding a JWT with typ: dpop+jwt, a jwk that is a public key, an alg the server verifies, and a signature by that key; iat present, a number, and in the window; exp, if present, not more than 180 seconds past. Otherwise invalid_dpop_proof.
  2. nonce, if present, a string; jti a non-empty string; htm the request's method; htu a string, a URL, http or https, with no user or password, matching the request's. Otherwise invalid_dpop_proof.
  3. nonce present: otherwise use_dpop_nonce. A nonce the server does not take: use_dpop_nonce.
  4. ath: absent at the three endpoints, the access token's hash at XRPC. Otherwise invalid_dpop_proof.
  5. The jti not seen before: otherwise invalid_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 a getSession refused for its token, sent again, is invalid_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:

NamespaceValueKept for
DPoP proofsa proof's jti, across all clients, endpoints and XRPC200 seconds
PKCEa code_challenge whose code was exchanged24 hours
statesa client's state, kept as the SHA-256 of its client_id and state, so each entry is of one size whatever their length24 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:

ParameterIs
client_idrequired, non-empty
response_typerequired: code
redirect_urione of the client's redirect URIs; may be left out when the client has exactly one
scoperequired: one left out is refused at step 11 below, as a scope without atproto
staterequired, non-empty
code_challenge, code_challenge_methodrequired: PKCE (RFC 7636) with S256
login_hintoptional: a handle or a DID, in any case
promptoptional: none, login, consent, select_account or create
response_modeoptional: query (the default), fragment or form_post
ui_localesoptional: language tags as fr-CA en (each [a-z]{2,3} with an optional -[A-Z]{2}, separated by single spaces)
displayoptional: page, popup, touch or wap
max_ageoptional: an integer, 0 or more
dpop_jktoptional: 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:

  1. The body, as above.

  2. client_id present and non-empty: else invalid_client.

  3. The parameters' forms: response_type one of code, token, none, code id_token token, code id_token, code token, id_token token, id_token; redirect_uri, if given, an https: URL, an http: URL on 127.0.0.1 or [::1] (never localhost), or a private-use scheme URI (com.example.app:/path); scope a scope string as above; code_challenge_method S256 or plain; prompt, response_mode, ui_locales, display, max_age as above; login_hint non-empty; id_token_hint and claims, if given, a JWT and a JSON object; else invalid_request.

  4. The DPoP proof, as above: required here (else 401 invalid_dpop_proof).

  5. The client: its client_id as under "Clients".

  6. dpop_jkt, if given, the proof's key's thumbprint: else 401 invalid_token, with WWW-Authenticate: DPoP … error="invalid_token".

  7. claims, id_token_hint or nonce given: invalid_request.

  8. response_type not code: unsupported_response_type.

  9. Every scope token one the client's metadata declares: else invalid_scope. redirect_uri one of the client's, or left out when it has exactly one: else invalid_request.

  10. code_challenge_method given without code_challenge, or no code_challenge: invalid_request.

  11. scope left out, or without atproto: invalid_scope; with openid: invalid_scope.

  12. code_challenge_method not S256: invalid_request.

  13. prompt=none: invalid_request (a public client may not sign in silently).

  14. login_hint neither a handle nor a DID, once lower-cased: invalid_request.

  15. An include: scope whose set does not resolve, or is not a set (OAUTH-PERMISSION-SETS.md, "At PAR"): invalid_scope.

  16. state missing or empty, or the same as one this client gave in the last 24 hours: invalid_request.

  17. A request larger than the server keeps: invalid_request. That is a client_id longer than 18470 bytes, a state longer than 1024, a code_challenge that is not 43 characters (an S256 challenge always is, so no verifier matches another), a redirect_uri or login_hint longer than 2048, a scope longer than 4096, or ui_locales of more than 16 tags. The reference keeps them whatever their length, up to its body's 100 KiB (probed: a state of 100000 bytes and a code_challenge of 10000 are kept).

    Note: 18470 is the longest loopback client_id naming one redirect_uri of 2048 bytes and a scope of 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).

  18. 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 is 429 with error: 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 of atproto/permission.md that parse (below), and the include: 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: create if given create, else consent, 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:

ResourceParameters (positional first)Values
repocollection (one or more, required), action (any of)an NSID or *; create, update, delete
rpclxm (one or more, required), aud (required)an NSID or *; a DID with a # service fragment, or *; not both *
blobaccept (one or more, required)a MIME type type/subtype, type/* or */*
accountattr (required), actionemail, repo or status; read or manage
identityattr (required)handle or *
spacespaceType (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:

  1. client_id and request_uri present: else a 400 error page invalid_request. A request_uri that is not urn:ietf:params:oauth:request_uri: and an id: 400 error page invalid_request.
  2. The client: a client_id refused as under "Clients" is a 400 error page with that error.
  3. The request: one the server does not keep (never made, or ended) is a 400 error page invalid_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) with error=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 also uiLocales (the request's, as given), loginHint and selectedDid when they have values. scope and promptMode are the request's, as kept; permissionSets is as OAUTH-PERMISSION-SETS.md says ({} for a scope with no include:). loginHint is the request's login_hint, but the handle of the account it names if it is the DID of an account here. selectedDid is the DID of the account signed in on this device that login_hint names by DID or handle, if one is, and only when promptMode is consent: with create there is none. spaces and spaceHandles are there when the scope, with what its sets grant, has a space permission, as OAUTH-SCOPES.md says ("Spaces", "On the authorization page").
  • __sessions: the accounts signed in on this device and remembered (below), each {account, loginRequired}, in any order. loginRequired is true once 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"}:

  1. Sec-Fetch-Mode: same-origin and Sec-Fetch-Site: same-origin.
  2. Origin, if present, the issuer's.
  3. Referer: the issuer's origin, path /oauth/authorize, and a request_uri query parameter of the form above. The call is then for that request. (passkey-register takes the passkey page's instead, PASSKEYS.md, "passkey-register".)
  4. The x-csrf-token header and the csrf-token cookie both present and equal.
  5. Content-Type: application/json (else 415, with the same body), and the body: at most 102400 bytes, as PAR's (else 413, 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 with remember left 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 has ephemeralToken too: 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:

  1. A request the server keeps: else 400 invalid_request, and no url.
  2. 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.
  3. did signed in on this device, or the ephemeral token as above: else invalid_request.
  4. The narrowed scope has atproto: else access_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: 303 to redirect_uri with them in its query;
  • fragment: 303 to redirect_uri with them as its fragment, encoded as a query is;
  • form_post: 200 HTML 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:

  1. The body, as for PAR.
  2. client_id present and non-empty: else invalid_grant.
  3. grant_type authorization_code, refresh_token, password or client_credentials, with that grant's fields: for authorization_code, code (non-empty), redirect_uri (a redirect URI of the form above) and code_verifier (optional: 43 to 128 of A-Za-z0-9-._~); for refresh_token, refresh_token (non-empty). Else invalid_grant.
  4. The DPoP proof, as above.
  5. The client, as under "Clients".
  6. A DPoP proof present: else 401 invalid_dpop_proof.
  7. grant_type authorization_code or refresh_token: else invalid_grant.

The code grant then checks, all invalid_grant:

  1. code one 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 a 400 error page, and the API answers 400), whatever follows. A code whose request a change of its account's state ended is spent (LIFECYCLE.md, "OAuth sessions").
  2. Its request's client is this one; the proof's key is the request's.
  3. redirect_uri is the request's, as kept.
  4. code_verifier present, and its SHA-256, base64url, is the request's code_challenge.
  5. That code_challenge not exchanged before (single-use values).
  6. 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:

  1. refresh_token a session's: its current one, or one it had before. Neither: refused.
  2. One it had before (a replaced refresh token): refused, and the session ends.
  3. The session's client is this one, and the proof's key is the session's: else refused, and the session ends.
  4. 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:

  1. With a DPoP header, the proof, as under "DPoP": 401 invalid_dpop_proof or 401 use_dpop_nonce.
  2. The access token one the server issued, at any time: else 401 invalid_token.
  3. A DPoP header: else 401 invalid_dpop_proof.
  4. The proof's key the one the token was issued for: else 401 invalid_token.
  5. The token its session's current one, the session not ended, and the token not past its expires_in: else 401 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 referenceThe specThe server
takes a PAR with no DPoP proof, binding the key at the token requestatproto/oauth.md: clients must start DPoP at PAR401 invalid_dpop_proof
takes a PAR without state, or with an empty oneatproto/oauth.md: state is required400 invalid_request
takes a state the client used beforeatproto/oauth.md: servers should reject duplicate states400 invalid_request for the same client within 24 hours
takes a parameter twice, the last winningRFC 6749 §3.1: parameters must not be repeated400 invalid_request
issues access tokens for 60 minutesatproto/oauth.md: access tokens should live less than 30 minutes15 minutes (expires_in: 900)
serves an authorization request given on the page's URL, without PARRFC 9126 §5 with require_pushed_authorization_requestsa 400 error page
keeps a PAR's state, code_challenge and other parameters of any length, up to 100 KiB, and any number of requestsnone: the server's own bounds400 invalid_request past PAR's step 17, 429 past step 18
limits its sign-in in no waynone: the server's own boundthe 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 bounda 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 getSession whose 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 getSession with the old and new access tokens.
  • revoke: a session's current or replaced token, then getSession and 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: true on the first: whether the sign-in gave the device new cookies (of those but csrf-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 __sessions compared.
  • the client library: authorize, the page, callback, getSession through its session, a refresh, signOut, and restore after it.
  • crashes: before each kill, a fresh nonce and a getSession for some sessions, compared; after the restart, that getSession's proof sent again (a replay on both sides), a getSession with the nonce given before the kill and no retry, and sometimes a refresh. Where the getSession before 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 to invalid_token alone 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 algs and error_description of WWW-Authenticate, and error_description and message anywhere.
  • Two refreshes at once with one token: which lands first is a race.
  • __customizationData, and the rest of a page's HTML here: --pages checks the pages in a browser (OAUTH-PAGES.md).