livery_auth_introspect (livery v0.2.0)

View Source

OAuth 2.0 token introspection middleware (RFC 7662).

Verifies opaque bearer tokens that cannot be checked locally by POSTing them to the authorization server's introspection endpoint and trusting the active field of the JSON response. On success the full introspection response (claims such as scope, client_id, username, sub, exp) is stored as meta(user, _) (read it back with livery_ext:user/1). On any failure it short-circuits with 401 Unauthorized.

Use this for reference/opaque tokens; for self-contained JWTs prefer local verification with livery_auth_bearer.

State:

{livery_auth_introspect, #{
    endpoint      => <<"https://issuer.example/oauth/introspect">>,
    client_id     => <<"my-api">>,
    client_secret => <<"s3cret">>,
    required      => true
}}

client_id/client_secret authenticate this resource server to the introspection endpoint via HTTP Basic. The HTTP call is pluggable via fetch => fun((Url, Headers, Body) -> {ok, Status, Body} | {error, _}); the default uses hackney.

Summary

Types

error_reason()
fetch_fun()
opts()

Functions

call(Req, Next, State)
default_fetch(Url, Headers, Body)

Default introspection POST using hackney, verifying the server's TLS cert.

introspect(Token, Opts)

Introspect a token at the configured endpoint.

Types

error_reason()

-type error_reason() ::
          inactive | invalid_response | invalid_json | {http_status, non_neg_integer()} | term().

fetch_fun()

-type fetch_fun() ::
          fun((binary(), [{binary(), binary()}], binary()) ->
                  {ok, non_neg_integer(), binary()} | {error, term()}).

opts()

-type opts() ::
          #{endpoint := binary(),
            client_id => binary(),
            client_secret => binary(),
            token_type_hint => binary(),
            required => boolean(),
            fetch => fetch_fun()}.

Functions

call(Req, Next, State)

-spec call(livery_req:req(), livery_middleware:next(), map()) -> livery_resp:resp().

default_fetch(Url, Headers, Body)

-spec default_fetch(binary(), [{binary(), binary()}], binary()) ->
                       {ok, non_neg_integer(), binary()} | {error, term()}.

Default introspection POST using hackney, verifying the server's TLS cert.

introspect(Token, Opts)

-spec introspect(binary(), opts()) -> {ok, map()} | {error, error_reason()}.

Introspect a token at the configured endpoint.

Returns the introspection response map when the token is active, {error, inactive} when it is not, and other {error, _} reasons on transport or decoding failure.