AshAuthentication.Oauth2Server.CIMD.Fetcher behaviour (ash_authentication_oauth2_server v0.3.0)

Copy Markdown View Source

Behaviour for fetching OAuth Client ID Metadata Documents.

A Client ID Metadata Document (CIMD) client identifies itself with an HTTPS URL as its client_id; the authorization server fetches the JSON metadata document from that URL. This behaviour is the extension point for how that fetch happens — the default implementation is AshAuthentication.Oauth2Server.CIMD.ReqFetcher, which applies an SSRF-safe outbound policy.

Swap in your own module via the :cimd_fetcher option on your Oauth2Server module when you need a different outbound policy (an egress proxy, an allowlist of client hosts, a stub for tests, etc.).

Summary

Types

result()

A successful fetch.

Callbacks

fetch(url, opts)

Fetch and JSON-decode the metadata document at url.

Types

result()

@type result() :: %{document: map(), cache_ttl: non_neg_integer() | nil}

A successful fetch.

  • :document — the decoded JSON object (a map with string keys). Validation of its contents happens in AshAuthentication.Oauth2Server.CIMD — the fetcher only guarantees it retrieved and decoded a JSON object.
  • :cache_ttl — seconds the document may be cached for, derived from the response's Cache-Control header. nil means the response carried no caching directives (the caller applies its default); 0 means the response asked not to be cached.

Callbacks

fetch(url, opts)

@callback fetch(url :: String.t(), opts :: keyword()) ::
  {:ok, result()} | {:error, term()}

Fetch and JSON-decode the metadata document at url.

opts is the server's :cimd_fetch_options config, passed through verbatim — implementations define their own option set.