Auth¶
rn_forge.fastapi.auth binds the login, session, CSRF and authorization design
of rn-forge-auth (a separate package, which holds the framework-neutral
contracts, login flows, session and replay stores and the OIDC adapter) to
FastAPI. It serves a browser single-page application through a server-side
session, and API clients through bearer tokens, with one account and one
authorization model behind both. rn-forge-auth documents the providers and
stores; this page documents the FastAPI side. The Django binding in
rn-forge-django serves the same routes, responses and audit events.
The session, CSRF and rate-limit state is shared by every worker, so outside
development it lives in Redis. Install rn-forge-fastapi with the redis
extra, and with oidc for OIDC login or JWKS bearer tokens.
Setup¶
An end-to-end configuration with one OIDC provider, local password login and, in development, a fixture-account provider:
# myapp/auth_config.py
from redis import Redis
from rn_forge.auth import (
AuthorizationContextCache,
DevelopmentAccount,
DevelopmentIdentityProvider,
PasswordIdentityProvider,
)
from rn_forge.auth.oidc import OidcProvider
from rn_forge.auth.redis import (
RedisAuthorizationVersions,
RedisReplayStore,
RedisSessionStore,
RedisTransactionStore,
)
from rn_forge.fastapi.auth import AuthRoutesConfig
from rn_forge.fastapi.auth.redis import RedisCsrfStore, RedisRateLimiter
from myapp.accounts import MyAccountResolver, MyAccountState, MyContexts, check_password
DEBUG = False
redis = Redis.from_url("redis://localhost:6379/0")
contexts = AuthorizationContextCache(
MyContexts(),
versions=RedisAuthorizationVersions(redis),
writer=MyAccountState(),
)
providers = {
"acme": OidcProvider(
id="acme",
issuer="https://login.example.com/tenant/v2.0",
client_id="orders-web",
client_secret="...",
redirect_uri="https://app.example.com/auth/callback/acme",
),
"password": PasswordIdentityProvider(check_password),
}
if DEBUG:
providers["development"] = DevelopmentIdentityProvider(
[DevelopmentAccount("alice", name="Alice")], debug=True
)
config = AuthRoutesConfig(
providers=providers,
accounts=MyAccountResolver(),
contexts=contexts,
account_state=contexts, # writes through to MyAccountState
problem_type_base="https://errors.example.com/",
return_to_prefixes=["/app"],
default_return_to="/app",
provider_names={"acme": "Acme SSO", "password": "Password"},
sessions=RedisSessionStore(redis),
transactions=RedisTransactionStore(redis),
replay=RedisReplayStore(redis),
csrf=RedisCsrfStore(redis),
limiter=RedisRateLimiter(redis),
trusted_origins=["https://app.example.com"],
debug=DEBUG,
)
Mount the router and the middleware:
# myapp/main.py
from rn_forge.fastapi import FastApiApp, SessionMiddleware, auth_router
from rn_forge.fastapi.auth import sessions_for
from myapp.auth_config import config
app = FastApiApp(...)
app.add_middleware(SessionMiddleware, sessions=sessions_for(config))
app.include_router(auth_router(config))
sessions_for(config) builds the Sessions from the same stores and timeouts
as the routes, so the middleware and the routes agree. SessionMiddleware
resolves the session once per request and runs the CSRF check; a router mounted
without it is unprotected, and current_principal raises RuntimeError for a
session request. add_middleware wraps the application, so the middleware added
last is outermost. Add SessionMiddleware before the middleware that should
also decorate its responses (security headers, CORS), so a csrf-failed
rejection, which the middleware answers itself, carries them.
When the router is mounted under a prefix other than /auth, tell the
middleware the paths it has special rules for:
app.add_middleware(
SessionMiddleware,
sessions=sessions_for(config),
untouched_paths=["/api/auth/session"],
login_path="/api/auth/login/password",
csrf_exempt_prefixes=["/api/auth/backchannel-logout/"],
)
app.include_router(auth_router(config, prefix="/api/auth"))
The session cookie is Secure, so serve development over localhost or HTTPS.
Routes and responses¶
auth_router(config, prefix="/auth") serves these routes under the prefix. It
is left out of the OpenAPI document. A 401 from any of them is a
problem+json response with no WWW-Authenticate header.
| Method | Path | Response |
|---|---|---|
GET |
providers |
200, a list of {id, name, kind}. kind is oidc, oauth2, password or development; the development provider is listed only with debug=True |
GET |
login/{provider}?return_to= |
302 to the identity provider, with the __Host-login-tx cookie. A return_to outside return_to_prefixes is replaced by default_return_to. An unknown provider is 404; login/password is 405 |
GET |
login/development?account= |
With debug=True only (otherwise 404): without account, an HTML list of the fixture accounts; with it, signs in and redirects to return_to |
GET |
callback/{provider} |
302 to return_to, or to the error route; 429 when rate limited |
GET |
session |
200 with the session body, or 401. Always sets the CSRF cookie |
POST |
logout |
200 {"redirect": url or null}; 401 without a session |
POST |
logout/all |
200 {"redirect": null}; 401 without a session |
POST |
backchannel-logout/{provider} |
200; 400 for an invalid logout token; 404 for a provider with no handler |
POST |
login/password |
200 with the session body, 401 for any failure, or 429 |
A callback error redirects to error_route (/auth/error) with ?error= set
to one of access_denied, account_not_provisioned and login_failed. Details
go to the log, never into the URL. A password login failure is one 401
whatever its cause, so the response does not reveal which accounts exist. The
login body is JSON or form-encoded {username, password}.
The session body is camelCase: subject (the account ID), provider, roles,
permissions, attributes, authTime, amr and expiresAt (the absolute
timeout). Session responses carry Cache-Control: no-store.
The login transaction lives in its store for 10 minutes behind the
__Host-login-tx cookie (HttpOnly, Secure, SameSite=Lax, Path=/, no
Domain). A callback that carries more than one transaction cookie is rejected,
and a transaction is consumed atomically, so a callback works once. The stores'
synchronous calls and the Authlib providers run in the thread pool.
Configuration¶
AuthRoutesConfig is a frozen dataclass. providers, accounts, contexts
and account_state are required, and so is problem_type_base (a ValueError
otherwise): it is the prefix of the type URI of the problem responses, which
is what tells csrf-failed from forbidden.
| Field | Default |
|---|---|
URL prefix (auth_router(prefix=)) |
/auth |
return_to_prefixes / default_return_to |
("/",) / / |
error_route |
/auth/error |
post_logout_redirect |
/ |
idle_timeout / absolute_timeout |
30 minutes / 12 hours |
trusted_origins / trusted_proxies |
none / none |
password_client_limit |
30 per 5 minutes |
password_account_limit |
10 per 5 minutes |
callback_client_limit |
60 per 5 minutes |
sessions, transactions, replay, csrf, limiter |
in-memory stores, refused unless debug=True |
debug |
False |
| Session cookie | __Host-session, HttpOnly, Secure, SameSite=Lax, Path=/, no Domain |
| Login transaction cookie | __Host-login-tx, same flags, Max-Age=600 |
| CSRF cookie / header | XSRF-TOKEN (not HttpOnly, Secure, SameSite=Lax, Path=/) / X-XSRF-TOKEN |
| Anonymous session lifetime | 10 minutes |
backchannel maps provider IDs to the back-channel logout handlers
(rn_forge.auth.oidc.BackchannelLogout, which needs the oidc extra);
provider_names maps IDs to display names; clock replaces the time source in
tests.
trusted_proxies lists the peer addresses or CIDR networks, such as
10.0.0.0/8, whose X-Forwarded-Proto, X-Forwarded-Host and
X-Forwarded-For headers are believed. From any other peer those headers are
ignored, so a client cannot forge its own origin or address.
Production storage¶
In-memory stores are held per process, so a second worker would not see a
revocation, a transaction or a CSRF token. Outside debug, auth_router and
Sessions refuse them with a RuntimeError naming the store: sessions,
transactions, replay, CSRF and the rate limiter. Install the redis extra and
use:
| Store | Class |
|---|---|
| Login sessions | rn_forge.auth.redis.RedisSessionStore |
| Login transactions | rn_forge.auth.redis.RedisTransactionStore |
Replayed token IDs and revoked sid values |
rn_forge.auth.redis.RedisReplayStore |
| Authorization context versions | rn_forge.auth.redis.RedisAuthorizationVersions |
| CSRF tokens | rn_forge.fastapi.auth.redis.RedisCsrfStore |
| Rate limits | rn_forge.fastapi.auth.redis.RedisRateLimiter |
They take a redis.Redis client and need Redis 6.2 or later. The Redis modules
of this package are not imported by rn_forge.fastapi, so a deployment without
the extra can import the rest. RedisAuthorizationVersions goes to the
AuthorizationContextCache, so that a change made in one process invalidates
the cached context in every process; without it a change applies after the
cache's ttl (60 seconds by default).
Sessions and revocation¶
The login session is a rn-forge-auth SessionStore entry behind the
__Host-session cookie. It holds the account ID, the account's session version
at login, provider, issuer, external subject, auth_time, amr, session_ref
and the ID token (only with rp_initiated_logout), and never permissions: those
are computed on each request.
- Timeouts. A 30-minute sliding idle timeout (
idle_timeout) and a 12-hour absolute timeout (absolute_timeout).SessionMiddlewareextends the idle expiry and refreshes the cookie on every request exceptGET /auth/session, so a client that polls the session does not keep it alive. - One read path.
Sessions.readdeletes the session, and the request is unauthenticated, when the absolute timeout has passed, the recorded session version differs from the account's, the account is inactive, or thesession_refis revoked. A cookie that names no valid session is cleared. - New IDs. Login replaces the session ID, and the CSRF token with it. Call
await rotate_session(request)after a change to the account's privileges, so an ID seen before the change is useless afterwards; the middleware sets the new cookie. - Logout.
/auth/logoutends the current session and starts a new anonymous one./auth/logout/alland a back-channel logout that names onlysubbump the account's session version throughaccount_state, which ends every session of the account on its next request. A back-channel logout with asidrevokes that session only, until the absolute timeout. Withrp_initiated_logouton the provider,/auth/logoutreturns the identity provider's end-session URL. - Disabling.
contexts.set_active(account_id, False)(or any change that makes the account inactive) ends the account's sessions at their next request.
active_session(request) returns the ActiveSession (the SessionInfo and the
account's current authorization context) the middleware resolved, or None.
CSRF¶
Unsafe methods on session-authenticated routes are protected by a synchronizer
token, which SessionMiddleware checks for the /auth routes and for the
application's own routes alike. The token is random and kept in the CsrfStore
under the session ID; the readable XSRF-TOKEN cookie hands it to the browser,
and the request repeats it in X-XSRF-TOKEN, which are Angular's defaults. The
comparison is constant-time.
GET /auth/sessionalways sets the cookie, including when it answers401. With no session it starts an anonymous session, a 10-minute entry behind__Host-sessionthat holds only a token, soPOST /auth/login/passwordis protected before sign-in.- Login replaces the session ID and the token; logout starts a new anonymous
session with a new token;
rotate_sessioncarries the token to the new ID. - Checked: an unsafe request that carries the
__Host-sessioncookie, whether it names a live session, an anonymous one or nothing known, and a request to the password login path (login_path), which a browser can reach with no cookie. - Exempt:
GET,HEAD,OPTIONSandTRACE; a request with aBearerAuthorizationheader; the paths undercsrf_exempt_prefixes(back-channel logout, which carries a signed token); and a request with no session cookie to an application route, which has no session to ride. ABasicheader is not exempt: browsers replay cached Basic credentials on their own. - Origin. The
Originheader (theRefererover HTTPS when there is noOrigin) must be the request's own origin or one oftrusted_origins, andSec-Fetch-Site: cross-siteis rejected even from a trusted origin. The request's own scheme and host come fromX-Forwarded-ProtoandX-Forwarded-Hostonly when the peer is intrusted_proxies. - A rejection is the
403csrf-failedproblem; its reason is logged, never sent.
Authentication¶
current_principal(bearer=None) returns a dependency that yields a Principal
from the login session (mechanism="session", the account's roles and
permissions from its authorization context, and the session's auth_time and
amr), or from a bearer token when bearer is given.
bearer_auth verifies an externally issued token, then resolves its
(issuer, subject) through AccountResolver.lookup. It never provisions: a
token with no linked account, or whose account is inactive, is 401. The
principal's subject is the account ID, its roles, tenant and attributes come
from the authorization context, and its permissions are the account's, limited
to what the token's scopes allow through scope_map:
from rn_forge.auth.oidc import OidcAuthenticator
from rn_forge.fastapi.auth import bearer_auth, current_principal
from myapp.auth_config import config, contexts
bearer = bearer_auth(
authenticator=OidcAuthenticator.from_issuer(
"https://login.example.com/tenant/v2.0", audience="api://orders"
),
accounts=config.accounts,
contexts=contexts,
scope_map={"orders:read": frozenset({"orders.list", "orders.read"})},
)
caller = current_principal(bearer=bearer)
Build the authenticator once at startup: it holds the JWKS cache.
One credential per request. A request with an Authorization header is
authenticated by bearer alone: an invalid token is 401 even with a valid
session cookie, and without bearer the header makes the request
unauthenticated. Any other request is authenticated by the session. An
unauthenticated request is 401 with the Bearer challenge when bearer is
given, and without a challenge otherwise, and the failure reason goes to the
log callback, never the response.
basic_auth(authenticator=...) is the RFC 7617 twin for an authenticator you
supply and does not link accounts. It is for local development and simple
internal deployments only.
Authorization¶
requires(caller, Requirement(...)) authenticates, then enforces the
requirement with rn_forge.auth.ScopeAuthorizer (or the authorizer you pass).
Insufficient access is a 403 with no challenge.
requires_permission(caller, permission_key, action) enforces the key that
rn_forge.auth.requirement_for builds from the base key and an explicit action,
list, retrieve or partial_update for example; action_map overrides the
default action-to-verb map:
from fastapi import APIRouter, Depends
from rn_forge.auth import Principal, Requirement
from rn_forge.fastapi.auth import requires, requires_permission
router = APIRouter()
@router.get("/orders")
async def list_orders(
principal: Principal = Depends(requires_permission(caller, "orders", "list")),
): ...
@router.post("/reports")
async def run_report(
principal: Principal = Depends(
requires(caller, Requirement(all_scopes=frozenset({"reports:run"})))
),
): ...
PolicyGuard(policy, hides_existence=False) applies a ResourcePolicy.
guard.scope(principal, action, query) narrows a query of any type, such as a
SQLAlchemy select, so rows, counts and pages cover only permitted rows;
guard.check(principal, action, obj) returns the object or raises 403, or
404 when hides_existence is true:
from rn_forge.fastapi.auth import PolicyGuard
from sqlalchemy import select
guard = PolicyGuard(OrderPolicy(), hides_existence=True)
@router.get("/orders/{order_id}")
async def get_order(
order_id: int,
principal: Principal = Depends(caller),
session: Session = Depends(db_session),
):
order = session.scalar(
guard.scope(principal, "retrieve", select(Order).where(Order.id == order_id))
)
if order is None:
raise LookupError("Not found")
return guard.check(principal, "retrieve", order)
Rate limits and audit events¶
POST /auth/login/password and GET /auth/callback/{provider} are rate limited
with a fixed-window counter in limiter. The client is the connection's peer,
or the nearest address in X-Forwarded-For that is not a trusted proxy when the
peer is in trusted_proxies. Password login is limited per client and per
submitted username (hashed in the key); callbacks per client only, because no
account is known before the response is verified. Each limit is a
RateLimit(limit, window), or None for none. A limited request is the 429
too-many-requests problem with Retry-After. Windows are aligned to the
clock, so a client can use a limit twice around a window boundary.
Security-relevant events are INFO records on the rn_forge.audit.auth
channel, in the form audit event=<name> key='value' ...:
| Event | Emitted when |
|---|---|
login.success |
A login starts a session |
login.failure |
A login fails (provider, code, reason) |
logout, logout.all, logout.backchannel |
A session or sessions end |
account.provisioned |
A provisioning resolver creates an account |
account.rejected |
The resolver refuses an identity |
account.disabled |
An inactive account logs in |
authorization.denied |
requires, requires_permission or PolicyGuard denies a request |
rate_limited |
A request is answered 429 |
Events carry account IDs, provider IDs, codes and short reasons, and never a token, code, assertion, password, session ID or email address.
What the application implements¶
The binding takes these rn_forge.auth protocols; every method is synchronous
and runs in the thread pool.
-
AccountResolver.resolve(identity)links, provisions or rejects an external identity at login and returns the account ID, raisingAccountRejectedto refuse it;lookup(issuer, subject)is the read-only formbearer_authuses. A resolver that creates accounts recordsaccount.provisionedonce the account is committed:```python from rn_forge.auth import audit
audit("account.provisioned", account_id=account.id, provider=identity.provider) ```
-
AuthorizationContextProvider.resolve(account_id)returns theAuthorizationContext:active,session_version,permissions,rolesandattributes. Wrap it in anAuthorizationContextCacheand callcontexts.invalidate(account_id)when a role or permission changes. -
AccountStateWriter.set_active(account_id, active)andbump_session_version(account_id)persist the state the context carries./auth/logout/alland a back-channel logout call them; the cache above writes through to it. -
ResourcePolicy.allows(principal, action, resource)andscope(principal, action, query), forPolicyGuard. -
PasswordVerifier. ForPasswordIdentityProvider: a callable(username, password) -> subject | None. Hash comparison and the user lookup are yours.