Skip to content

F13.4 — Protocol adapters

State Closed
Parent E13
Iteration Release 7
Start Date 2026-10-28
Closed Date 2026-10-28
Predecessors F13.3
Source Owner decision, 2026-10-26

Stories: 6 Closed · 1 Removed

Story State Depends on
S13.4.1 — OIDC adapter Closed (2026-10-28) —
S13.4.2 — OAuth 2.0-only providers Closed (2026-10-28) —
S13.4.3 — Logout Closed (2026-10-28) —
S13.4.4 — SAML adapter Removed —
S13.4.5 — Local password and development adapters Closed (2026-10-28) —
S13.4.6 — Broker profile job Closed (2026-10-28) —
S13.4.7 — Document the adapters Closed (2026-10-28) —

The login methods, each ending in an ExternalIdentity: OIDC and OAuth 2.0, local passwords and the development provider. SAML IdPs reach the app through a broker, as an ordinary OIDC provider.

Context

The library evaluation made pykit's adapters the owner of every login flow on both frameworks (Login flow owners), over Authlib's core and not its framework integrations. pykit binds no SAML library (SAML identity providers). The bindings (F13.5, F13.6) mount the adapters; the login guide describes them.

Decisions

  • Owner decision, 2026-10-27: a neutral LoginFlow in the rn_forge.auth core owns the login transaction. It validates return_to, saves the transaction for 600 seconds, consumes it once by the handle in the transaction cookie, checks that it belongs to the provider, and ends every failure in LoginFailed with a CallbackError code. The bindings mount it; the adapters stay IdentityProvider implementations over the thin LoginRequest protocol (query, form).
  • Owner decision, 2026-10-27: the Keycloak broker job (S13.4.6) runs from a repo-owned workflow beside main.yml, so it survives the kiln cutover (F16.3), and from the same docker compose file on a developer's machine. It is not a required check. Revised 2026-11-07 (kiln S7.2.4): the broker profile becomes the keycloak service of rn-forge-auth, declared in its pyproject.toml and run by the generated CI's integration job; no repo-owned workflow remains (S16.3.1).
  • Owner decision, 2026-10-28: the oidc extra declares requests, which Authlib's OAuth2Session needs and Authlib does not declare.

S13.4.1 — OIDC adapter

State: Closed (2026-10-28)

Acceptance:

  • rn_forge.auth.oidc holds an IdentityProvider over Authlib's OAuth2Session and CodeIDToken that runs the flow in OIDC login: discovery with the issuer check, state, nonce, PKCE S256, and a login transaction saved for 600 seconds and consumed once.
  • Against the fake OIDC IdP, a login succeeds and returns the expected ExternalIdentity, and each of these ends in login_failed: a wrong iss, a missing iss when discovery advertises authorization_response_iss_parameter_supported, a UserInfo sub that differs from the ID token's, a replayed callback, a callback with another browser's transaction, and an ID token older than max_age. The first three use the fake's response_iss, response_iss_missing and userinfo_sub_mismatch switches, which S13.3.8 left to these tests.
  • Claim mapping has a default and an application hook. Upstream access and refresh tokens are discarded unless an application hook receives them.
  • A test captures the log records of every flow above and finds no token, code or verifier in them.

S13.4.2 — OAuth 2.0-only providers

State: Closed (2026-10-28)

Acceptance:

  • A provider with no ID token is served by the same adapter over Authlib's client: it calls the provider's user endpoint over the back channel and maps the result to an ExternalIdentity.
  • Tests against the fake IdP in OAuth 2.0 mode cover success and a failed user call.

S13.4.3 — Logout

State: Closed (2026-10-28)

Acceptance:

  • logout_redirect returns the provider's end_session_endpoint with id_token_hint and post_logout_redirect_uri when RP-initiated logout is enabled, and None otherwise.
  • A back-channel logout handler validates the token under the logout-token profile and returns which (issuer, sid) to revoke, or which account's session version to bump when only sub is present.
  • Tests reject a logout token with nonce, a replayed jti, a stale iat and an ID token offered in its place.

S13.4.4 — SAML adapter

State: Removed

pykit speaks no SAML; a SAML IdP federates through a broker (S13.1.5).

S13.4.5 — Local password and development adapters

State: Closed (2026-10-28)

Acceptance:

  • The password adapter takes a verifier and returns an ExternalIdentity with issuer="local". A wrong password and an unknown account fail with the same error, in tests.
  • The development adapter lists fixture accounts in stable, documented markup and accepts the account as a parameter. It refuses to be constructed unless the caller declares debug mode, in a test.
  • Neither needs an extra.

S13.4.6 — Broker profile job

State: Closed (2026-10-28)

Acceptance:

  • An optional CI job runs a Keycloak container and completes an OIDC login, one federated from a SAML IdP inside Keycloak, and a client-credentials bearer call through the adapter (Testing).
  • The job is not a required check and does not gate merges.

S13.4.7 — Document the adapters

State: Closed (2026-10-28)

Acceptance:

  • rn-forge-auth's guides cover each adapter, its extra and its configuration, and how to connect a SAML IdP through a broker.
  • The changelog records the adapters. Both strict MkDocs builds pass.

Acceptance

  • The OIDC and OAuth 2.0 adapters over Authlib's core pass every fake-IdP failure case (S13.4.1, S13.4.2).
  • RP-initiated and back-channel logout work under the logout-token profile (S13.4.3).
  • The password and development adapters exist with no extra (S13.4.5).
  • The optional Keycloak job runs and does not gate merges (S13.4.6).
  • The adapters are documented (S13.4.7).
uv run --package rn-forge-auth pytest packages/rn-forge-auth
uv run lint-imports
uv run pyright
sh docs/_update_board.sh --check