litestar-keycloak-admin

Account and user management for Litestar applications that use Keycloak as their identity provider. It lets your frontend keep its own login form, lets users manage their own account, and lets administrators create users with any realm roles. Neither the browser nor your code ever has to talk to Keycloak directly.

The project is currently alpha software. Pin the version, test upgrades in a staging environment, and review the security notes before using it in production.

The package is built on top of litestar-keycloak and complements it rather than replacing it:

KeycloakAdminPlugin installs litestar-keycloak's KeycloakPlugin for you, so an application registers exactly one plugin.

Contents: Installation · Quick start · Keycloak setup · Protecting routes · Login flow · Endpoints · Errors · Configuration · Command line · Using the client · Public API · Security notes

Installation

Python 3.12 or newer is required.

# pip
python -m pip install litestar-keycloak-admin

# or uv
uv add litestar-keycloak-admin

It depends on litestar-keycloak (0.3.x) and aiohttp; both are installed with it.

Quick start

from litestar import Litestar, get
from litestar_keycloak import CurrentUser, MatchStrategy, require_roles
from litestar_keycloak_admin import KeycloakAdminConfig, KeycloakAdminPlugin


@get("/reports", guards=[require_roles("admin", "analyst", strategy=MatchStrategy.ANY)])
async def reports(current_user: CurrentUser) -> dict[str, str]:
    return {"requested_by": current_user.preferred_username or current_user.sub}


app = Litestar(
    route_handlers=[reports],
    plugins=[
        KeycloakAdminPlugin(
            KeycloakAdminConfig.from_env(keycloak={"exclude_patterns": ("^/schema", "^/health$")}),
        )
    ],
)

With KEYCLOAK_INTERNAL_URL, KEYCLOAK_REALM, KEYCLOAK_CLIENT_ID and KEYCLOAK_CLIENT_SECRET set, the application now has:

• every route protected by a Keycloak access token, except /schema, /health and the public auth endpoints;
• /reports open to users holding admin or analyst;
• the auth endpoints under /auth (see Endpoints).

A minimal local environment looks like this:

KEYCLOAK_INTERNAL_URL=http://localhost:8080
KEYCLOAK_REALM=my-realm
KEYCLOAK_CLIENT_ID=my-backend
KEYCLOAK_CLIENT_SECRET=replace-me

# Optional: use a master-realm administrator for local development.
KEYCLOAK_ADMIN=admin
KEYCLOAK_ADMIN_PASSWORD=replace-me-too

Keep secrets outside source control. In production, prefer a narrowly scoped service account as described below.

Keycloak setup

The package expects:

1. A confidential client (Client authentication On) with Direct access grants enabled. This is the client the backend uses for the password grant. Its ID and secret go into KEYCLOAK_CLIENT_ID / KEYCLOAK_CLIENT_SECRET.
2. An audience mapper on that client, so access tokens carry its ID in aud (Client scopes → dedicated scope → Add mapper → Audience). Without it every token is rejected as having the wrong audience.
3. Realm roles for your application, e.g. admin, user, dispatcher. They are not listed anywhere in code: define them in Keycloak (or in the realm export you import) and they can be assigned and checked right away. One realm role, admin by default, is the admin role: its holders may list roles and register users.
4. Admin REST API access, in one of two ways:
   • set KEYCLOAK_ADMIN / KEYCLOAK_ADMIN_PASSWORD to a master-realm administrator (simplest, fine for development); or
   • leave them unset and enable Service accounts on the client, then give its service account the realm-management roles manage-users and view-realm (recommended in production: the backend gets only the rights it needs, in one realm).

A minimal realm export with both roles and the client:

{
  "realm": "my-realm",
  "roles": {
    "realm": [
      { "name": "admin", "description": "Full administrative access" },
      { "name": "user", "description": "Regular user" }
    ]
  },
  "clients": [
    {
      "clientId": "my-backend",
      "publicClient": false,
      "secret": "${KEYCLOAK_CLIENT_SECRET}",
      "directAccessGrantsEnabled": true,
      "standardFlowEnabled": false,
      "protocolMappers": [
        {
          "name": "audience",
          "protocol": "openid-connect",
          "protocolMapper": "oidc-audience-mapper",
          "config": { "included.client.audience": "my-backend", "access.token.claim": "true" }
        }
      ]
    }
  ]
}

Protecting routes

Authentication is on by default: litestar-keycloak rejects any request without a valid token with 401. Make a route public in one of two ways:

• a path pattern in exclude_patterns (regular expressions, matched against the path): KeycloakAdminConfig.from_env(keycloak={"exclude_patterns": ("^/schema", "^/webhooks/")});
• a handler flag: @get("/health", opt={"exclude_from_auth": True}).

