Authentication and authorization
The package has one core and two adapters. rn_forge.auth holds the contracts
and needs no third-party package. rn_forge.auth.oidc runs OIDC and OAuth 2.0
logins and verifies OIDC bearer tokens (see Login providers), and
rn_forge.auth.redis keeps sessions and single-use records in Redis; both
import the core and the core never imports them. The oidc extra installs
pyjwt[crypto], authlib, joserfc and requests, the redis extra installs
redis, and the rn_forge.auth facade re-exports neither adapter.
How the pieces fit
A login and each later request pass through the same stages:
provider -> ExternalIdentity -> AccountResolver -> account ID
-> session (SessionInfo) or bearer token
-> AuthorizationContext -> Principal
-> Requirement (route) -> ResourcePolicy (object and query)
- An
IdentityProviderauthenticates the user and returns anExternalIdentity. The login is held in aTransactionStorewhile the browser is away. - An
AccountResolvermaps the identity to an internal account ID, or rejects the login. ASessionStorethen holds aSessionInfounder a random ID. - On each request, a session or a verified bearer token identifies the account.
An
AuthorizationContextProvider, usually behind anAuthorizationContextCache, returns the account's current permissions, and the binding builds aPrincipal. For a bearer caller the token's scopes limit those permissions and never add to them. - An
Authorizerchecks the route'sRequirementagainst thePrincipal. AResourcePolicythen checks the object, or narrows the query.
| Guide | Covers |
|---|---|
| Contracts | Identity, account resolution, authorization context and cache, Principal and Requirement, permissions and the scope limit, resource policy, return_to and the session body |
| Token profiles | JwtVerifier, IdTokenVerifier and LogoutTokenVerifier, modes, the login-client rule, key rotation and cooldown |
| Stores | The four store protocols, in-memory and Redis, and the atomic operation each relies on |
| Testing | FakeOidcProvider and its failure switches |
Installing
Declare the package by version range, with the extras you use:
The base install, rn-forge-auth, is enough to write your own authenticator.
Importing rn_forge.auth.oidc without the extra fails with
ModuleNotFoundError for jwt. rn-forge-django[oidc] and
rn-forge-fastapi[oidc] already name rn-forge-auth[oidc]. Importing
rn_forge.auth.redis without the redis extra fails with ModuleNotFoundError
for redis.
With rn-forge-web and the framework packages
rn-forge-web owns the wire contract that surrounds these types:
Credentials, the raw scheme and token lifted off a request;parse_authorization, which reads anAuthorizationheader intoCredentials;challenge_header, which builds theWWW-Authenticatevalue;AUTH_FAILED_DETAIL, the fixed 401 detail,"Authentication failed.";- the
AuthenticationFailedandPermissionDeniedexceptions.
This package adds the verified caller and the decisions made about it. A
framework binding does the plumbing between them: it parses the header, calls
the Authenticator, turns AuthenticationFailed into a 401 with a challenge
and AUTH_FAILED_DETAIL, and turns PermissionDenied into a 403.
rn-forge-django binds Principal to DRF with PrincipalBearerAuthentication,
JWKSBearerAuthentication and requires; rn-forge-fastapi binds it with
bearer_auth, basic_auth and requires. See those packages' guides for
wiring.