chadtmiller.com/monolith
An atproto PDS
0
0
# OAuth: the authorization server
The server is the OAuth authorization server for its own accounts, as
[`atproto/oauth.md`](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`](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`](PDS.md); the password sessions beside these are
in [`SESSIONS.md`](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-CLIENTS.md); OAuth access tokens on the other
methods, and what scopes allow, in [`OAUTH-SCOPES.md`](OAUTH-SCOPES.md);
what the pages show a person, and how they are built and served, in
[`OAUTH-PAGES.md`](OAUTH-PAGES.md); permission sets (`include:` scopes)
in [`OAUTH-PERMISSION-SETS.md`](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`](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`](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: *`:
```json
{"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 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:
```json
{"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:
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:
| 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:
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, if the request carries a `DPoP` header. A
request with none is taken, its DPoP key then bound at the token request
(below, "The code grant", step 2), as the reference takes it.
*Note:* this departs from `atproto/oauth.md`, which says a client must
send a proof at PAR; refusing a PAR without one, `401
invalid_dpop_proof`, is the stricter answer, and the right one. The
server takes it only because the reference does, and clients written
against the reference rely on it. It is a candidate to drop once such
clients send proofs at PAR.
5. The client: its `client_id` as under "Clients".
6. `dpop_jkt`, if given with a proof, the proof's key's thumbprint: else
`401 invalid_token`, with `WWW-Authenticate: DPoP … error="invalid_token"`.
Given without a proof, it is kept as the request's key.
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; none for a
request with neither.
- 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`](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,
where the request kept one. A request kept with no key (PAR, step 4)
takes this proof's key: the session is bound to it.
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`:
```json
{"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 first alone the server does
as the reference does, against the spec, and the harness compares it:
| 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 | takes it too, alone of these (PAR, step 4): compared, and a candidate to drop |
| 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_id`s with scopes and redirect URIs drawn from a list), scope,
`login_hint`, `prompt`, `response_mode`, identifier, `remember`, a PAR
sometimes with no DPoP proof (with or without `dpop_jkt`), 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; `error`s (`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`).