AttestoClient.Discovery (AttestoClient v0.6.0)

Copy Markdown View Source

Fetch and read OAuth 2.0 / OpenID Connect authorization-server metadata (RFC 8414 / OpenID Connect Discovery 1.0).

A thin lookup: it fetches the discovery document (and, separately, the JWKS) and returns the parsed JSON. It runs no flow and holds no state - the host reads the endpoint URLs and capabilities it needs (and, for verifying JARM responses, passes the fetched JWKS to AttestoClient.JARM.verify/3).

URL construction

By default the OpenID Connect Discovery document is fetched by appending /.well-known/openid-configuration to the issuer (OpenID Connect Discovery 1.0 §4). Pass well_known: :oauth_authorization_server for the RFC 8414 document, which is constructed differently: the well-known segment is inserted before the issuer's path component (RFC 8414 §3.1), so it is correct for path-based (multi-tenant) issuers.

Issuer / transport validation

  • The issuer MUST be an https URL with no query or fragment (RFC 8414 §2).
  • The document's own issuer member MUST equal the issuer it was fetched from (RFC 8414 §3.3), defending against a metadata mix-up. A trailing slash on the supplied issuer is normalised away for both the request and this comparison.
  • A JWKS is fetched only over https, since it is the trust root for verifying the authorization server's signatures.

HTTP

Requests go through Req. Pass :req_options to configure it - notably plug: for Req.Test in tests.

Summary

Types

error()
opt()
well_known()

Functions

fetch(issuer, opts \\ [])

Fetch the authorization server's metadata for issuer, returning {:ok, metadata} (a string-keyed map) or {:error, reason}.

fetch_jwks(jwks_uri, opts \\ [])

Fetch a JWKS document from jwks_uri (typically the metadata's jwks_uri), returning {:ok, jwks} - a map with a "keys" list - or {:error, reason}. The URI must be https.

Types

error()

@type error() ::
  :invalid_issuer
  | :invalid_well_known
  | :invalid_jwks_uri
  | :issuer_mismatch
  | :invalid_metadata
  | :blocked_host
  | {:http_status, pos_integer()}
  | {:transport, term()}

opt()

@type opt() :: {:well_known, well_known()} | {:req_options, keyword()}

well_known()

@type well_known() :: :openid_configuration | :oauth_authorization_server

Functions

fetch(issuer, opts \\ [])

@spec fetch(String.t(), [opt()]) :: {:ok, map()} | {:error, error()}

Fetch the authorization server's metadata for issuer, returning {:ok, metadata} (a string-keyed map) or {:error, reason}.

issuer must be an https URL with no query or fragment. Options: :well_known (:openid_configuration (default) or :oauth_authorization_server) and :req_options (forwarded to Req).

fetch_jwks(jwks_uri, opts \\ [])

@spec fetch_jwks(String.t(), [opt()]) :: {:ok, map()} | {:error, error()}

Fetch a JWKS document from jwks_uri (typically the metadata's jwks_uri), returning {:ok, jwks} - a map with a "keys" list - or {:error, reason}. The URI must be https.