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:readorphotos:read): an application cannot annotate, change or share what it cannot read. drive:shareneedsdrive: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_idisrp-and 12 base64url characters.registration_access_tokenandregistration_client_urimanage the registration (§5). Keep the token secret; it is not issued again.client_id_issued_atis 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:
429with{ "error": "temporarily_unavailable", "error_description": "too many registrations from this network; try again later" }(or "…is at capacity…"), withoutRetry-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".