livery_auth_jwks (livery v0.13.0)
View SourceJWKS fetching, parsing, and caching with key rotation.
keys/1,2 returns the JWK set for a jwks_uri, fetching it over
HTTP on first use and caching the result in persistent_term
with a TTL. refresh/1,2 forces a re-fetch: call it on a
no_matching_key verification failure to pick up a rotated key.
The HTTP fetch is pluggable via fetch => fun((Url) -> {ok, Body} | {error, _}) in the options, so deployments (and tests) can
supply their own client. The default goes through livery_client
(livery_auth:client/0) and verifies the server's TLS certificate.
{ok, Keys} = livery_auth_jwks:keys(<<"https://issuer/.well-known/jwks.json">>),
{ok, Claims} = livery_auth:verify(Token, #{keys => Keys, issuer => Iss}).Summary
Functions
Default JWKS fetcher, through livery_client (livery_auth:client/0),
verifying the server's certificate. Waits 5 seconds for the answer.
livery_auth_oidc uses it for discovery too.
Parse a JWKS document (binary or decoded map) into a key list.
JWK set for JwksUri, cached with the default 5-minute TTL.
JWK set for JwksUri. Honors fetch and ttl options.
Re-fetch JwksUri unless the cached set was fetched less than
min_refresh_interval milliseconds ago (default 30000), in which case
the cached keys are returned. Use it when a token names a key the set
does not have: a rotated key is picked up, but tokens with made-up key
ids cannot make every request fetch the set again.
Force a re-fetch of JwksUri, replacing the cached entry.
Types
-type opts() :: #{fetch => fun((binary()) -> {ok, binary()} | {error, term()}), ttl => non_neg_integer(), min_refresh_interval => non_neg_integer()}.
Functions
Default JWKS fetcher, through livery_client (livery_auth:client/0),
verifying the server's certificate. Waits 5 seconds for the answer.
livery_auth_oidc uses it for discovery too.
-spec from_json(binary() | map()) -> {ok, [livery_auth:jwk()]} | {error, term()}.
Parse a JWKS document (binary or decoded map) into a key list.
-spec keys(binary()) -> {ok, [livery_auth:jwk()]} | {error, term()}.
JWK set for JwksUri, cached with the default 5-minute TTL.
-spec keys(binary(), opts()) -> {ok, [livery_auth:jwk()]} | {error, term()}.
JWK set for JwksUri. Honors fetch and ttl options.
-spec maybe_refresh(binary(), opts()) -> {ok, [livery_auth:jwk()]} | {error, term()}.
Re-fetch JwksUri unless the cached set was fetched less than
min_refresh_interval milliseconds ago (default 30000), in which case
the cached keys are returned. Use it when a token names a key the set
does not have: a rotated key is picked up, but tokens with made-up key
ids cannot make every request fetch the set again.
-spec refresh(binary()) -> {ok, [livery_auth:jwk()]} | {error, term()}.
Force a re-fetch of JwksUri, replacing the cached entry.
-spec refresh(binary(), opts()) -> {ok, [livery_auth:jwk()]} | {error, term()}.