Skip to content

OAuth: web, native and confidential clients

OAuth: the authorization server 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's OAuth spec, “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: the authorization server says holds for these clients too, where this page does not say otherwise: what this page adds to a step of OAuth: the authorization server’s checks, it says where in that order it comes.

This section is informative.

FileDescriptionLicence
the client ID metadata document draftOAuth Client ID Metadata Document (draft 00)IETF Trust
RFC 7523JWT profile for OAuth client authenticationIETF Trust

and those OAuth: the authorization server lists, atproto's OAuth spec above all (“Clients”, “Confidential Client Authentication”, “Tokens and Session Lifetime”, “Authorization Interface”).

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's OAuth spec: “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: the authorization server) nor one of these is 400 invalid_client_metadata, as OAuth: the authorization server says.

Fetching it. The client’s metadata is the JSON document at its client_id: the server sends GET <client_id>, 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 (Proxying, service auth and preferences, “SSRF protection”): only from hosts that resolve to public unicast addresses (draft-client-id-metadata-document §6.5, atproto's OAuth spec “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:

FieldTypeIf absent
client_ida non-empty stringrefused
redirect_urisa non-empty array of redirect URIs (below)refused
response_typesa 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_typesa 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"]
scopea scope string, as OAuth: the authorization server defines onerefused
token_endpoint_auth_methodone of client_secret_basic, client_secret_jwt, client_secret_post, none, private_key_jwt, self_signed_tls_client_auth, tls_client_authclient_secret_basic
token_endpoint_auth_signing_alga string
jwksan object whose keys is an array
jwks_urian https URL (as a redirect URI’s, below)
application_typeweb or nativeweb
subject_typepublic or pairwisepublic
client_namea string
client_urian https URL (as a redirect URI’s)
logo_uri, tos_uri, policy_urian https URL (as a redirect URI’s)
contactsan array of email addresses
dpop_bound_access_tokensa booleanrefused
authorization_signed_response_alga stringRS256
request_object_signing_alg, authorization_encrypted_response_alga string
require_auth_time, tls_client_certificate_bound_access_tokensa boolean
authorization_encrypted_response_encA128CBC-HS256
authorization_details_typesan array of strings
default_max_agea number
userinfo_signed_response_alg, userinfo_encrypted_response_alg, id_token_signed_response_alga 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's OAuth spec: “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's OAuth spec, “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: the authorization server 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: the authorization server, “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.

Redirect URIs. A request’s redirect_uri matches one of the document’s as OAuth: the authorization server says: equal, character for character, or, if both are loopback URLs and the registered one has no port, equal but for the port. OAuth: the authorization server’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.

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's OAuth spec, “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's OAuth spec 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's OAuth spec: 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: the authorization server). Its access tokens live as long as a public client’s.

atproto's OAuth spec (“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: the authorization server) 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 (Account lifecycle).

When the authorization page loads a request of a confidential client (OAuth: the authorization server’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 (Account lifecycle), 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: the authorization server’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: the authorization server 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: the authorization server’s “The redirect” sends it, in the request’s response_mode, with iss and state: a 303, or the form_post page.

OAuth: the authorization server’s single-use values gain a namespace:

NamespaceValueKept for
client assertionsa confidential client’s assertion jti, per client2 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 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 jtis, until their time. Kept documents and JWKS do not survive, as said under “Keeping it”.

VariableDescription
PDS_OAUTH_CLIENT_FETCHfor 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 <origin>=<base URL>, 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

Section titled “Where the reference departs from the specs”

The reference PDS does these, which the specs this page rests on say otherwise; the server follows the specs, and the harness does not compare them, but holds the server to this page:

The referenceThe specThe server
takes a document answered with any 2xx status, as 201atproto's OAuth spec: the status must be 200400 invalid_client_metadata
takes token_endpoint_auth_signing_alg: "none"atproto's OAuth spec: none is never allowed400 invalid_client_metadata
takes an http: jwks_uri, logo_uri, tos_uri or policy_uri on a loopback hostatproto's OAuth spec: only https:400 invalid_client_metadata
takes a native client’s https redirect URI on another originatproto's OAuth spec: the same origin as the client_id400 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.

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: the authorization server’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 (Account lifecycle) 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: the authorization server 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: the authorization server, 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.