# 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/` | 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:`, 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": "", "authorization_servers": [""], "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 `` is the issuer: | Field | Value | | --- | --- | | `issuer` | `` | | `authorization_endpoint` | `/oauth/authorize` | | `token_endpoint` | `/oauth/token` | | `revocation_endpoint` | `/oauth/revoke` | | `pushed_authorization_request_endpoint` | `/oauth/par` | | `jwks_uri` | `/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` | `[""]` | | `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": "", "scope": "", "redirect_uris": [""], "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="", 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=""`. `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: `, 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:", "expires_in": 300}`, where `` 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=&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 `