livery_auth_oidc (livery v0.13.0)

View Source

OIDC provider discovery.

discover/1,2 fetches an issuer's /.well-known/openid-configuration document and returns it as a decoded map (notably jwks_uri, issuer, authorization_endpoint, token_endpoint). Feed the jwks_uri to livery_auth_jwks:keys/1 to get verification keys. discover_oauth/1,2 does the same for an OAuth 2.0 authorization server's metadata (RFC 8414).

The document's issuer must be exactly the issuer you passed, as OpenID Connect Discovery 1.0 section 4.3 requires. Otherwise you get {error, issuer_mismatch}, or {error, invalid_discovery} when it names none.

Deviations: only issuer is checked; the other REQUIRED metadata fields are returned as the provider sent them. See AGENTS.md, Known deviations.

The HTTP fetch is pluggable via fetch => fun((Url) -> {ok, Body} | {error, _}); the default uses livery_auth_jwks:default_fetch/1 (hackney).

{ok, Cfg}  = livery_auth_oidc:discover(<<"https://issuer.example">>),
JwksUri    = maps:get(<<"jwks_uri">>, Cfg),
{ok, Keys} = livery_auth_jwks:keys(JwksUri).

Summary

Types

config()
opts()

Functions

discover(Issuer)

Fetch and parse the OIDC discovery document for an issuer.

discover(Issuer, Opts)
discover_oauth(Issuer)

Fetch and parse an OAuth 2.0 authorization server's metadata (RFC 8414) for an issuer. Same checks and errors as discover/2.

discover_oauth(Issuer, Opts)
oauth_well_known_url(Issuer)

Build the RFC 8414 metadata URL for an issuer. The well-known segment goes between the host and the issuer's path (RFC 8414 3.1), so https://as.example/tenant becomes https://as.example/.well-known/oauth-authorization-server/tenant.

well_known_url(Issuer)

Build the discovery URL for an issuer (handles a trailing slash).

Types

config()

-type config() :: #{binary() => term()}.

opts()

-type opts() :: #{fetch => fun((binary()) -> {ok, binary()} | {error, term()})}.

Functions

discover(Issuer)

-spec discover(binary()) -> {ok, config()} | {error, term()}.

Fetch and parse the OIDC discovery document for an issuer.

discover(Issuer, Opts)

-spec discover(binary(), opts()) -> {ok, config()} | {error, term()}.

discover_oauth(Issuer)

-spec discover_oauth(binary()) -> {ok, config()} | {error, term()}.

Fetch and parse an OAuth 2.0 authorization server's metadata (RFC 8414) for an issuer. Same checks and errors as discover/2.

discover_oauth(Issuer, Opts)

-spec discover_oauth(binary(), opts()) -> {ok, config()} | {error, term()}.

oauth_well_known_url(Issuer)

-spec oauth_well_known_url(binary()) -> binary().

Build the RFC 8414 metadata URL for an issuer. The well-known segment goes between the host and the issuer's path (RFC 8414 3.1), so https://as.example/tenant becomes https://as.example/.well-known/oauth-authorization-server/tenant.

well_known_url(Issuer)

-spec well_known_url(binary()) -> binary().

Build the discovery URL for an issuer (handles a trailing slash).