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
LoginFlowin thern_forge.authcore owns the login transaction. It validatesreturn_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 inLoginFailedwith aCallbackErrorcode. The bindings mount it; the adapters stayIdentityProviderimplementations over the thinLoginRequestprotocol (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 thekeycloakservice ofrn-forge-auth, declared in itspyproject.tomland run by the generated CI'sintegrationjob; no repo-owned workflow remains (S16.3.1). - Owner decision, 2026-10-28: the
oidcextra declaresrequests, which Authlib'sOAuth2Sessionneeds and Authlib does not declare.
S13.4.1 — OIDC adapter
State: Closed (2026-10-28)
Acceptance:
rn_forge.auth.oidcholds anIdentityProviderover Authlib'sOAuth2SessionandCodeIDTokenthat 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 inlogin_failed: a wrongiss, a missingisswhen discovery advertisesauthorization_response_iss_parameter_supported, a UserInfosubthat differs from the ID token's, a replayed callback, a callback with another browser's transaction, and an ID token older thanmax_age. The first three use the fake'sresponse_iss,response_iss_missinganduserinfo_sub_mismatchswitches, 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_redirectreturns the provider'send_session_endpointwithid_token_hintandpost_logout_redirect_uriwhen RP-initiated logout is enabled, andNoneotherwise.- 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 onlysubis present. - Tests reject a logout token with
nonce, a replayedjti, a staleiatand 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
ExternalIdentitywithissuer="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).