replace big-tech and host basic infrastructure yourself! ordner.fyi
ordner docs developers registration.md
12 kB · 302 lines
Markdown
at main

Registration #

An application registers itself with each install it talks to, without an administrator, by Dynamic Client Registration (RFC 7591). The install offers one tier of automatic registration: native applications with loopback redirects, public clients that prove themselves with PKCE and never hold a secret (RFC 8252). An agent on a server, with no browser, uses the same registration and signs in with the device grant.

1. One registration per installation #

A registration is made by one copy of the application on one device, once, and kept: the application stores client_id and registration_access_token with its other settings and reuses them for every sign-in. It does not register on every start: registrations are limited (§4), and the person's consent, their pairwise subject and everything the application wrote are tied to the client_id — a new registration is a new application to the person, with a new sub, a new consent and a new source.

2. The request #

POST to the registration_endpoint with a JSON body:

POST /auth/register HTTP/1.1
host: ordner.example
content-type: application/json

{
  "redirect_uris": [
    "http://127.0.0.1/callback"
  ],
  "token_endpoint_auth_method": "none",
  "grant_types": [
    "authorization_code",
    "refresh_token",
    "urn:ietf:params:oauth:grant-type:device_code"
  ],
  "scope": "openid offline_access drive:read drive:annotate drive:faces",
  "client_name": "Photo Sorter"
}
Member Required Rule
redirect_uris yes 1–5 strings, each ≤ 256 characters, each a loopback URI: scheme http (not https), host 127.0.0.1, [::1] or localhost, any port or none, any path and query, no fragment, no user info. Custom schemes and other hosts are refused.
token_endpoint_auth_method yes "none", and nothing else
grant_types no a subset of authorization_code, refresh_token, urn:ietf:params:oauth:grant-type:device_code that includes authorization_code; default ["authorization_code", "refresh_token"]
response_types no exactly ["code"]
application_type no "native"
scope no space-separated; default openid. Must hold openid; each scope one of openid, profile, email, offline_access and the data scopes (§3)
client_name no ≤ 128 characters after trimming; refused when it holds invisible or bidirectional control characters, mixes Latin, Cyrillic and Greek letters, resembles the name of one of the install's own apps, or holds a reserved word (admin, administrator, official, security, support, helpdesk, system, verified, login, sign in, signin, account, password, passkey, or the organisation's name)
id_token_signed_response_alg no one of the provider's signing algorithms; default RS256

Other RFC 7591 members (logo_uri, client_uri, software_id, software_version, contacts, tos_uri, policy_uri) are ignored: not checked, not kept, not answered. The person never sees a logo or a link of the application's, only its name, marked as unchecked.

The registered scope is the most the application may ever ask for; it asks for what it needs at each sign-in (often the same). Register the device grant (urn:ietf:params:oauth:grant-type:device_code) when the application may run without a browser.

3. The data scopes #

Scope Lets the application
drive:read read the whole drive (every file and folder, every picture's metadata, every application's annotations, faces without embeddings, vectors, suggestions), and download content
photos:read the same, confined to the Pictures folder of each drive it reaches
drive:annotate write annotations, faces, vectors, its field schema, views and album suggestions
photos:annotate the same, in Pictures only
drive:write change the drive: create, upload, move, rename, delete, edit pictures, make albums, name faces; implies drive:annotate
photos:write the same, in Pictures only
drive:share share files and albums with others
drive:faces read face embeddings, and write them with drive:annotate (biometric data)

Rules, checked at registration and again at every sign-in:

  • Every data scope needs a read scope beside it (drive:read or photos:read): an application cannot annotate, change or share what it cannot read.
  • drive:share needs drive:read.
  • No other data is reachable: mail, calendars, contacts and sending are out of reach of every application that registers itself.
POST /auth/register HTTP/1.1
host: ordner.example
content-type: application/json

{
  "redirect_uris": [
    "http://127.0.0.1/callback"
  ],
  "token_endpoint_auth_method": "none",
  "scope": "openid drive:annotate",
  "client_name": "Photo Sorter"
}
HTTP/1.1 400 Bad Request
content-type: application/json
cache-control: no-store
pragma: no-cache

{
  "error": "invalid_client_metadata",
  "error_description": "scope drive:annotate needs drive:read or photos:read beside it"
}

4. The answer #

201 Created, with Cache-Control: no-store:

HTTP/1.1 201 Created
content-type: application/json
cache-control: no-store
pragma: no-cache

