ReqDPoP (ReqDPoP v0.5.0)

Req plugin for OAuth 2.0 DPoP client proof generation.

Attach the plugin to a Req.Request with attach/2:

key = ReqDPoP.Key.generate(:es256)

client =
  Req.new(base_url: "https://api.example.com")
  |> ReqDPoP.attach(key: key, access_token: access_token)

Req.get!(client, url: "/resource")

To use proof-only mode for token endpoint requests, omit :access_token.

Summary

Types

alg()

attach_option()

clock()

jti()

proof_option()

Functions

attach(request, opts)

Attaches DPoP proof generation to a Req.Request.

proof(opts)

Builds a compact DPoP proof JWT.

proof!(opts)

Builds a compact DPoP proof JWT or raises ReqDPoP.Error.

Types

alg()

@type alg() :: :es256 | :rs256

attach_option()

@type attach_option() ::
  proof_option()
  | {:retry_on_nonce, boolean()}
  | {:max_nonce_retries, non_neg_integer()}

clock()

@type clock() :: (-> integer()) | (Req.Request.t() -> integer())

jti()

@type jti() :: (-> binary()) | (Req.Request.t() -> binary())

proof_option()

@type proof_option() ::
  {:key, ReqDPoP.Key.t() | JOSE.JWK.t() | map()}
  | {:access_token,
     binary() | (-> binary() | nil) | (Req.Request.t() -> binary() | nil)}
  | {:nonce,
     binary() | (-> binary() | nil) | (Req.Request.t() -> binary() | nil)}
  | {:clock, clock()}
  | {:jti, jti()}
  | {:alg, alg()}

Functions

attach(request, opts)

@spec attach(Req.Request.t(), [attach_option()]) :: Req.Request.t()

Attaches DPoP proof generation to a Req.Request.

Options:

:key - required DPoP private key. Accepts ReqDPoP.Key, JOSE.JWK, or a JWK map.
:access_token - optional token string or function. When present, the plugin adds Authorization: DPoP ... and computes the proof ath claim.
:nonce - optional static nonce or function.
:retry_on_nonce - retries once on DPoP nonce challenges by default.
:max_nonce_retries - defaults to 1.
:clock - injectable Unix-second clock for tests.
:jti - injectable JTI generator for tests.
:alg - :es256 by default. :rs256 is also supported.

proof(opts)

@spec proof([proof_option() | {:htm, binary() | atom()} | {:htu, binary()}]) ::
  {:ok, binary()} | {:error, ReqDPoP.Error.t()}

Builds a compact DPoP proof JWT.

Required options are :key, :htm, and :htu. :access_token adds ath; :nonce adds nonce.

proof!(opts)

@spec proof!([proof_option() | {:htm, binary() | atom()} | {:htu, binary()}]) ::
  binary()

Builds a compact DPoP proof JWT or raises ReqDPoP.Error.