@spec emit_telemetry(Plug.Conn.t(), Plug.opts()) :: Plug.Conn.t()

Emit telemetry events after token verification.

Should be placed immediately before verify_no_auth_error/2 in the pipeline. See Charon.Telemetry for details on the emitted events.

@spec get_token_from_auth_header(Plug.Conn.t(), any()) :: Plug.Conn.t()

Get a bearer token from the authorization header.

Extracts tokens from headers in the format "Bearer <token>" or "Bearer: <token>". If a valid token is found, it's stored in the connection's private state along with the transport type (:bearer).

Doctests / examples

iex> conn()
...> |> put_req_header("authorization", "Bearer super.secure.token")
...> |> get_token_from_auth_header([])
...> |> Utils.get_bearer_token()
"super.secure.token"

@spec get_token_from_cookie(Plug.Conn.t(), String.t()) :: Plug.Conn.t()

Get the token or token signature from a cookie.

If a bearer token was previously found by get_token_from_auth_header/2, the cookie contents are appended to it if:

• the cookie starts with a dot
• the token ends in a dot (for backwards compatibility)

If no bearer token was previously found, the cookie contents are used as the full token.

Doctests / examples

iex> conn()
...> |> put_req_cookie("access_cookie", "super.secure.token")
...> |> fetch_cookies()
...> |> get_token_from_cookie("access_cookie")
...> |> Utils.get_bearer_token()
"super.secure.token"

@spec load_session(Plug.Conn.t(), Charon.Config.t()) :: Plug.Conn.t()

Fetch the session to which the bearer token belongs. Raises on session store error.

Must be used after verify_token_signature/2.

Requires the token payload to contain "sub", "sid", and "styp" claims. If the session is found, it's stored in the conn's private state. If not found, an authentication error is set.

@spec verify_no_auth_error(Plug.Conn.t(), (Plug.Conn.t(), String.t() -> Plug.Conn.t())) ::
  Plug.Conn.t()

Make sure that no previous plug of this module added an auth error. In case of an error, on_error is called (it should probably halt the connection).

Doctests / examples

iex> conn = conn()
iex> verify_no_auth_error(conn, fn _conn, _error -> raise "BOOM" end)

# on error, send an error response
iex> on_error = fn conn, error -> conn |> send_resp(401, error) |> halt() end
iex> %{halted: true, resp_body: "oops!"} =
...> conn()
...> |> Utils.set_auth_error("oops!")
...> |> verify_no_auth_error(on_error)

@spec verify_session_payload(Plug.Conn.t(), verifier()) :: Plug.Conn.t()

Verify the session payload. The validation function verifier receives the conn and the session, and must return the conn or an error message.

Must be used after load_session/2.

Doctests / examples

iex> verifier = fn conn, session -> if session.uid == 2, do: conn, else: "not user 2" end
iex> conn()
...> |> Utils.set_session(%{uid: 1})
...> |> verify_session_payload(verifier)
...> |> Utils.get_auth_error()
"not user 2"

@spec verify_token_claim(
  Plug.Conn.t(),
  {claim_name(), verifier()}
  | %{required(claim_name()) => verifier()}
  | keyword(verifier())
) :: Plug.Conn.t()

Verify that the bearer token payload contains claim and that its value matches verifier, which receives the conn and the claim value, and must return the conn or an error message. Also accepts a map/keyword of claims and verifiers.

Must be used after verify_token_signature/2.

Doctests

def verify_read_scope(conn, value) do
  if "read" in String.split(value, ","), do: conn, else: "no read scope"
end

iex> conn()
...> |> Utils.set_token_payload(%{"scope" => "write"})
...> |> verify_token_claim(scope: &verify_read_scope/2)
...> |> Utils.get_auth_error()
"no read scope"

@spec verify_token_claim_equals(Plug.Conn.t(), claims_and_expectations()) ::
  Plug.Conn.t()

Verify that the bearer token payload contains claim and that its value is expected. Also accepts a map/keyword of claims and expected values.

Must be used after verify_token_signature/2.

