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