Contracts¶
The core, rn_forge.auth, is a set of contracts and the values they exchange.
This guide walks them in the order a request meets them; the
overview shows how they connect. For tokens, see
Token profiles; for server-side state, see Stores.
Identity providers and external identities¶
An IdentityProvider[RequestT] is one login method, generic over the
framework's native request type. It has an id and a kind (ProviderKind:
"oidc", "oauth2", "password" or "development") and three methods:
begin(request, *, return_to)returns aLoginStart: theLoginTransactionto persist and theredirect_urlto send the browser to, orNonewhen the provider takes a form instead, as password login does.complete(request, transaction)validates the provider's response against the transaction and returns anExternalIdentity.logout_redirect(session, *, post_logout_redirect)returns the provider's logout URL, orNonefor a local logout only.
ExternalIdentity is a verified identity asserted by a provider: provider,
issuer, subject, and optionally email, email_verified, name,
picture, groups, attributes, auth_time, amr and session_ref (the
OIDC sid). Everything after this value is framework-neutral.
LoginTransaction is the state of one login in flight (state, nonce,
code_verifier, return_to), saved in a TransactionStore between begin and
complete.
SessionInfo is what a login session stores: the internal account_id, the
session_version at login, how the user authenticated, and expires_at. It
holds no permissions; they are looked up per request (see
Authorization context).
Account resolution¶
An AccountResolver maps an ExternalIdentity to an internal account ID.
resolve(identity) links, provisions or rejects a login and returns the account
ID; it raises AccountRejected when the login may not proceed.
lookup(issuer, subject) returns the linked account ID, or None, and never
provisions.
AccountRejected carries a reason for logs. The user is never shown it: the
callback sends one of the CallbackError codes instead (see
Return targets, the session body and callback errors).
Authorization context and cache¶
An AuthorizationContext is an account's current authorization data: active
(whether it may authenticate), session_version, permissions, roles (a
display hint and an input to your provider) and attributes (inputs to
attribute-based rules such as tenant or location). An
AuthorizationContextProvider returns it from an account ID with
resolve(account_id).
A session holds only the account ID and its session_version. On each request
the binding fetches the current context, checks active and that the session's
version still matches, and builds the Principal from the context. Revoking a
permission, deactivating an account or bumping the session version therefore
takes effect on the next request, with no session to edit.
link_bearer_principal and session_principal project account state into a
Principal; session_to_record/session_from_record and
transaction_to_record/transaction_from_record define the persisted shapes.
fixed_window_seconds, fixed_window_key and fixed_window_retry_after
provide shared fixed-window arithmetic.
Caching contexts¶
AuthorizationContextCache wraps an AuthorizationContextProvider so a request
does not recompute the account's permissions every time. It keeps one entry per
account in process memory and serves it while the account's authorization
version and the global version are unchanged and the entry is younger than the
TTL (60 seconds by default).
cache = AuthorizationContextCache(provider, ttl=timedelta(seconds=30), writer=writer)
cache.invalidate("acct-1") # one account's permissions changed
cache.invalidate_all() # a role definition or an import changed many
cache.set_active("acct-1", False) # writer, then invalidate
new_version = cache.bump_session_version("acct-1")
Use set_active and bump_session_version for the two values that revoke
access, so no cached context outlives the change; they need an
AccountStateWriter that the application implements. A change made behind the
cache's back, such as a direct database edit, applies once the TTL passes.
The default InMemoryAuthorizationVersions is not shared across processes, so
with several workers a bump reaches only the worker that made it and the others
rely on the TTL. A shared AuthorizationVersions implementation fixes that.
Principal and Requirement¶
Principal is the verified caller, a frozen dataclass. subject is the only
required field. permissions holds the effective permissions, scopes the
token's delegated scopes (empty for a session), and roles, tenant and
attributes the application's authorization data. mechanism is "session",
"bearer" or "basic" and defaults to "bearer"; claims keeps every
verified claim; external_subject, auth_time and amr record how the caller
authenticated.
Requirement is a declarative access check with four frozen sets. The sets are
ANDed together; the members of an any_* set are ORed:
| Field | Satisfied when |
|---|---|
any_scope |
empty, or the principal holds at least one of them |
all_scopes |
the principal holds every one of them |
any_permission |
empty, or the principal's permissions include at least one of them |
all_permissions |
the principal's permissions include every one of them |
An empty Requirement() is satisfied by any principal: it means
"authenticated", not "denied". Routes require permissions, never roles; the
scope clauses can only narrow access further.
from rn_forge.auth import Principal, Requirement
requirement = Requirement(any_scope=frozenset({"orders:read", "orders:admin"}))
caller = Principal(subject="u-1", scopes=frozenset({"orders:read"}))
requirement.is_satisfied_by(caller) # True
Permissions and the scope limit¶
requirement_for builds the requirement for a resource key and an action:
requirement_for("orders", "partial_update") requires orders.update.
DEFAULT_PERMISSION_ACTION_MAP maps the action names; an action_map argument
overrides entries of it, and an action named by neither map is used as is.
A token's scopes limit, and never grant, permissions. effective_permissions
returns a session or basic caller's account permissions unchanged, and for a
bearer caller keeps only the permissions that its scopes allow through your
scope map. A scope the map does not name allows nothing.
from rn_forge.auth import effective_permissions, requirement_for
permissions = effective_permissions(
frozenset({"orders.read", "orders.update"}),
mechanism="bearer",
scopes=frozenset({"orders:read"}),
scope_map={"orders:read": frozenset({"orders.list", "orders.read"})},
) # frozenset({"orders.read"})
requirement_for("orders", "partial_update") # needs orders.update: denied
Authenticators and authorizers¶
The contracts are runtime-checkable protocols.
Authenticator.authenticate(*, credentials)turns aCredentialsinto aPrincipal.AsyncAuthenticatoris the awaitable counterpart. A failure raisesrn_forge.web.AuthenticationFailed; its message must not say which part of the credentials was wrong.Authorizer.authorize(principal, *, requires)returns when the request may proceed and raisesrn_forge.web.PermissionDeniedwhen it may not. It never raisesAuthenticationFailed: the caller is already authenticated, which is the line between 401 and 403.
ScopeAuthorizer is the shipped Authorizer. It evaluates the Requirement
and raises PermissionDenied with a fixed message. Pass log to be told about
each refusal; it is called as log("authorization.denied", context), where
context holds subject, mechanism and required.
from rn_forge.auth import ScopeAuthorizer
authorizer = ScopeAuthorizer(log=lambda message, context: print(message, context))
authorizer.authorize(caller, requires=requirement)
Mapping claims to a principal¶
principal_from_claims(claims, *, mechanism="bearer") is the default mapping
from already-verified claims:
| Principal | Claim |
|---|---|
subject |
sub, required |
issuer |
iss |
scopes |
scope (space-delimited string) and scp (string or list), combined |
roles |
roles (a list) |
tenant |
tid |
It raises AuthenticationFailed when sub is missing or empty. A claim of the
wrong type for issuer or tenant is ignored, not an error.
An identity provider that keeps roles elsewhere, such as Keycloak's
realm_access.roles, needs its own mapping. Any callable from verified claims
to a Principal works; Principal.claims still holds the whole token:
from dataclasses import replace
from rn_forge.auth import Principal, principal_from_claims
def keycloak_principal(claims: dict[str, object]) -> Principal:
principal = principal_from_claims(claims)
realm = claims.get("realm_access")
roles = realm.get("roles", ()) if isinstance(realm, dict) else ()
return replace(principal, roles=frozenset(str(role) for role in roles))
Hand it to OidcAuthenticator as claims_to_principal.
Resource policy¶
A Requirement decides whether a caller may reach a route. A ResourcePolicy
decides what the caller may do with a particular object or set of objects:
allows(principal, action, resource)returns whether the principal may perform the action on one resource.scope(principal, action, query)returns the query narrowed to what the principal may perform the action on, such as a queryset filtered by tenant.
It is generic over the resource and query types, so the application chooses both. The core supplies the protocol only.
Return targets, the session body and callback errors¶
validate_return_to accepts a return_to only when it is a relative path under
one of the configured prefixes, matched on whole segments:
from rn_forge.auth import InvalidReturnTo, validate_return_to
try:
target = validate_return_to(raw, prefixes=["/app"])
except InvalidReturnTo:
target = "/app"
It rejects absolute and scheme-relative URLs, backslashes, control characters,
percent-encoded slashes, backslashes and dots in the path, .. segments and
paths outside the prefixes. A query string and fragment may follow the path. The
caller falls back to a default on InvalidReturnTo.
SessionBody.build(session, context, name=..., email=..., picture=...) makes
the /auth/session body; subject is the internal account ID. to_json()
returns camelCase keys, RFC 3339 UTC timestamps, sorted roles, permissions
and amr, and leaves out absent optional fields. The keys of attributes are
converted from snake_case to camelCase at every depth.
CallbackError is the closed list of codes a failed callback sends to the error
route: access_denied, account_not_provisioned and login_failed.