Doctests / examples

iex> conn()
...> |> Utils.set_token_payload(%{"type" => "access"})
...> |> verify_token_claim_equals(type: "refresh")
...> |> Utils.get_auth_error()
"bearer token claim type invalid"

@spec verify_token_claim_in(Plug.Conn.t(), claims_and_expectations()) :: Plug.Conn.t()

Verify that the bearer token payload contains claim and that its value is in expected. Also accepts a map/keyword of claims and lists of expected values.

Must be used after verify_token_signature/2.

Doctests / examples

iex> conn()
...> |> Utils.set_token_payload(%{"uid" => 1, "type" => "access"})
...> |> verify_token_claim_in(uid: 1..20, type: ["id", "refresh"])
...> |> Utils.get_auth_error()
"bearer token claim type invalid"

@spec verify_token_exp_claim(Plug.Conn.t(), Plug.opts()) :: Plug.Conn.t()

Verify that the bearer token payload contains a non-expired exp (expires at) claim.

Must be used after verify_token_signature/2.

Note that a token created by Charon.SessionPlugs.upsert_session/3 is guaranteed to have an exp claim that does not outlive its underlying session.

Allows for some clock drift (5 seconds).

@spec verify_token_fresh(Plug.Conn.t(), pos_integer()) :: Plug.Conn.t()

Verify that the token (either access or refresh) is fresh.

A token is fresh if it belongs to the current or previous refresh generation. A generation is a set of tokens that is created within new_cycle_after seconds after the first token in the generation is created. A token created after new_cycle_after seconds starts a new generation.

It would be simpler to just have a single fresh (refresh) token. However, because of refresh race conditions caused by network issues or misbehaving clients, enforcing only a single fresh token causes too many problems in practice.

In addition to this generation mechanism, 5 seconds of clock drift are allowed.

Must be used after load_session/2. Verify the token type with verify_token_claim_equals/2.

Freshness example

New cycle is created 5 seconds after the generation's first token is created, and token TTL is 24h (which is irrelevant in this example).

@spec verify_token_nbf_claim(Plug.Conn.t(), Plug.opts()) :: Plug.Conn.t()

Verify that the bearer token payload contains a valid nbf (not before) claim.

Must be used after verify_token_signature/2.

Allows for some clock drift (5 seconds).

@spec verify_token_ordset_claim_contains(Plug.Conn.t(), claims_and_expectations()) ::
  Plug.Conn.t()

Verify that the bearer token payload contains claim, which is assumed to be an :ordsets, and that ordset (which is also assumed to be either an ordset or a single element) is a subset of that ordset.

Also accepts a map/keyword of claims and expected ordsets.

Doctests / examples

iex> conn()
...> |> Utils.set_token_payload(%{"scope" => ["a", "b", "c"]})
...> |> verify_token_ordset_claim_contains({"scope", "a"})
...> |> Utils.get_auth_error()
nil

iex> conn()
...> |> Utils.set_token_payload(%{"scope" => ["a", "b", "c"]})
...> |> verify_token_ordset_claim_contains(scope: ["c", "d", "e"])
...> |> Utils.get_auth_error()
"bearer token claim scope does not contain [d, e]"

@spec verify_token_payload(Plug.Conn.t(), verifier()) :: Plug.Conn.t()

Verify the bearer token payload. The validation function verifier receives the conn and the token payload, and must return the conn or an error message.

Must be used after verify_token_signature/2.

Doctests / examples

iex> verifier = fn conn, payload -> is_map_key(payload, "sub") && conn || "no sub claim" end
iex> conn()
...> |> Utils.set_token_payload(%{"id" => 1})
...> |> verify_token_payload(verifier)
...> |> Utils.get_auth_error()
"no sub claim"

@spec verify_token_signature(Plug.Conn.t(), Charon.Config.t()) :: Plug.Conn.t()

Verify that the bearer token found by get_token_from_auth_header/2 is signed correctly, using the configured token factory.

If verification succeeds, the token payload is stored in the connection's private state. If verification fails, an authentication error is set instead.