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 |
required |
log
|
Log | None
|
Receives |
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 |
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 |
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: |
None
|
Raises:
| Type | Description |
|---|---|
RuntimeError
|
At request time, :class: |
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: |
required |
requirement
|
Requirement
|
Evaluated by :class: |
required |
authorizer
|
Authorizer | None
|
Defaults to :class: |
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: |
required |
permission_key
|
str
|
The resource's base permission key, such as |
required |
action
|
str
|
The action to check, such as |
required |
action_map
|
Mapping[str, str] | None
|
Overrides of |
None
|
authorizer
|
Authorizer | None
|
Defaults to :class: |
None
|