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"
]
}
resourceis the origin: JMAP, its upload, download and EventSource URLs.authorization_serversholds one issuer, the install's own, always<origin>/auth.scopes_supportedare 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_supportedis["header"]: a token goes inAuthorization: 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 #
- Address → SRV
_jmap._tcp.<domain>→ origin (or the origin as given). GET <origin>/.well-known/jmapwithout credentials →401→resource_metadata.- RFC 9728 document →
authorization_servers[0]= issuer. - RFC 8414 document at
<origin>/.well-known/oauth-authorization-server<issuer path>. - Register, sign in, then
GET <origin>/.well-known/jmapwith the token → the session (JMAP for this API §1).
The reference client does exactly this (The reference client).