{
  "client_id": "${clientId}",
  "client_id_issued_at": "${clientIdIssuedAt}",
  "redirect_uris": [
    "http://127.0.0.1/callback"
  ],
  "token_endpoint_auth_method": "none",
  "grant_types": [
    "authorization_code",
    "refresh_token",
    "urn:ietf:params:oauth:grant-type:device_code"
  ],
  "response_types": [
    "code"
  ],
  "application_type": "native",
  "scope": "openid offline_access drive:read drive:annotate drive:faces",
  "client_name": "Photo Sorter",
  "id_token_signed_response_alg": "RS256",
  "registration_client_uri": "https://ordner.example/auth/register/${clientId}",
  "registration_access_token": "${registrationAccessToken}"
}
  • client_id is rp- and 12 base64url characters.
  • registration_access_token and registration_client_uri manage the registration (§5). Keep the token secret; it is not issued again.
  • client_id_issued_at is in seconds since the epoch.
  • The other members say what was registered, defaults filled in.

Errors are 400 with { "error", "error_description" } (RFC 7591 §3.2.2): invalid_redirect_uri for a redirect URI, invalid_client_metadata for everything else, the description saying what is wrong. A body that is not a JSON object is 400 invalid_client_metadata too; send Accept: application/json to get it as JSON rather than an HTML page.

5. Limits #

  • At most 10 registrations per IPv4 address or IPv6 /64 per 24 hours, and 2,000 automatic registrations on the install in all. Over either: 429 with { "error": "temporarily_unavailable", "error_description": "too many registrations from this network; try again later" } (or "…is at capacity…"), without Retry-After. Deleting a registration frees its place in the total, not in its network's 24 hours.
  • The install's per-address request limit applies to registration as to every request that is not signed in (Errors and rate limits §4).
  • A registration nobody uses is collected: one that has issued no token 30 days after it was made is removed. Any token issued keeps it.
  • The install's administrators may ban or remove a registration; either ends every token and consent given to it at once.

6. Managing the registration (RFC 7592) #

The registration is read, replaced and removed at registration_client_uri with Authorization: Bearer <registration_access_token> (RFC 7592).

Read (GET):

GET /auth/register/${clientId} HTTP/1.1
host: ordner.example
authorization: Bearer ${registrationAccessToken}
HTTP/1.1 200 OK
content-type: application/json
cache-control: no-store

{
  "client_id": "${clientId}",
  "client_id_issued_at": "${clientIdIssuedAt}",
  "redirect_uris": [
    "http://127.0.0.1/callback"
  ],
  "token_endpoint_auth_method": "none",
  "grant_types": [
    "authorization_code",
    "refresh_token"
  ],
  "response_types": [
    "code"
  ],
  "application_type": "native",
  "scope": "openid offline_access drive:read drive:annotate drive:faces",
  "client_name": "Photo Sorter",
  "id_token_signed_response_alg": "RS256",
  "registration_client_uri": "https://ordner.example/auth/register/${clientId}",
  "registration_access_token": "${registrationAccessToken}"
}

The read answers grant_types as ["authorization_code", "refresh_token"] whatever was registered: grant types are not kept. The device grant is allowed by the registered scope (§3 of Signing in), not by this member.

Replace (PUT): the whole registration, checked as a new one; the body names the same client_id. A member left out takes its default (scope becomes openid, a client_name left out is dropped), so send everything.

PUT /auth/register/${clientId} HTTP/1.1
host: ordner.example
authorization: Bearer ${registrationAccessToken}
content-type: application/json

{
  "client_id": "${clientId}",
  "redirect_uris": [
    "http://127.0.0.1/callback"
  ],
  "token_endpoint_auth_method": "none",
  "grant_types": [
    "authorization_code",
    "refresh_token",
    "urn:ietf:params:oauth:grant-type:device_code"
  ],
  "scope": "openid offline_access drive:read drive:annotate drive:faces",
  "client_name": "Photo Sorter Desktop"
}
HTTP/1.1 200 OK
content-type: application/json
cache-control: no-store

{
  "client_id": "${clientId}",
  "client_id_issued_at": "${clientIdIssuedAt}",
  "redirect_uris": [
    "http://127.0.0.1/callback"
  ],
  "token_endpoint_auth_method": "none",
  "grant_types": [
    "authorization_code",
    "refresh_token",
    "urn:ietf:params:oauth:grant-type:device_code"
  ],
  "response_types": [
    "code"
  ],
  "application_type": "native",
  "scope": "openid offline_access drive:read drive:annotate drive:faces",
  "client_name": "Photo Sorter Desktop",
  "id_token_signed_response_alg": "RS256",
  "registration_client_uri": "https://ordner.example/auth/register/${clientId}",
  "registration_access_token": "${registrationAccessToken}"
}

Remove (DELETE): 204. Every token, refresh chain, application session and consent of the registration ends with it; what the application wrote into drives stays until the person removes it.

DELETE /auth/register/${clientId} HTTP/1.1
host: ordner.example
authorization: Bearer ${registrationAccessToken}
HTTP/1.1 204 No Content

A missing or wrong registration access token, and an unknown client, are the same 401 (invalid_token, "unknown client or bad registration access token"), with WWW-Authenticate: Bearer error="invalid_token".