Skip to content

require_roles

require_roles(*roles, require_all=False) — builds a guard that requires AuthUser.roles to cover the given roles.

Signature

def require_roles(*roles: str, require_all: bool = False) -> type:
    ...

Semantics

Authentication is OR by default: the user must possess at least one of the listed roles (classic RBAC "any-of").

require_all Meaning
False (default) user has at least one of roles (OR)
True user has all of roles (AND)

Examples

@use_guards(require_roles("admin"))                     # must have 'admin'
@use_guards(require_roles("admin", "billing.manager"))   # either
@use_guards(require_roles("admin", "audit.confirm", require_all=True))  # both

Behaviour

  • No AuthUser on state → UnauthorizedError (401).
  • User present but roles don't satisfy the requirement → ForbiddenError (403).
from lauren_guards import AuthUser, require_roles

admin = AuthUser(id="u1", roles=("admin",))
editor = AuthUser(id="u2", roles=("editor",))

# admin passes; editor fails
require_roles("admin")

# Both pass — OR semantics
require_roles("admin", "editor")

# editor fails when both are required
require_roles("admin", "audit", require_all=True)

Where roles come from

Authentication guards populate AuthUser.roles from the credential — for jwt_bearer, configure role_claim to map custom claim layouts (e.g. Keycloak's realm_access.roles).