On a protected route, inject the caller as current_user: CurrentUser (the parameter must have exactly this name). It is a litestar_keycloak.KeycloakUser with sub, preferred_username, email, given_name, family_name, realm_roles and client_roles.

Restrict a route to certain roles with require_roles:

from litestar_keycloak import MatchStrategy, require_roles
from litestar_keycloak_admin import requires_admin

require_roles("admin", "dispatcher", strategy=MatchStrategy.ANY)  # holds at least one of them
require_roles("dispatcher", "supervisor")  # holds every one of them
requires_admin  # holds the configured admin role

Note: require_roles defaults to MatchStrategy.ALL. For "any of these roles", which is what most role checks mean, pass strategy=MatchStrategy.ANY explicitly.

A caller lacking the roles gets 403.

Login flow

The endpoints are designed for a browser frontend with its own login form:

1. Log in: POST /auth/login with {"username", "password"}. The response holds the access token. The refresh token is set as an httponly cookie and is never visible to JavaScript.
2. First login of a new user: users created by an admin have a temporary password, so the login responds 403 with the reason passwordChangeRequired (see Errors). The frontend asks for a new password and calls POST /auth/initial-password with {"username", "password", "new_password"}. On success it returns tokens, just like a login.
3. Calling the API: send Authorization: Bearer <token>.
4. Keeping the session alive: before the access token expires (expires_in, in seconds), call POST /auth/refresh, or call it when an API request fails with the reason expired. The browser sends the cookie on its own; no body is needed. A 401 from /refresh itself means the Keycloak session is over and the user has to log in again.
5. Logging out: POST /auth/logout ends the Keycloak session and clears the cookie. Dropping the access token in the browser alone would leave the session usable until it expires.

For non-browser clients (mobile apps, scripts), disable the cookie with refresh_cookie=RefreshCookieConfig(enabled=False): the refresh token is then returned in the response body and sent back as {"refresh_token": "..."} to /refresh and /logout.

Login verification by code

Set login_verification to require a one-time code after the password. The application decides how the code reaches the user - the package only calls send_code:

from litestar_keycloak_admin import KeycloakAdminConfig, LoginCode, LoginVerificationConfig


async def send_code(code: LoginCode) -> None:
    await mailer.send(code.email, f"Your login code: {code.code}")  # or publish to a queue


config = KeycloakAdminConfig.from_env(
    login_verification=LoginVerificationConfig(send_code=send_code),
)

POST /login and POST /initial-password then check the password and answer 202 {"challenge_id", "expires_in", "destination": "a***@example.com", "code_required": true} instead of tokens. POST /login/verify with the right code returns the usual TokenResponse (and the refresh cookie); POST /login/resend sends a new code for the same challenge.

• The Keycloak tokens of the checked password wait in a Litestar store under LoginVerificationConfig.store and are refreshed on success. Register a shared store (e.g. RedisStore) under that name when the app runs several workers.
• The code is kept only as an HMAC; max_attempts wrong codes (default 5) end the Keycloak session. Codes live ttl_seconds (300); resend_interval_seconds (60) and max_sends (4) limit resending.
• The e-mail comes from the access token's email claim; an account without one gets 403 emailRequired. A send_code that raises gives 503 codeDeliveryFailed.
• Error reasons: invalidCode (401), challengeExpired (401), tooManyAttempts (429), tooManySends (429), resendTooSoon (429 with Retry-After).

Endpoints

All paths are relative to auth_path (default /auth).

Public (no token)

The last two exist only with login_verification (see below); otherwise they answer 404.

TokenResponse is {"token": str, "expires_in": int, "refresh_expires_in": int, "refresh_token": str | null}; refresh_token is null while the cookie is enabled.

Any authenticated user

UserResponse is {"id", "username", "email", "first_name", "last_name", "roles": [str]}. It is built from the access token, so after PATCH /me the token itself keeps the old values until it is refreshed.

Admin role only

GET /roles returns the realm's own roles and leaves out Keycloak's built-in ones (offline_access, uma_authorization, default-roles-<realm>). Use it to fill a role picker.

POST /register creates the user with a temporary password and the given roles, at least one. It fails with 400, and creates nothing, if a role doesn't exist in the realm or isn't in assignable_roles.

Errors

Every error, whether it comes from this package, from litestar-keycloak (tokens, roles) or from Litestar itself (validation), has the same shape:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "invalidParameter",
        "message": "Password must be at least 8 characters long",
        "locationType": "body",
        "location": "password"
      }
    ],
    "code": 400,
    "message": "Password must be at least 8 characters long"
  }
}

