fastapi-keycloak-admin 0.1.0__py3-none-any.whl

fastapi_keycloak_admin/client.py

@@ -0,0 +1,362 @@
+import asyncio
+import json
+import time
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from http import HTTPStatus
+from typing import Any
+
+import aiohttp
+
+from fastapi_keycloak_admin.config import KeycloakAdminConfig
+from fastapi_keycloak_admin.exceptions import (
+    KeycloakAdminError,
+    KeycloakLoginError,
+    KeycloakUnavailableError,
+    PasswordChangeRequiredError,
+)
+
+PASSWORD_CHANGE_REQUIRED_DESCRIPTION = "Account is not fully set up"
+"""Keycloak's ``error_description`` for a password grant on an account with pending required actions."""
+
+BUILT_IN_ROLES = frozenset({"offline_access", "uma_authorization"})
+"""Roles every Keycloak realm has; not application roles, so ``list_roles`` leaves them out."""
+
+_ADMIN_TOKEN_LEEWAY_SECONDS = 15
+
+
+@dataclass(frozen=True, slots=True)
+class _Response:
+    status: int
+    text: str
+    headers: Mapping[str, str]
+
+    def json(self) -> Any:  # noqa: ANN401
+        return json.loads(self.text)
+
+    def error_description(self) -> str | None:
+        try:
+            payload = self.json()
+        except ValueError:
+            return None
+        if not isinstance(payload, dict):
+            return None
+        return (
+            payload.get("error_description") or payload.get("errorMessage") or payload.get("error")
+        )
+
+
+class KeycloakAdminClient:
+    """Calls Keycloak on behalf of the backend: the OIDC token endpoints (password grant,
+    refresh, logout) and the Admin REST API.
+
+    One instance lives per application (see ``KeycloakAdmin``); it reuses one aiohttp
+    session and one admin token until it expires.
+    """
+
+    def __init__(self, config: KeycloakAdminConfig) -> None:
+        self.config = config
+        self._session: aiohttp.ClientSession | None = None
+        self._session_lock = asyncio.Lock()
+        self._admin_token: str | None = None
+        self._admin_token_expires_at = 0.0
+
+    async def _get_session(self) -> aiohttp.ClientSession:
+        # Created lazily inside the running loop - there is none yet when the app is built.
+        if self._session is None or self._session.closed:
+            async with self._session_lock:
+                if self._session is None or self._session.closed:
+                    self._session = aiohttp.ClientSession(
+                        timeout=aiohttp.ClientTimeout(total=self.config.timeout)
+                    )
+        return self._session
+
+    async def close(self) -> None:
+        """Close the HTTP session; ``KeycloakAdmin`` calls it at application shutdown."""
+        if self._session is not None and not self._session.closed:
+            await self._session.close()
+        self._session = None
+
+    async def _request(self, method: str, url: str, **kwargs: Any) -> _Response:  # noqa: ANN401
+        session = await self._get_session()
+        try:
+            async with session.request(method, url, **kwargs) as response:
+                return _Response(response.status, await response.text(), dict(response.headers))
+        except (aiohttp.ClientError, TimeoutError) as exc:
+            raise KeycloakUnavailableError(f"Keycloak is unreachable: {exc!r}") from exc
+
+    # --- tokens ---------------------------------------------------------------------------
+
+    async def _token_grant(self, data: dict[str, str]) -> dict[str, Any]:
+        response = await self._request(
+            "POST",
+            self.config.keycloak.token_url,
+            data={
+                "client_id": self.config.client_id,
+                "client_secret": self.config.client_secret,
+                **data,
+            },
+        )
+        if response.status == HTTPStatus.OK:
+            return response.json()
+        if response.status >= HTTPStatus.INTERNAL_SERVER_ERROR:
+            raise KeycloakUnavailableError(f"Keycloak token endpoint failed: {response.text}")
+        description = response.error_description() or "Invalid credentials"
+        if description == PASSWORD_CHANGE_REQUIRED_DESCRIPTION:
+            raise PasswordChangeRequiredError(description)
+        raise KeycloakLoginError(description)
+
+    async def login(self, username: str, password: str) -> dict[str, Any]:
+        """Resource Owner Password Credentials grant - the password passes through to
+        Keycloak and is never stored. Returns Keycloak's token response as is.
+
+        Raises:
+            PasswordChangeRequiredError: the account still has a temporary password.
+            KeycloakLoginError: wrong credentials.
+        """
+        return await self._token_grant(
+            {"grant_type": "password", "username": username, "password": password}
+        )
+
+    async def refresh(self, refresh_token: str) -> dict[str, Any]:
+        """New tokens for a live session (Keycloak rotates the refresh token too).
+
+        Raises:
+            KeycloakLoginError: the refresh token is expired, revoked or malformed.
+        """
+        return await self._token_grant(
+            {"grant_type": "refresh_token", "refresh_token": refresh_token}
+        )
+
+    async def logout(self, refresh_token: str) -> None:
+        """End the session behind ``refresh_token``. An already dead session is fine."""
+        await self._request(
+            "POST",
+            self.config.keycloak.logout_url,
+            data={
+                "client_id": self.config.client_id,
+                "client_secret": self.config.client_secret,
+                "refresh_token": refresh_token,
+            },
+        )
+
+    async def check_password(self, username: str, password: str) -> bool:
+        """Whether ``password`` is the user's current one; the session this opens is closed again."""
+        try:
+            tokens = await self.login(username, password)
+        except PasswordChangeRequiredError:
+            return True
+        except KeycloakLoginError:
+            return False
+        if refresh_token := tokens.get("refresh_token"):
+            await self.logout(refresh_token)
+        return True
+
+    async def complete_initial_password(
+        self, username: str, password: str, new_password: str
+    ) -> dict[str, Any]:
+        """Swap a temporary password for a permanent one and log in with it.
+
+        Raises:
+            KeycloakLoginError: ``password`` is wrong.
+            KeycloakAdminError: the account has no temporary password (``conflict``), or the
+                new one breaks the realm's password policy (``invalid``).
+        """
+        try:
+            tokens = await self.login(username, password)
+        except PasswordChangeRequiredError:
+            subject = await self.find_user_id(username)
+            if subject is None:
+                raise KeycloakLoginError("Invalid credentials") from None
+            await self.set_password(subject, new_password)
+            await self.update_user(subject, requiredActions=[])
+            return await self.login(username, new_password)
+        if refresh_token := tokens.get("refresh_token"):
+            await self.logout(refresh_token)
+        raise KeycloakAdminError("This account has no temporary password", conflict=True)
+
+    async def signing_keys(self) -> dict[str, Any]:
+        """The realm's JWKS, which access tokens are verified against."""
+        response = await self._request(
+            "GET", self.config.keycloak.jwks_url, headers={"Accept": "application/json"}
+        )
+        if response.status != HTTPStatus.OK:
+            raise KeycloakUnavailableError(f"Keycloak JWKS endpoint failed: {response.status}")
+        try:
+            return response.json()
+        except ValueError as exc:
+            raise KeycloakUnavailableError("Keycloak returned a malformed JWKS") from exc
+
+    # --- Admin REST API -------------------------------------------------------------------
+
+    async def _fetch_admin_token(self) -> str:
+        if self._admin_token and time.monotonic() < self._admin_token_expires_at:
+            return self._admin_token
+        if self.config.admin_username and self.config.admin_password:
+            url = self.config.master_token_url
+            data = {
+                "grant_type": "password",
+                "client_id": "admin-cli",
+                "username": self.config.admin_username,
+                "password": self.config.admin_password,
+            }
+        else:
+            url = self.config.keycloak.token_url
+            data = {
+                "grant_type": "client_credentials",
+                "client_id": self.config.client_id,
+                "client_secret": self.config.client_secret,
+            }
+        response = await self._request("POST", url, data=data)
+        if response.status != HTTPStatus.OK:
+            raise KeycloakAdminError(f"Could not obtain a Keycloak admin token: {response.text}")
+        payload = response.json()
+        self._admin_token = token = payload["access_token"]
+        self._admin_token_expires_at = (
+            time.monotonic() + payload.get("expires_in", 60) - _ADMIN_TOKEN_LEEWAY_SECONDS
+        )
+        return token
+
+    async def _admin(self, method: str, path: str, **kwargs: Any) -> _Response:  # noqa: ANN401
+        token = await self._fetch_admin_token()
+        response = await self._request(
+            method,
+            self.config.admin_realm_url + path,
+            headers={"Authorization": f"Bearer {token}"},
+            **kwargs,
+        )
+        if response.status == HTTPStatus.UNAUTHORIZED:
+            # Revoked or expired early (e.g. Keycloak restarted) - drop it so the next call re-fetches.
+            self._admin_token = None
+        return response
+
+    async def list_roles(self) -> list[dict[str, Any]]:
+        """The realm's own roles (``name``, ``description``), without Keycloak's built-in ones."""
+        found = await self._admin("GET", "/roles", params={"briefRepresentation": "true"})
+        if found.status != HTTPStatus.OK:
+            raise KeycloakAdminError(f"Could not list realm roles: {found.text}")
+        default_roles = f"default-roles-{self.config.keycloak.realm}"
+        return sorted(
+            (
+                role
+                for role in found.json()
+                if role["name"] not in BUILT_IN_ROLES and role["name"] != default_roles
+            ),
+            key=lambda role: role["name"],
+        )
+
+    async def create_user(
+        self,
+        *,
+        username: str,
+        password: str,
+        email: str | None = None,
+        first_name: str | None = None,
+        last_name: str | None = None,
+        roles: Iterable[str] = (),
+        temporary_password: bool = True,
+    ) -> str:
+        """Create a realm user, assign ``roles`` and return the new subject id. A temporary
+        password must be changed at first login (see ``complete_initial_password``)."""
+        role_representations = [await self._role(role) for role in roles]
+        created = await self._admin(
+            "POST",
+            "/users",
+            json={
+                "username": username,
+                "email": email,
+                "firstName": first_name,
+                "lastName": last_name,
+                "enabled": True,
+                "emailVerified": email is not None,
+                "requiredActions": ["UPDATE_PASSWORD"] if temporary_password else [],
+                "credentials": [
+                    {"type": "password", "value": password, "temporary": temporary_password}
+                ],
+            },
+        )
+        if created.status == HTTPStatus.CONFLICT:
+            raise KeycloakAdminError(f"User {username!r} already exists", conflict=True)
+        if created.status == HTTPStatus.BAD_REQUEST:
+            raise KeycloakAdminError(
+                created.error_description() or "User rejected by Keycloak", invalid=True
+            )
+        if created.status != HTTPStatus.CREATED:
+            raise KeycloakAdminError(f"Could not create Keycloak user: {created.text}")
+        subject = created.headers["Location"].rsplit("/", 1)[-1]
+        if role_representations:
+            assigned = await self._admin(
+                "POST", f"/users/{subject}/role-mappings/realm", json=role_representations
+            )
+            if assigned.status != HTTPStatus.NO_CONTENT:
+                raise KeycloakAdminError(f"Could not assign roles: {assigned.text}")
+        return subject
+
+    async def _role(self, role: str) -> dict[str, Any]:
+        found = await self._admin("GET", f"/roles/{role}")
+        if found.status == HTTPStatus.NOT_FOUND:
+            raise KeycloakAdminError(f"Unknown realm role {role!r}", invalid=True)
+        if found.status != HTTPStatus.OK:
+            raise KeycloakAdminError(f"Could not look up role {role!r}: {found.text}")
+        return found.json()
+
+    async def update_user(self, subject: str, **representation: Any) -> None:  # noqa: ANN401
+        """Partial update with Keycloak's own ``UserRepresentation`` field names
+        (``firstName``, ``email``, ``requiredActions``, ...)."""
+        updated = await self._admin("PUT", f"/users/{subject}", json=representation)
+        if updated.status == HTTPStatus.CONFLICT:
+            raise KeycloakAdminError(
+                "This e-mail is already used by another account", conflict=True
+            )
+        if updated.status == HTTPStatus.BAD_REQUEST:
+            raise KeycloakAdminError(
+                updated.error_description() or "Update rejected by Keycloak", invalid=True
+            )
+        if updated.status != HTTPStatus.NO_CONTENT:
+            raise KeycloakAdminError(f"Could not update Keycloak user: {updated.text}")
+
+    async def set_password(self, subject: str, password: str, *, temporary: bool = False) -> None:
+        """Set the user's password; a ``temporary`` one has to be replaced at the next login.
+
+        Raises:
+            KeycloakAdminError: the password breaks the realm's password policy (``invalid``).
+        """
+        reset = await self._admin(
+            "PUT",
+            f"/users/{subject}/reset-password",
+            json={"type": "password", "value": password, "temporary": temporary},
+        )
+        if reset.status == HTTPStatus.BAD_REQUEST:
+            detail = reset.error_description() or "Password rejected by the password policy"
+            raise KeycloakAdminError(detail, invalid=True)
+        if reset.status != HTTPStatus.NO_CONTENT:
+            raise KeycloakAdminError(f"Could not set Keycloak password: {reset.text}")
+
+    async def get_user(self, subject: str) -> dict[str, Any] | None:
+        """The full ``UserRepresentation`` (attributes included), or ``None``."""
+        found = await self._admin("GET", f"/users/{subject}")
+        if found.status == HTTPStatus.NOT_FOUND:
+            return None
+        if found.status != HTTPStatus.OK:
+            raise KeycloakAdminError(f"Could not read Keycloak user: {found.text}")
+        return found.json()
+
+    async def set_user_attribute(self, subject: str, name: str, values: list[str]) -> None:
+        """Replace one user attribute and keep the others.
+
+        Keycloak replaces the whole ``attributes`` map (and drops omitted fields) on update,
+        so the user is read first and sent back merged.
+        """
+        user = await self.get_user(subject)
+        if user is None:
+            raise KeycloakAdminError(f"User {subject!r} not found", invalid=True)
+        attributes = {**(user.get("attributes") or {}), name: values}
+        await self.update_user(subject, **{**user, "attributes": attributes})
+
+    async def find_user_id(self, username: str) -> str | None:
+        """The subject id of the user with exactly this username, or ``None``."""
+        found = await self._admin("GET", "/users", params={"username": username, "exact": "true"})
+        if found.status != HTTPStatus.OK:
+            raise KeycloakAdminError(f"Could not look up user {username!r}: {found.text}")
+        users = found.json()
+        return users[0]["id"] if users else None

