Attesto.LogoutToken (Attesto v0.13.0)

Copy Markdown View Source

Mint OpenID Connect Back-Channel Logout logout_tokens (OpenID Connect Back-Channel Logout 1.0 §2.4).

A logout token is the signed JWT an OP POSTs to a Relying Party's backchannel_logout_uri to tell it a session has ended. It is a distinct artifact from the Attesto.IDToken and Attesto.Token this library also mints: its JOSE header typ is the dedicated logout+jwt (so an RP can reject anything else presented at its logout endpoint), and it carries an events claim naming the back-channel-logout event rather than identity or authorization claims.

Like Attesto.IDToken, minting is pure: it reads only the Attesto.Config passed in, signs through the same keystore/kid/RS256 path, and funnels the JOSE call through the shared internal JWS signer so the alg whitelist lives in one place.

Claims (Back-Channel Logout 1.0 §2.4)

Every minted logout token carries:

  • iss - the configured issuer.
  • aud - the OAuth client_id of the Relying Party (as in an ID Token).
  • iat - issued-at, unix seconds.
  • jti - a unique identifier, so an RP can detect a replayed token.
  • events - a JSON object with the single member "http://schemas.openid.net/event/backchannel-logout" mapped to an empty object, identifying this as a back-channel logout request.

At least one of:

  • sub - the subject whose session(s) ended.
  • sid - the session id that ended (the same value that rode in the ID Token's sid claim).

Per §2.4 a logout token MUST NOT contain a nonce claim; this module never emits one. An exp is included with a deliberately short lifetime so a captured token cannot be replayed indefinitely (the spec leaves exp optional; including a short one is strictly safer for a conforming RP).

Targeting sub vs sid

Back-Channel Logout 1.0 §2.4 requires a logout token to identify the session by sub, sid, or both, and an RP advertises via backchannel_logout_session_required whether it needs sid. Supply both when known; supply :sid for an RP that requires session-scoped logout and :sub for one that logs out every session for the subject.

Summary

Types

mint_error()
mint_opts()

Functions

event_uri()

The back-channel-logout events URI (Back-Channel Logout 1.0 §2.4).

header_typ()

The JOSE header typ logout tokens carry: "logout+jwt".

mint(config, client_id, opts \\ [])

Mint a signed Back-Channel Logout token addressed to the Relying Party identified by client_id (which becomes aud, as in an ID Token).

Types

mint_error()

@type mint_error() :: :invalid_client_id | :missing_subject_identifier

mint_opts()

@type mint_opts() :: [
  sub: String.t(),
  sid: String.t(),
  now: DateTime.t() | non_neg_integer(),
  lifetime: pos_integer(),
  jti: String.t()
]

Functions

event_uri()

@spec event_uri() :: String.t()

The back-channel-logout events URI (Back-Channel Logout 1.0 §2.4).

header_typ()

@spec header_typ() :: String.t()

The JOSE header typ logout tokens carry: "logout+jwt".

mint(config, client_id, opts \\ [])

@spec mint(Attesto.Config.t(), String.t(), mint_opts()) ::
  {:ok, String.t()} | {:error, mint_error()}

Mint a signed Back-Channel Logout token addressed to the Relying Party identified by client_id (which becomes aud, as in an ID Token).

Options:

  • :sub - the subject whose session ended.
  • :sid - the session id that ended (matches the ID Token sid). At least one of :sub / :sid MUST be supplied (:missing_subject_identifier otherwise).
  • :jti - override the generated unique identifier (a fresh CSPRNG value is used otherwise).
  • :now - DateTime or unix-seconds clock override. Defaults to now.
  • :lifetime - positive seconds; may only shorten the short default.

Returns {:ok, logout_token} (compact JWS) or {:error, reason}.