• code repeats the HTTP status, and message is meant for humans.
• errors[].reason is the stable, machine-readable part: branch on it, not on the message.
• location and locationType say what the error is about, when that is known: a body field (body), a query or path parameter (query, path), or a header (header, e.g. Authorization).

Token errors also set WWW-Authenticate: Bearer.

The plugin applies this format to its own endpoints and to token and role errors. To use it for the whole application, register the same handlers app-wide:

from litestar import Litestar
from litestar.exceptions import HTTPException
from litestar.status_codes import HTTP_500_INTERNAL_SERVER_ERROR
from litestar_keycloak_admin import handle_http_exception, handle_internal_error

app = Litestar(
    exception_handlers={
        HTTPException: handle_http_exception,
        HTTP_500_INTERNAL_SERVER_ERROR: handle_internal_error,
    },
    ...,
)

In your own handlers, HTTPException(..., extra={"reason": "..."}) sets the reason, and error_response(status, message, [ErrorItem(...)]) builds a response directly.

Configuration

KeycloakAdminConfig.from_env() reads these variables (prefix KEYCLOAK_, change it with from_env(prefix=...)):

Keyword arguments refine the result:

• keycloak={...} passes extra arguments to litestar_keycloak.KeycloakConfig, e.g. exclude_patterns, jwks_cache_ttl, optional_audiences;
• other arguments override KeycloakAdminConfig fields:

KeycloakAdminConfig(keycloak=KeycloakConfig(...), ...) can also be built directly, without environment variables.

Command line

The plugin adds a keycloak group to the litestar CLI. Its main use is creating the first administrator, when nobody can log in to /register yet:

KEYCLOAK_NEW_USER_PASSWORD='temporary-secret' \
  litestar keycloak create-user root --role admin --exist-ok

• --role may be repeated to assign several roles;
• the password comes from KEYCLOAK_NEW_USER_PASSWORD or an interactive prompt, never from command-line arguments, which other processes can see;
• the password is temporary: the user replaces it at first login;
• --exist-ok exits successfully if the user already exists, so the command is safe to run on every deployment.

Using the client in your own code

KeycloakAdminClient is available to any handler as the keycloak_admin dependency, for user-management needs beyond the built-in endpoints. For example, an administrator resetting a user's password to a temporary one, which the user replaces at the next login:

from dataclasses import dataclass

from litestar import post
from litestar.di import NamedDependency
from litestar.exceptions import NotFoundException
from litestar.params import FromPath
from litestar_keycloak_admin import KeycloakAdminClient, requires_admin


@dataclass
class ResetPasswordRequest:
    password: str


@post("/users/{username:str}/reset-password", guards=[requires_admin], status_code=204)
async def reset_password(
    username: FromPath[str],
    data: ResetPasswordRequest,
    keycloak_admin: NamedDependency[KeycloakAdminClient],
) -> None:
    subject = await keycloak_admin.find_user_id(username)
    if subject is None:
        raise NotFoundException(f"User {username!r} not found")
    await keycloak_admin.set_password(subject, data.password, temporary=True)

Its errors (KeycloakClientError and subclasses) are turned into the HTTP responses listed in Errors wherever they are raised.

Public API

Everything below is importable from litestar_keycloak_admin; other modules are internal.

The package follows Semantic Versioning; while it is in 0.x, a minor release may contain breaking changes, which are listed in the changelog.

Security notes

• Password grant. The login endpoints use OAuth's Resource Owner Password Credentials grant: the password passes through your backend to Keycloak and is never stored. It is what allows a custom login form, but OAuth 2.1 deprecates it, and it rules out Keycloak features that need its own login page (social login, WebAuthn, its two-factor flows). If you need them, use litestar-keycloak's own routes (Authorization Code flow) instead of the public endpoints here.
• Refresh token. By default it stays in an httponly, secure, SameSite=Strict cookie scoped to auth_path, out of reach of JavaScript. secure cookies need HTTPS; disable it only for local development.
• Admin credentials. Prefer a service account with manage-users and view-realm to a master-realm administrator in production.

Development

uv sync --group dev
uv run ruff check .
uv run ruff format --check .
uv run pytest
uv build
uv run twine check --strict dist/*

The tests start a fake Keycloak on aiohttp.web (tests/fake_keycloak.py), so they run real HTTP against both this package and litestar-keycloak without a Keycloak instance.

See CONTRIBUTING.md for contribution guidelines, CHANGELOG.md for user-visible changes, and the release guide for the release process.

License

Distributed under the MIT License.