replace big-tech and host basic infrastructure yourself! ordner.fyi
ordner docs developers discovery.md
6.7 kB · 185 lines
Markdown
at main

Discovery #

An application starts from what the person tells it: an email address (pip@example.org) or the install's address (https://ordner.example). From there it finds, without any configuration of its own, the JMAP session and the authorization server that issues tokens for it.

1. From an email address to the install #

The install publishes an SRV record for each mail domain it serves (RFC 8620 §2.2, RFC 6186):

_jmap._tcp.example.org. 3600 IN SRV 0 1 443 ordner.example.

The target and port name the install's origin, https://ordner.example. An application that was given an address looks up _jmap._tcp.<domain>; one that was given the origin skips this step. A domain that publishes no record (or a target of .) has no JMAP: the application asks the person for the install's address instead.

2. The session URL #

GET https://ordner.example/.well-known/jmap answers 301 with the session URL in Location; the application follows it with its credentials (RFC 8620 §2.2). Without credentials the session answers 401:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="mail", charset="UTF-8", Bearer realm="jmap", resource_metadata="https://ordner.example/.well-known/oauth-protected-resource"

The resource_metadata parameter of the Bearer challenge (RFC 9728 §5.1) names the protected-resource metadata: an application finds the authorization server from the JMAP URL alone. Every 401 of the install's JMAP carries it. (This answer comes from the install's origin in front of the files service; it is described here, not executed by the examples.)

3. The protected resource (RFC 9728) #

GET /.well-known/oauth-protected-resource HTTP/1.1
host: ordner.example
HTTP/1.1 200 OK
content-type: application/json

{
  "resource": "https://ordner.example",
  "authorization_servers": [
    "https://ordner.example/auth"
  ],
  "scopes_supported": [
    "drive:read",
    "drive:annotate",
    "drive:write",
    "drive:share",
    "drive:faces",
    "photos:read",
    "photos:annotate",
    "photos:write"
  ],
  "bearer_methods_supported": [
    "header"
  ]
}
  • resource is the origin: JMAP, its upload, download and EventSource URLs.
  • authorization_servers holds one issuer, the install's own, always <origin>/auth.
  • scopes_supported are the data scopes an application may ask for (Signing in §1). The identity scopes (openid, profile, email, offline_access) are the authorization server's.
  • bearer_methods_supported is ["header"]: a token goes in Authorization: Bearer …, never in a query string or a form.

4. The authorization server (RFC 8414) #

The issuer https://ordner.example/auth has a path, so its metadata is at /.well-known/oauth-authorization-server/auth on the origin (RFC 8414 §3.1). The same document is also served at https://ordner.example/auth/.well-known/openid-configuration (OpenID Connect Discovery). The example shows the members an application uses; the document holds more.

GET /.well-known/oauth-authorization-server/auth HTTP/1.1
host: ordner.example
HTTP/1.1 200 OK
content-type: application/json

{
  "issuer": "https://ordner.example/auth",
  "authorization_endpoint": "https://ordner.example/auth/authorize",
  "token_endpoint": "https://ordner.example/auth/token",
  "jwks_uri": "https://ordner.example/auth/jwks",
  "userinfo_endpoint": "https://ordner.example/auth/userinfo",
  "revocation_endpoint": "https://ordner.example/auth/revoke",
  "registration_endpoint": "https://ordner.example/auth/register",
  "device_authorization_endpoint": "https://ordner.example/auth/device/code",
  "response_types_supported": [
    "code"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token",
    "urn:ordner:oauth:grant-type:app-password",
    "urn:ietf:params:oauth:grant-type:device_code"
  ],
  "code_challenge_methods_supported": [
    "S256"
  ],
  "authorization_response_iss_parameter_supported": true,
  "token_endpoint_auth_methods_supported": [
    "none",
    "client_secret_post",
    "client_secret_basic"
  ],
  "id_token_signing_alg_values_supported": [
    "ES256",
    "RS256"
  ],
  "scopes_supported": [
    "openid",
    "profile",
    "email",
    "offline_access",
    "drive:read",
    "drive:annotate",
    "drive:write",
    "drive:share",
    "drive:faces",
    "photos:read",
    "photos:annotate",
    "photos:write"
  ],
  "resource_indicators_supported": true
}

An application reads, and never hard-codes:

Member Used for
registration_endpoint registering (Registration)
authorization_endpoint, token_endpoint the code flow with PKCE
device_authorization_endpoint the device grant
revocation_endpoint signing out
jwks_uri checking ID token signatures
code_challenge_methods_supported always ["S256"]: plain is refused

Other members: userinfo_endpoint, introspection_endpoint (for the install's own services: it needs a client secret, which an application never has), response_types_supported ["code"], response_modes_supported ["query"], subject_types_supported ["public", "pairwise"], prompt_values_supported (none, login, consent, select_account), claims_supported, resource_indicators_supported true, and request_parameter_supported, request_uri_parameter_supported and claims_parameter_supported, all false. There is no end_session_endpoint: an application signs out by revoking its refresh token (Signing in §6).

5. In short #

  1. Address → SRV _jmap._tcp.<domain> → origin (or the origin as given).
  2. GET <origin>/.well-known/jmap without credentials → 401 → resource_metadata.
  3. RFC 9728 document → authorization_servers[0] = issuer.
  4. RFC 8414 document at <origin>/.well-known/oauth-authorization-server<issuer path>.
  5. Register, sign in, then GET <origin>/.well-known/jmap with the token → the session (JMAP for this API §1).

The reference client does exactly this (The reference client).