Client ID Metadata Documents - CIMD
(draft-ietf-oauth-client-id-metadata-document-03, IETF OAuth WG).
CIMD lets a client identify itself with no prior registration by using an
HTTPS URL as its client_id. The authorization server dereferences that URL
to fetch a JSON client metadata document - the RFC 7591 Dynamic Client
Registration metadata field set - and uses it as the client.
This module is the pure, conn-free, HTTP-free half of that feature: it
decides whether a client_id is a CIMD URL (client_id_url?/1), validates
the URL against the draft §3 grammar (validate_client_id/1), and validates a
fetched document against the draft §4 / §5 content rules, normalizing it into
the client shape attesto's resolution expects (validate_document/2). The
load-bearing network half - the SSRF-guarded GET, redirect refusal, size cap,
and caching - lives in the Phoenix layer; this module never touches a socket
and pulls in no dependencies, the same discipline as
Attesto.AuthorizationRequest.
URL grammar (draft §3)
A CIMD client_id MUST:
- use the
httpsscheme; - have a path component other than
/; - NOT contain a fragment;
- NOT contain userinfo (a
user:password@component); - NOT contain single-dot (
.) or double-dot (..) path segments.
Ports are allowed; a query is discouraged but allowed. A client_id that is
not a binary, or does not parse as a URL, is not a CIMD client_id - it is an
opaque identifier the host resolves through its own registry.
Document content (draft §4 / §5)
The fetched document's fields are the OAuth Dynamic Client Registration
Metadata registry values (RFC 7591 §2), plus
token_endpoint_auth_methods_supported (OpenID RP Metadata Choices). On top
of that field set the draft requires:
- a
client_idmember equal to the URL by simple string comparison (mismatch ->{:error, :client_id_mismatch}); - NO shared symmetric secret:
client_secret/client_secret_expires_atMUST NOT be present ({:error, :symmetric_secret}), and neithertoken_endpoint_auth_methodnortoken_endpoint_auth_methods_supportedmay containclient_secret_basic,client_secret_post, orclient_secret_jwt({:error, :symmetric_auth_method}) - a CIMD client authenticates as a public client (none+ PKCE) or withprivate_key_jwt; - when both
token_endpoint_auth_methods_supportedandtoken_endpoint_auth_methodare present, the singular value MUST appear intoken_endpoint_auth_methods_supported; when neither is present, the client's method defaults tonone(never RFC 7591'sclient_secret_basic); jwksandjwks_uriMUST NOT both be present (RFC 7591 / draft §4.1), and at least one of them MUST be present whenprivate_key_jwtis declared (draft §5).
Authorization-code and implicit grants require a non-empty redirect_uris
array of strings. A document explicitly declaring only grants that do not
redirect, such as client_credentials, may omit it; normalization supplies
an empty list. A missing grant_types retains the RFC 7591 default of
authorization_code and therefore still requires redirect URIs.
An inline JWK Set must contain public asymmetric keys only. Private JWK
members and symmetric keys yield {:error, :private_key_material}.
Normalized client shape
validate_document/2 returns a string-keyed map carrying the RFC 7591 §2
client-metadata members the document supplied (client_id, redirect_uris,
and any of grant_types, response_types, scope, jwks, jwks_uri,
client_name, client_uri, logo_uri, token_endpoint_auth_methods_supported,
token_endpoint_auth_method, contacts). The shape matches the validated
metadata the RFC 7591 registration path persists, so a CIMD client is consumed
downstream (scope resolution, redirect match, JARM, DPoP) exactly like a
registered one. Absent members are omitted rather than rendered as nil; an
out-of-shape member (e.g. a redirect_uris that is not a list of strings) is
a validation error, never silently dropped.
Summary
Types
A reason a fetched document fails the draft §2 content rules.
A reason a client_id URL fails the draft §2 grammar.
Functions
Return the token endpoint authentication methods declared by a CIMD metadata
document (draft-ietf-oauth-client-id-metadata-document-03 §5).
Returns true iff value is a CIMD client_id: a binary that parses as an
HTTPS URL satisfying the draft §2 grammar (a path, and no fragment, userinfo,
or single-/double-dot path segments).
Validate a client_id against the CIMD URL grammar
(draft-ietf-oauth-client-id-metadata-document-03 §3).
Validate a fetched client metadata document against the draft §4 / §5 content rules and normalize it into attesto's client shape.
Check CIMD verification keys for private or symmetric key material.
Types
@type document_error() ::
:client_id_mismatch
| :symmetric_secret
| :symmetric_auth_method
| :invalid_redirect_uris
| :invalid_metadata
| :private_key_material
A reason a fetched document fails the draft §2 content rules.
@type url_error() ::
:not_a_url
| :not_https
| :no_path
| :has_fragment
| :has_userinfo
| :dot_segments
A reason a client_id URL fails the draft §2 grammar.
Functions
Return the token endpoint authentication methods declared by a CIMD metadata
document (draft-ietf-oauth-client-id-metadata-document-03 §5).
Prefers token_endpoint_auth_methods_supported over singular
token_endpoint_auth_method. When neither property is present, assumes
["none"] (RFC 7591's client_secret_basic default MUST NOT be applied).
Returns true iff value is a CIMD client_id: a binary that parses as an
HTTPS URL satisfying the draft §2 grammar (a path, and no fragment, userinfo,
or single-/double-dot path segments).
This is the fast, allocation-light predicate the resolver uses to decide
whether a client_id is a CIMD URL before any network work; a client_id
that is not a binary, or fails the grammar, returns false. For the specific
failure reason use validate_client_id/1.
Validate a client_id against the CIMD URL grammar
(draft-ietf-oauth-client-id-metadata-document-03 §3).
Returns {:ok, %URI{}} for a well-formed CIMD client_id, or
{:error, reason} for the first rule it violates:
:not_a_url- not parseable as a URL with a host;:not_https- the scheme is nothttps;:no_path- no path component or bare/(draft §3 forbids/);:has_fragment- a fragment is present;:has_userinfo- auser:password@userinfo component is present;:dot_segments- the path contains a single-dot (.) or double-dot (..) segment.
The checks run in that order, so the returned reason is the first the URL fails. A query is permitted (discouraged by the draft, not rejected here).
@spec validate_document(String.t(), map()) :: {:ok, map()} | {:error, document_error()}
Validate a fetched client metadata document against the draft §4 / §5 content rules and normalize it into attesto's client shape.
client_id is the URL the document was fetched from (already validated by
validate_client_id/1); doc is the decoded JSON object. Returns
{:ok, metadata} - a string-keyed map carrying the validated, normalized
RFC 7591 §2 / CIMD metadata members - or {:error, reason}:
:client_id_mismatch-doc["client_id"]is not equal toclient_idby simple string comparison (draft §4);:symmetric_secret-client_secretorclient_secret_expires_atis present (draft §4.1: no shared symmetric secret);:symmetric_auth_method-token_endpoint_auth_methodortoken_endpoint_auth_methods_supportednamesclient_secret_basic,client_secret_post, orclient_secret_jwt(draft §4.1 / §5);:invalid_redirect_uris-redirect_urisis absent, empty, or not a list of strings (RFC 9700 / draft §4.2 require registered redirect URIs for redirect-based grants);:invalid_metadata- a carried-through member is present with the wrong shape,jwksandjwks_uriare both present (draft §4.1),token_endpoint_auth_methodis not included intoken_endpoint_auth_methods_supported(draft §5), orprivate_key_jwtis declared with neitherjwksnorjwks_uri(draft §5).
The returned map always carries client_id and redirect_uris; any of the
other metadata members the document supplied
(grant_types, response_types, scope, jwks, jwks_uri, client_name,
client_uri, logo_uri, token_endpoint_auth_methods_supported,
token_endpoint_auth_method, contacts) are carried through, and absent
members are omitted.
@spec validate_public_jwks(term()) :: :ok | {:error, :private_key_material | :invalid_metadata}
Check CIMD verification keys for private or symmetric key material.
Applies draft 02 §4.1 to embedded jwks and to a fetched jwks_uri response.
Unknown public key types are retained; consumers select usable keys separately.