Login providers
A login provider turns a framework request into an ExternalIdentity.
LoginFlow runs the providers for a framework binding. Every provider
implements IdentityProvider, so a binding handles OIDC, OAuth 2.0, password
and development logins the same way.
| Provider | Module | Extra |
|---|---|---|
OidcProvider |
rn_forge.auth.oidc |
oidc |
OidcProvider.oauth2(...) |
rn_forge.auth.oidc |
oidc |
PasswordIdentityProvider |
rn_forge.auth.local |
none |
DevelopmentIdentityProvider |
rn_forge.auth.local |
none |
rn_forge.auth.oidc needs the oidc extra and is imported directly. The
rn_forge.auth facade re-exports LoginFlow, LoginFailed, LoginRequest and
the rn_forge.auth.local providers.
The request and the flow
A provider reads two mappings from the request: query, the URL parameters (the
IdP's callback arrives there), and form, the decoded POST fields (a password
login arrives there). A binding passes its native request when it has both, or a
small wrapper:
from dataclasses import dataclass, field
from collections.abc import Mapping
@dataclass(frozen=True)
class Request:
query: Mapping[str, str] = field(default_factory=dict)
form: Mapping[str, str] = field(default_factory=dict)
LoginFlow holds the providers by ID, a TransactionStore and the allowed
return_to prefixes:
from datetime import timedelta
from rn_forge.auth import InMemoryTransactionStore, LoginFlow
flow = LoginFlow(
{"acme": acme_provider},
InMemoryTransactionStore(),
return_to_prefixes=["/app"],
ttl=timedelta(seconds=600), # the default
)
A binding mounts two routes over it:
# GET /auth/login/acme?return_to=/app/orders
start = flow.begin("acme", request, return_to="/app/orders")
# Set a cookie holding start.transaction.id; redirect to start.redirect_url.
# GET /auth/callback/acme
login = flow.complete("acme", request, transaction_id=cookie_value)
# login.identity is the verified identity; login.return_to is where to send
# the user. Clear the cookie, resolve the account, start the session.
After complete, a binding calls admit_login to resolve the account and build
the session content and validated return_to. It uses
transaction_cookie_value for raw cookie headers and json_string_fields for
JSON login fields. The binding keeps session start, CSRF token rotation,
responses, form parsing, header access and rate limiting.
begin checks return_to with validate_return_to, asks the provider for the
redirect, and saves the transaction for the TTL. complete consumes the
transaction first, so a callback works once whatever its outcome, then rejects a
missing, expired, already used or foreign transaction (one that another provider
began) before the provider sees the response. The transaction cookie is
__Host-login-tx with HttpOnly, Secure, SameSite=Lax, Path=/ and
Max-Age=600: Lax sends it on the IdP's top-level redirect back, and the
__Host- prefix stops a sibling subdomain from planting one. Reject a callback
that carries more than one. Because the transaction binds the callback to the
browser that started it, a callback replayed in another browser fails.
Every failure is one exception, LoginFailed, with a code from
CallbackError: login_failed, or access_denied when the IdP returned
error=access_denied. Send the code to the error route and keep reason in the
logs; it names the failed check and must not reach the user. An invalid
return_to and an unknown provider are login_failed too. Any other exception
a provider raises is logged and also becomes login_failed.
OIDC
from rn_forge.auth.oidc import OidcProvider
acme_provider = OidcProvider(
id="acme",
issuer="https://login.acme.example",
client_id="orders-web",
client_secret="...",
redirect_uri="https://app.example/auth/callback/acme",
)
The provider reads the discovery document on first use and checks that it names
the configured issuer. It sends state, a nonce and a PKCE S256 challenge, and
records all three, with the verifier, on the transaction. On the callback it
requires the same state, then checks the iss parameter
(RFC 9207): a different iss fails,
and a missing one fails when discovery advertises
authorization_response_iss_parameter_supported. It then exchanges the code and
verifies the ID token with IdTokenVerifier, including the nonce and at_hash.
The secrets stay out of the logs.
| Argument | Effect |
|---|---|
scopes |
Defaults to openid email profile; openid is required |
max_age |
Sent on the authorization request; an ID token whose auth_time is older fails |
userinfo |
"auto" (default) calls UserInfo when the ID token has no email; "always" and "never" do as named. The UserInfo sub must equal the ID token's, and the ID token wins any other conflict |
claim_mapper |
Replaces default_claim_mapper |
token_hook |
Receives the identity and the upstream tokens |
rp_initiated_logout |
Lets logout_redirect return the IdP's logout URL |
token_endpoint_auth_method |
client_secret_basic by default; a public client (client_secret=None) sends none |
algorithms, leeway, timeout, fetch |
The accepted ID-token algorithms (RS256), clock skew, the back-channel timeout, and the discovery transport |
Claim mapping
default_claim_mapper fills sub, email, email_verified, name,
picture, groups, auth_time and amr, takes sid as session_ref, and
puts the remaining claims, except the token-protocol ones, in attributes. To
change that, pass a function of the provider ID and the verified claims. It may
raise LoginFailed to refuse the login:
from rn_forge.auth import ExternalIdentity, LoginFailed
from rn_forge.auth.oidc import default_claim_mapper
def acme_mapper(provider: str, claims):
identity = default_claim_mapper(provider, claims)
if not identity.email_verified:
raise LoginFailed("login_failed", "email is not verified")
return identity
Upstream tokens
pykit stores no upstream token. The access and refresh tokens are dropped after
the exchange unless the application passes a token_hook, which is called once
the login has succeeded:
def keep_tokens(identity, tokens): # tokens is an UpstreamTokens
vault.save(identity.issuer, identity.subject, tokens.refresh_token)
The tokens have no repr, so a logged UpstreamTokens does not leak them.
Logout
With rp_initiated_logout=True,
logout_redirect(session, post_logout_redirect=...) returns the discovered
end_session_endpoint with id_token_hint, post_logout_redirect_uri and
client_id. It returns None, and the binding logs out locally only, when the
flag is off, the provider advertises no endpoint, or the session kept no ID
token. A session keeps its ID token (SessionInfo.id_token) only when the
application enables RP-initiated logout: with the flag on, the provider sets
ExternalIdentity.id_token and the binding copies it into the session; with it
off the field stays None. Signing out of the app does not normally need to
sign the user out of their whole IdP session, so the flag is off by default.
OAuth 2.0 providers
A server that issues no ID token, such as GitHub, uses OidcProvider.oauth2
with explicit endpoints and a fixed issuer string. The flow keeps state and
PKCE, sends no nonce, and calls the user endpoint with the access token:
from rn_forge.auth import ExternalIdentity
from rn_forge.auth.oidc import OAuth2Endpoints, OidcProvider
def github_mapper(provider, claims):
return ExternalIdentity(
provider=provider,
issuer=claims["iss"],
subject=claims["sub"],
email=claims.get("email"),
name=claims.get("name"),
picture=claims.get("avatar_url"),
)
github = OidcProvider.oauth2(
id="github",
issuer="https://github.com",
endpoints=OAuth2Endpoints(
authorization="https://github.com/login/oauth/authorize",
token="https://github.com/login/oauth/access_token",
user="https://api.github.com/user",
),
client_id="...",
client_secret="...",
redirect_uri="https://app.example/auth/callback/github",
scopes=["read:user", "user:email"],
subject_field="id",
claim_mapper=github_mapper,
)
The user endpoint's JSON object becomes the claim set, with iss set to
issuer and sub set to the subject_field member as a string, so GitHub's
numeric id works. A user without that member fails the login. The default
mapper reads the standard names; a provider with other names (avatar_url here)
needs a mapper. The iss response check applies only when you pass
response_issuer, because most OAuth 2.0 servers send none. Such a provider has
no ID token to keep, so logout_redirect returns None, and token_hook
receives UpstreamTokens with id_token=None. A failed user call, an HTTP
error or a non-object body is login_failed.
Back-channel logout
When the user signs out at the IdP, it posts a logout token to the application.
BackchannelLogout validates it under the logout-token profile (see
Token profiles) and says what to revoke:
from rn_forge.auth import InMemoryReplayStore
from rn_forge.auth.oidc import BackchannelLogout, LogoutTokenVerifier
replay = InMemoryReplayStore()
logout = BackchannelLogout(
LogoutTokenVerifier.from_issuer(
"https://login.acme.example", client_id="orders-web", replay_store=replay
),
accounts, # an AccountResolver; only lookup() is called
)
The binding mounts POST /auth/backchannel-logout/acme, reads the form field
logout_token, and applies the result:
from rn_forge.auth.oidc import TokenVerificationError
try:
revocation = logout.handle(form["logout_token"])
except TokenVerificationError:
return response(400)
if revocation.sid is not None:
replay.revoke_sid(revocation.issuer, revocation.sid, ttl=SESSION_ABSOLUTE_TIMEOUT)
elif revocation.account_id is not None:
account_state.bump_session_version(revocation.account_id)
return response(200)
The handler changes no state of its own except the token's jti record, because
the revoked-sid lifetime (the sessions' absolute timeout) and the
session-version store belong to the binding. A token with a sid revokes that
session only. A token with only sub names the account linked to
(issuer, sub) through AccountResolver.lookup, whose session version the
binding bumps; an unlinked sub gives account_id=None and nothing to do.
Answer a failed token with 400 and log the exception message, which says which
check failed.
Password login
PasswordIdentityProvider needs no extra. The application supplies a verifier
that returns the account's stable subject, or None for an unknown account or a
wrong password:
from rn_forge.auth.local import PasswordIdentityProvider
def verify(username: str, password: str) -> str | None:
account = accounts_by_name.get(username)
return account.id if account and hasher.check(password, account.hash) else None
password = PasswordIdentityProvider(verify) # id="password"
begin returns a transaction and no redirect, since the login is a form. The
login page posts username and password, and the binding calls complete
with those form fields. The identity has issuer local and amr of {"pwd"}.
An unknown account and a wrong password fail with the same LoginFailed. Rate
limiting per account and per client belongs to the binding, and the provider
never logs or keeps the password. SSO or passkeys are preferred in production.
Development login
DevelopmentIdentityProvider lists fixture accounts so that a developer, or an
end-to-end test, signs in without a password. Construction raises
DevelopmentModeRequired unless the caller passes debug=True; wire it to the
framework's debug flag, never to a constant:
from rn_forge.auth.local import DevelopmentAccount, DevelopmentIdentityProvider
dev = DevelopmentIdentityProvider(
[
DevelopmentAccount("alice", email="alice@example.com", name="Alice"),
DevelopmentAccount("bob", groups=frozenset({"staff"})),
],
debug=settings.DEBUG,
)
html = dev.render_accounts(login_url="/auth/login/development")
render_accounts returns this markup, with every value HTML-escaped; an
end-to-end test can rely on the attributes:
<ul data-rn-forge-dev-accounts>
<li><a href="/auth/login/development?account=alice" data-account="alice">Alice</a></li>
</ul>
The link text is the account's name, or its subject when it has none. The
provider accepts the account as the account form field or query parameter, so
a test can sign in directly. The identity has issuer development and amr of
{"dev"}. An unknown account fails with LoginFailed.
Connecting a SAML IdP through a broker
pykit speaks no SAML. A SAML IdP federates through a broker (Keycloak, Entra ID,
Auth0, Okta and others), which runs the SAML exchange and then logs the user in
to the application over OIDC. The application configures the broker as one
ordinary OidcProvider; the SAML connection is the broker's configuration, not
the application's. Most workforce IdPs also speak OIDC, and a direct connection
to them needs no broker.
With Keycloak:
- Create a realm for the application and an OpenID Connect client in it (a confidential client with the standard flow, your callback URL as a valid redirect URI, and a secret).
- Under identity providers, add a SAML v2.0 provider with an alias such as
saml-idp. Give it the SAML IdP's entity ID and single sign-on URL, and require signed assertions. Import the IdP's metadata when it publishes it. - Add attribute mappers from the SAML attributes to user attributes (
email,firstName,lastName), so that they reach the ID token as claims. - Configure
OidcProviderwith the realm's issuer,https://<host>/realms/<realm>, and the client's ID and secret. To send users straight to the SAML IdP, add Keycloak'skc_idp_hint=saml-idpparameter to the redirect URL.
broker = OidcProvider(
id="keycloak",
issuer="https://sso.example/realms/acme",
client_id="orders-web",
client_secret="...",
redirect_uri="https://app.example/auth/callback/keycloak",
)
The identity's issuer is the broker, and its subject is the broker's user ID, so
an account links to (broker issuer, broker subject) whichever IdP the user
signed in through. The SAML assertion is the broker's to validate; the
application sees only the broker's signed ID token. tests/broker/ holds a
working configuration: realms/idp-realm.json is a SAML IdP, and
realms/broker-realm.json is a broker realm with the client, the SAML identity
provider and the attribute mappers above. Testing describes how to
run them.