app.auth.deps

FastAPI dependencies: the authenticated principal and permissions.

Identity comes from verified token claims only; no user is stored. Real (RS256) and dev (HS256) tokens produce their claims through app.auth.tokens.verify_token() and then share this module’s mapping (principal_from_claims()) and authorization (require_permission()).

Claim mapping:

  • issuer / subject – iss / sub (required).

  • display – name, else preferred_username, else sub.

  • email – email, unless the token says email_verified: false (then None).

  • roles – the list of strings at the dotted ADRIANO_OIDC_ROLES_CLAIM path (default roles; Keycloak: realm_access.roles). A missing path or a non-list value yields no roles; non-string items are ignored.

Permissions come from the rbac section loaded at startup (app.auth.rbac); no configuration means no permissions.

Public API: Principal, principal_from_claims(), get_oidc_validator(), get_principal(), get_permissions(), require_permission().

class app.auth.deps.Principal(issuer, subject, display, email, roles)

Bases: object

The authenticated caller, from verified token claims.

Parameters:

  • issuer (str) – Token iss.

  • subject (str) – Token sub.

  • display (str) – Human-readable name.

  • email (str | None) – Email, if the token carries one (not marked unverified).

  • roles (tuple[str, ...]) – Role names, sorted and unique.

issuer: str
subject: str
display: str
email: str | None
roles: tuple[str, ...]
app.auth.deps.get_oidc_validator(settings=Depends(dependency=<functools._lru_cache_wrapper object>, use_cache=True, scope=None))

FastAPI dependency: the OIDC validator, if OIDC is configured.

Tests override this to inject mocked discovery and keys.

Parameters:

settings (Settings) – Application settings.

Return type:

OidcValidator | None

Returns:

The cached validator, or None.

app.auth.deps.get_permissions(principal=Depends(dependency=<function get_principal>, use_cache=True, scope=None), runtime=Depends(dependency=<function get_catalog_runtime>, use_cache=True, scope=None))

FastAPI dependency: the caller’s permissions.

Parameters:
Return type:

frozenset[Permission]

Returns:

Granted permissions (none without configuration).

app.auth.deps.get_principal(credentials=Depends(dependency=<fastapi.security.http.HTTPBearer object>, use_cache=True, scope=None), settings=Depends(dependency=<functools._lru_cache_wrapper object>, use_cache=True, scope=None), oidc=Depends(dependency=<function get_oidc_validator>, use_cache=True, scope=None))

FastAPI dependency: authenticate the bearer token.

Synchronous on purpose: FastAPI runs it in a worker thread, so the (rare) discovery/JWKS fetch never blocks the event loop.

Parameters:

  • credentials (HTTPAuthorizationCredentials | None) – The Authorization: Bearer credentials.

  • settings (Settings) – Application settings.

  • oidc (OidcValidator | None) – The OIDC validator, if configured.

Return type:

Principal

Returns:

The principal.

Raises:
app.auth.deps.principal_from_claims(claims, *, roles_claim)

Map verified claims to a Principal.

Parameters:

  • claims (Mapping[str, Any]) – Verified claims (iss and sub present).

  • roles_claim (str) – Dotted roles claim path.

Return type:

Principal

Returns:

The principal.

Raises:

AuthenticationError – If iss or sub is not a string.

app.auth.deps.require_permission(permission)

Build a dependency that requires permission.

Use as Depends(require_permission(Permission.READ)).

Parameters:

permission (Permission) – The required permission.

Return type:

Callable[..., Principal]

Returns:

A dependency returning the authenticated principal.