fastapi_keycloak_admin/config.py

@@ -0,0 +1,179 @@
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass, field, replace
+from typing import Any, Literal
+
+from fastapi_keycloak_admin.verification import LoginVerificationConfig
+
+
+@dataclass(frozen=True, slots=True)
+class KeycloakConfig:
+    """Where Keycloak is, which client the backend uses, and how access tokens are checked."""
+
+    server_url: str
+    """Where the backend reaches Keycloak, e.g. ``http://keycloak:8080``."""
+    realm: str
+    client_id: str
+    """The confidential client used for the password grant; also the expected audience."""
+    client_secret: str
+
+    expected_issuer: str | None = None
+    """Expected ``iss``; defaults to ``realm_url``. Set it when users reach Keycloak at another
+    URL than ``server_url``, e.g. behind a reverse proxy."""
+    audience: str | None = None
+    """Expected ``aud``; defaults to ``client_id``."""
+    optional_audiences: frozenset[str] = frozenset()
+    """More audiences to accept, e.g. other clients calling this API."""
+    strict_audience: bool = False
+    """Accept a token only when ``aud`` holds an accepted audience. By default a token whose
+    ``azp`` is accepted passes too, since Keycloak access tokens often lack the client's own
+    audience."""
+    expected_token_type: str | None = "Bearer"
+    """Required ``typ`` claim, which rejects ID and refresh tokens; ``None`` skips the check."""
+    algorithms: tuple[str, ...] = ("RS256",)
+    jwks_cache_ttl: int = 3600
+    """Seconds Keycloak's signing keys are cached; a token with an unknown key fetches them
+    again sooner."""
+
+    def __post_init__(self) -> None:
+        if not self.client_secret:
+            raise ValueError("KeycloakConfig.client_secret is required")
+        if self.jwks_cache_ttl < 0:
+            raise ValueError("jwks_cache_ttl must not be negative")
+
+    @property
+    def realm_url(self) -> str:
+        return f"{self.server_url.rstrip('/')}/realms/{self.realm}"
+
+    @property
+    def issuer(self) -> str:
+        return self.expected_issuer or self.realm_url
+
+    @property
+    def accepted_audiences(self) -> frozenset[str]:
+        return frozenset({self.audience or self.client_id}) | self.optional_audiences
+
+    @property
+    def token_url(self) -> str:
+        return f"{self.realm_url}/protocol/openid-connect/token"
+
+    @property
+    def logout_url(self) -> str:
+        return f"{self.realm_url}/protocol/openid-connect/logout"
+
+    @property
+    def jwks_url(self) -> str:
+        return f"{self.realm_url}/protocol/openid-connect/certs"
+
+
+@dataclass(frozen=True, slots=True)
+class RefreshCookieConfig:
+    """Where the session endpoints keep the refresh token.
+
+    With ``enabled`` the token lives in an ``httponly`` cookie only and is never returned in
+    a response body - what a browser frontend wants. Disable it for non-browser clients:
+    the token is then returned in the body and must be sent back in ``refresh_token``.
+    """
+
+    enabled: bool = True
+    name: str = "kc_refresh"
+    path: str | None = None
+    """Defaults to ``auth_path``. Set it when a reverse proxy serves the API under a
+    prefix (e.g. ``/api/auth``), or the browser won't send the cookie back."""
+    secure: bool = True
+    samesite: Literal["lax", "strict", "none"] = "strict"
+
+
+@dataclass(frozen=True, slots=True)
+class KeycloakAdminConfig:
+    """Settings of ``KeycloakAdmin``.
+
+    Usually built with ``from_env``; build it directly to pass a ``KeycloakConfig`` of your own.
+    """
+
+    keycloak: KeycloakConfig
+    """Connection and token validation settings; its ``client_id`` and ``client_secret`` are
+    used for every call made here."""
+
+    admin_username: str | None = None
+    admin_password: str | None = None
+    """Master-realm admin used for the Admin REST API. Leave both unset to use the client's
+    own service account instead (``client_credentials``; give it the ``realm-management``
+    roles ``manage-users`` and ``view-realm``)."""
+
+    admin_role: str = "admin"
+    """Realm role allowed to register users and list roles."""
+    assignable_roles: tuple[str, ...] = ()
+    """Realm roles registration may assign. Empty (the default) allows every role the realm
+    defines, so new roles only need to be added in Keycloak."""
+
+    auth_path: str = "/auth"
+    """Path the session and account endpoints are mounted under."""
+    refresh_cookie: RefreshCookieConfig = field(default_factory=RefreshCookieConfig)
+    min_password_length: int = 8
+    """Checked before a password reaches Keycloak, whose own password policy applies too."""
+    timeout: float = 10
+    """Seconds allowed for each request to Keycloak."""
+    login_verification: LoginVerificationConfig | None = None
+    """Second login step with a one-time code; off when ``None``."""
+
+    @classmethod
+    def from_env(
+        cls,
+        prefix: str = "KEYCLOAK_",
+        *,
+        keycloak: Mapping[str, Any] | None = None,
+        **overrides: Any,  # noqa: ANN401
+    ) -> "KeycloakAdminConfig":
+        """Read ``{prefix}INTERNAL_URL``, ``REALM``, ``CLIENT_ID``, ``CLIENT_SECRET`` (required) and
+        ``ISSUER``, ``AUDIENCE``, ``ADMIN``, ``ADMIN_PASSWORD``, ``REFRESH_COOKIE_PATH`` (optional).
+
+        ``keycloak`` holds extra ``KeycloakConfig`` arguments (e.g. ``optional_audiences``);
+        ``overrides`` win over the environment for this config.
+        """
+
+        def required(name: str) -> str:
+            value = os.environ.get(prefix + name)
+            if not value:
+                raise ValueError(f"{prefix}{name} is required")
+            return value
+
+        def optional(name: str) -> str | None:
+            return os.environ.get(prefix + name) or None
+
+        keycloak_config = KeycloakConfig(
+            server_url=required("INTERNAL_URL"),
+            realm=required("REALM"),
+            client_id=required("CLIENT_ID"),
+            client_secret=required("CLIENT_SECRET"),
+            expected_issuer=optional("ISSUER"),
+            audience=optional("AUDIENCE"),
+            **(keycloak or {}),
+        )
+        config = cls(
+            keycloak=keycloak_config,
+            admin_username=optional("ADMIN"),
+            admin_password=optional("ADMIN_PASSWORD"),
+            refresh_cookie=RefreshCookieConfig(path=optional("REFRESH_COOKIE_PATH")),
+        )
+        return replace(config, **overrides)
+
+    @property
+    def client_id(self) -> str:
+        return self.keycloak.client_id
+
+    @property
+    def client_secret(self) -> str:
+        return self.keycloak.client_secret
+
+    @property
+    def admin_realm_url(self) -> str:
+        return f"{self.keycloak.server_url.rstrip('/')}/admin/realms/{self.keycloak.realm}"
+
+    @property
+    def master_token_url(self) -> str:
+        return f"{self.keycloak.server_url.rstrip('/')}/realms/master/protocol/openid-connect/token"
+
+    @property
+    def cookie_path(self) -> str:
+        return self.refresh_cookie.path or self.auth_path

