Skip to content

Auth dependencies

Authentication dependencies: current_principal, bearer_auth, basic_auth, requires and requires_permission.

rn_forge.fastapi.auth.dependencies

FastAPI security dependencies for the authentication contracts.

Framework credential parsers run with auto_error=False so failures use the shared problem response and challenge behavior.

BearerAuth(*, authenticator, accounts, contexts, scope_map, log)

A dependency yielding the :class:rn_forge.auth.Principal for a Bearer token.

Build it with :func:bearer_auth; use the instance as a dependency, or pass it to :func:current_principal.

authenticate(request) async

Return the principal for the request's Bearer token.

Raises:

Type Description
AuthenticationFailed

The token is absent, invalid or has no linked active account.

basic_auth(*, authenticator, log=None)

Return a dependency yielding a principal for HTTP Basic credentials.

Parameters:

Name Type Description Default
authenticator Authenticator | AsyncAuthenticator

Verifies Credentials(scheme="Basic", token=...), where the token is the base64 parameter exactly as sent (RFC 7617).

required
log Log | None

Receives authentication.failed with the authenticator's reason.

None

bearer_auth(*, authenticator, accounts, contexts, scope_map=None, log=None)

Return a dependency yielding the :class:rn_forge.auth.Principal for a Bearer token.

The verified token's (issuer, subject) is looked up with accounts.lookup, which never provisions. A token with no linked account, or whose account is inactive, is a 401. The principal's subject is then the account ID (external_subject keeps the token's); its roles, tenant and attributes come from the account's authorization context, and its permissions are the context's limited by the token's scopes through scope_map.

Parameters:

Name Type Description Default
authenticator Authenticator | AsyncAuthenticator

Verifies Credentials(scheme="Bearer", token=...).

required
accounts AccountResolver

Links the token's identity to an account.

required
contexts AuthorizationContextProvider

Supplies the account's authorization context.

required
scope_map Mapping[str, frozenset[str]] | None

The permissions each accepted scope allows; a scope it does not name allows nothing.

None
log Log | None

Receives authentication.failed with the failure's reason. The 401 body never carries it.

None

current_principal(*, bearer=None)

Return a dependency yielding the session or bearer principal.

A request with an Authorization header is authenticated by bearer alone: an invalid token is a 401 even with a valid session cookie, and without bearer the header makes the request unauthenticated. Any other request is authenticated by the login session that :class:~rn_forge.fastapi.SessionMiddleware resolved, whose principal has mechanism="session", the context's roles and permissions, and the session's auth_time and amr. CSRF checks for session requests are the middleware's.

An unauthenticated request is a 401 with the Bearer challenge when bearer is given, and without a challenge otherwise.

Parameters:

Name Type Description Default
bearer BearerAuth | None

From :func:bearer_auth.

None

Raises:

Type Description
RuntimeError

At request time, :class:~rn_forge.fastapi.SessionMiddleware is not installed and the request carries no Authorization header.

requires(authenticate, requirement, *, authorizer=None)

Return a dependency that authenticates, then enforces requirement.

Insufficient access produces 403 without an authentication challenge.

Parameters:

Name Type Description Default
authenticate PrincipalDependency

A dependency from :func:bearer_auth, :func:basic_auth or :func:current_principal.

required
requirement Requirement

Evaluated by :class:rn_forge.auth.Requirement's own rule.

required
authorizer Authorizer | None

Defaults to :class:rn_forge.auth.ScopeAuthorizer.

None

requires_permission(authenticate, permission_key, action, *, action_map=None, authorizer=None)

Return a dependency that authenticates, then enforces a permission key.

The requirement is :func:rn_forge.auth.requirement_for of permission_key and the action. Insufficient access produces 403 without a challenge.

Parameters:

Name Type Description Default
authenticate PrincipalDependency

A dependency such as :func:current_principal's.

required
permission_key str

The resource's base permission key, such as orders.

required
action str

The action to check, such as list, retrieve or partial_update.

required
action_map Mapping[str, str] | None

Overrides of DEFAULT_PERMISSION_ACTION_MAP.

None
authorizer Authorizer | None

Defaults to :class:rn_forge.auth.ScopeAuthorizer.

None