fastapi_keycloak_admin/dependencies.py

@@ -0,0 +1,117 @@
+"""Dependencies for routes: the caller (``CurrentUser``), role and scope checks, and the
+application's ``KeycloakAdminClient``."""
+
+import enum
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING, Annotated
+
+from fastapi import Depends, Request
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+from fastapi_keycloak_admin.client import KeycloakAdminClient
+from fastapi_keycloak_admin.exceptions import (
+    InsufficientRoleError,
+    InsufficientScopeError,
+    MissingTokenError,
+)
+from fastapi_keycloak_admin.models import KeycloakUser
+
+if TYPE_CHECKING:
+    from fastapi_keycloak_admin.integration import KeycloakAdmin
+
+STATE_KEY = "keycloak_admin"
+"""``app.state`` attribute holding the application's ``KeycloakAdmin``."""
+
+_bearer = HTTPBearer(auto_error=False, description="Keycloak access token")
+
+
+def get_keycloak(request: Request) -> "KeycloakAdmin":
+    keycloak = getattr(request.app.state, STATE_KEY, None)
+    if keycloak is None:
+        raise RuntimeError("KeycloakAdmin.init_app(app) has not been called")
+    return keycloak
+
+
+def get_keycloak_admin(request: Request) -> KeycloakAdminClient:
+    return get_keycloak(request).client
+
+
+async def get_current_user(
+    request: Request,
+    credentials: Annotated[HTTPAuthorizationCredentials | None, Depends(_bearer)],
+) -> KeycloakUser:
+    """The caller of a route; raises ``AuthenticationError`` (``401``) without a valid token."""
+    if credentials is None:
+        raise MissingTokenError("Authentication required")
+    claims = await get_keycloak(request).verifier.verify(credentials.credentials)
+    return KeycloakUser.from_claims(claims)
+
+
+CurrentUser = Annotated[KeycloakUser, Depends(get_current_user)]
+"""The authenticated caller: ``async def route(user: CurrentUser)``."""
+
+KeycloakAdminDep = Annotated[KeycloakAdminClient, Depends(get_keycloak_admin)]
+"""The application's ``KeycloakAdminClient``."""
+
+
+class MatchStrategy(enum.Enum):
+    ALL = "all"
+    """Every required value."""
+    ANY = "any"
+    """At least one of them."""
+
+
+def _satisfied(required: frozenset[str], actual: frozenset[str], strategy: MatchStrategy) -> bool:
+    return required <= actual if strategy is MatchStrategy.ALL else bool(required & actual)
+
+
+UserDependency = Callable[[KeycloakUser], Awaitable[KeycloakUser]]
+
+
+def require_roles(*roles: str, strategy: MatchStrategy = MatchStrategy.ALL) -> UserDependency:
+    """A dependency that admits callers holding the realm ``roles`` and returns the caller::
+
+    @app.get("/staff", dependencies=[Depends(require_roles("admin", "manager",
+                                                           strategy=MatchStrategy.ANY))])
+    """
+    required = frozenset(roles)
+
+    async def dependency(user: CurrentUser) -> KeycloakUser:
+        if not _satisfied(required, user.realm_roles, strategy):
+            raise InsufficientRoleError("Insufficient permissions")
+        return user
+
+    return dependency
+
+
+def require_client_roles(
+    client_id: str, *roles: str, strategy: MatchStrategy = MatchStrategy.ALL
+) -> UserDependency:
+    """Like ``require_roles``, for roles of the client ``client_id``."""
+    required = frozenset(roles)
+
+    async def dependency(user: CurrentUser) -> KeycloakUser:
+        if not _satisfied(required, user.client_roles.get(client_id, frozenset()), strategy):
+            raise InsufficientRoleError("Insufficient permissions")
+        return user
+
+    return dependency
+
+
+def require_scopes(*scopes: str, strategy: MatchStrategy = MatchStrategy.ALL) -> UserDependency:
+    """Like ``require_roles``, for scopes of the token."""
+    required = frozenset(scopes)
+
+    async def dependency(user: CurrentUser) -> KeycloakUser:
+        if not _satisfied(required, user.scopes, strategy):
+            raise InsufficientScopeError("Insufficient scope")
+        return user
+
+    return dependency
+
+
+async def requires_admin(request: Request, user: CurrentUser) -> KeycloakUser:
+    """The caller holds the configured ``admin_role``."""
+    if get_keycloak(request).config.admin_role not in user.realm_roles:
+        raise InsufficientRoleError("Insufficient permissions")
+    return user