litestar-keycloak-admin 0.1.0__tar.gz

litestar_keycloak_admin-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Korolev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

litestar_keycloak_admin-0.1.0/PKG-INFO

@@ -0,0 +1,510 @@
+Metadata-Version: 2.4
+Name: litestar-keycloak-admin
+Version: 0.1.0
+Summary: Keycloak account and user administration for Litestar applications
+Keywords: authentication,keycloak,litestar,oauth2,oidc
+Author: Alexander Korolev
+Author-email: Alexander Korolev <alexkorolex@bk.ru>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: click>=8.1
+Requires-Dist: litestar>=2.24.0
+Requires-Dist: litestar-keycloak>=0.3.2,<0.4
+Requires-Python: >=3.12
+Project-URL: Changelog, https://github.com/alexkorolex/litestar_keycloak_admin/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/alexkorolex/litestar_keycloak_admin#readme
+Project-URL: Issues, https://github.com/alexkorolex/litestar_keycloak_admin/issues
+Project-URL: Repository, https://github.com/alexkorolex/litestar_keycloak_admin
+Description-Content-Type: text/markdown
+
+# litestar-keycloak-admin
+
+[![PyPI](https://img.shields.io/pypi/v/litestar-keycloak-admin)](https://pypi.org/project/litestar-keycloak-admin/)
+[![Python](https://img.shields.io/pypi/pyversions/litestar-keycloak-admin)](https://pypi.org/project/litestar-keycloak-admin/)
+[![CI](https://github.com/alexkorolex/litestar_keycloak_admin/actions/workflows/ci.yml/badge.svg)](https://github.com/alexkorolex/litestar_keycloak_admin/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/alexkorolex/litestar_keycloak_admin/blob/main/LICENSE)
+
+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](https://github.com/alexkorolex/litestar_keycloak_admin#security-notes) before using it in production.
+
+The package is built on top of [litestar-keycloak](https://github.com/smirnoffmg/litestar-keycloak)
+and complements it rather than replacing it:
+
+| Concern | Handled by |
+| --- | --- |
+| Validating access tokens (JWKS, `iss`, `aud`, `exp`) | `litestar-keycloak` |
+| `current_user` injection, `require_roles` / `require_scopes` guards | `litestar-keycloak` |
+| Login with username and password, refresh, logout | **this package** |
+| Replacing a temporary password at first login | **this package** |
+| Own profile and password | **this package** |
+| Listing realm roles, registering users | **this package** |
+| Creating users from the command line (e.g. the first admin) | **this package** |
+
+`KeycloakAdminPlugin` installs `litestar-keycloak`'s `KeycloakPlugin` for you, so an application
+registers exactly one plugin.
+
+**Contents:**
+[Installation](https://github.com/alexkorolex/litestar_keycloak_admin#installation) ·
+[Quick start](https://github.com/alexkorolex/litestar_keycloak_admin#quick-start) ·
+[Keycloak setup](https://github.com/alexkorolex/litestar_keycloak_admin#keycloak-setup) ·
+[Protecting routes](https://github.com/alexkorolex/litestar_keycloak_admin#protecting-routes) ·
+[Login flow](https://github.com/alexkorolex/litestar_keycloak_admin#login-flow) ·
+[Endpoints](https://github.com/alexkorolex/litestar_keycloak_admin#endpoints) ·
+[Errors](https://github.com/alexkorolex/litestar_keycloak_admin#errors) ·
+[Configuration](https://github.com/alexkorolex/litestar_keycloak_admin#configuration) ·
+[Command line](https://github.com/alexkorolex/litestar_keycloak_admin#command-line) ·
+[Using the client](https://github.com/alexkorolex/litestar_keycloak_admin#using-the-client-in-your-own-code) ·
+[Public API](https://github.com/alexkorolex/litestar_keycloak_admin#public-api) ·
+[Security notes](https://github.com/alexkorolex/litestar_keycloak_admin#security-notes)
+
+## Installation
+
+Python 3.12 or newer is required.
+
+```bash
+# 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
+
+```python
+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](https://github.com/alexkorolex/litestar_keycloak_admin#endpoints)).
+
+A minimal local environment looks like this:
+
+```dotenv
+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:
+
+```json
+{
+  "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`:
+
+```python
+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](https://github.com/alexkorolex/litestar_keycloak_admin#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`.
+
+## Endpoints
+
+All paths are relative to `auth_path` (default `/auth`).
+
+### Public (no token)
+
+| Method and path | Body | Success |
+| --- | --- | --- |
+| `POST /login` | `username`, `password` | `200`, `TokenResponse` |
+| `POST /initial-password` | `username`, `password` (the temporary one), `new_password` | `200`, `TokenResponse` |
+| `POST /refresh` | `refresh_token` (only without the cookie) | `200`, `TokenResponse` |
+| `POST /logout` | `refresh_token` (only without the cookie) | `204` |
+
+`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
+
+| Method and path | Body | Success |
+| --- | --- | --- |
+| `GET /me` | | `200`, `UserResponse` |
+| `PATCH /me` | any of `first_name`, `last_name`, `email` (`""` removes the e-mail) | `200`, `UserResponse` |
+| `POST /password` | `current_password`, `new_password` | `204` |
+
+`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
+
+| Method and path | Body | Success |
+| --- | --- | --- |
+| `GET /roles` | | `200`, `[{"name", "description"}]` |
+| `POST /register` | `username`, `password`, `roles: [str]`, optional `email`, `first_name`, `last_name` | `201`, `UserResponse` |
+
+`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:
+
+```json
+{
+  "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`).
+
+| Status | `reason` | When |
+| --- | --- | --- |
+| `400` | `invalidParameter` | A field is missing, has the wrong type or fails a check (password too short, no roles); one item per field |
+| `400` | `invalid` | Keycloak refused the input: role missing from the realm, password breaks the realm's policy |
+| `400` | `badRequest` | Malformed request, e.g. invalid JSON |
+| `401` | `required` | No access token, or no session to refresh |
+| `401` | `expired` | The access token has expired: refresh it |
+| `401` | `authError` | Invalid token, wrong credentials, expired or ended session |
+| `403` | `passwordChangeRequired` | Login with a temporary password: call `/initial-password` |
+| `403` | `insufficientPermissions` | The caller lacks a required role |
+| `403` | `insufficientScope` | The token lacks a required scope |
+| `409` | `conflict` | User or e-mail already exists; `/initial-password` for an account without a temporary password |
+| `500` | `internalError` | Unexpected server error; no details are exposed |
+| `502` | `backendError` | Keycloak answered with something unexpected |
+| `503` | `backendError` | Keycloak is unreachable |
+
+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:
+
+```python
+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=...)`):
+
+| Variable | Required | Meaning |
+| --- | --- | --- |
+| `INTERNAL_URL` | yes | Where the backend reaches Keycloak, e.g. `http://keycloak:8080` |
+| `REALM` | yes | Realm name |
+| `CLIENT_ID` | yes | The confidential client (see [Keycloak setup](https://github.com/alexkorolex/litestar_keycloak_admin#keycloak-setup)) |
+| `CLIENT_SECRET` | yes | Its secret |
+| `ISSUER` | no | Expected `iss`: the URL users reach Keycloak at, plus `/realms/<realm>`. Needed when it differs from `INTERNAL_URL`, e.g. behind a reverse proxy |
+| `AUDIENCE` | no | Expected `aud`; defaults to `CLIENT_ID` |
+| `ADMIN`, `ADMIN_PASSWORD` | no | Master-realm administrator for the Admin REST API; without them the client's service account is used |
+| `REFRESH_COOKIE_PATH` | no | Cookie path when a reverse proxy serves the API under a prefix, e.g. `/api/auth`; otherwise the browser never sends the cookie back |
+
+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:
+
+| Field | Default | Meaning |
+| --- | --- | --- |
+| `admin_role` | `"admin"` | Realm role allowed to list roles and register users |
+| `assignable_roles` | `()` | Roles registration may assign; empty means every realm role |
+| `auth_path` | `"/auth"` | Where the endpoints are mounted |
+| `refresh_cookie` | `RefreshCookieConfig()` | `enabled`, `name` (`kc_refresh`), `path`, `secure`, `samesite` (`strict`) |
+| `min_password_length` | `8` | Checked before Keycloak's own password policy |
+| `timeout` | `10` | Seconds per request to Keycloak |
+
+`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:
+
+```bash
+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:
+
+```python
+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)
+```
+
+| Method | Does |
+| --- | --- |
+| `login(username, password)` | Password grant; returns Keycloak's token response |
+| `refresh(refresh_token)` | New tokens for a live session |
+| `logout(refresh_token)` | Ends the session |
+| `check_password(username, password)` | Whether the password is the user's current one |
+| `complete_initial_password(username, password, new_password)` | Replaces a temporary password and logs in |
+| `list_roles()` | The realm's own roles, without Keycloak's built-in ones |
+| `create_user(username=..., password=..., roles=..., ...)` | Creates a user, returns its subject id |
+| `update_user(subject, **representation)` | Partial update with Keycloak's `UserRepresentation` field names |
+| `set_password(subject, password, temporary=False)` | Sets a password |
+| `find_user_id(username)` | Subject id for an exact username, or `None` |
+
+Its errors (`KeycloakClientError` and subclasses) are turned into the HTTP responses listed in
+[Errors](https://github.com/alexkorolex/litestar_keycloak_admin#errors) wherever they are raised.
+
+## Public API
+
+Everything below is importable from `litestar_keycloak_admin`; other modules are internal.
+
+| Name | Kind |
+| --- | --- |
+| `KeycloakAdminPlugin` | The plugin to register on the application |
+| `KeycloakAdminConfig`, `RefreshCookieConfig` | Configuration |
+| `KeycloakAdminClient` | Asynchronous client for Keycloak's token endpoints and Admin REST API |
+| `requires_admin` | Guard: the caller holds `admin_role` |
+| `KeycloakSessionController`, `KeycloakAccountController`, `UserResponse` | The built-in endpoints and their user model |
+| `handle_http_exception`, `handle_internal_error`, `error_response`, `ErrorItem` | The error format |
+| `KeycloakClientError`, `KeycloakUnavailableError`, `KeycloakLoginError`, `PasswordChangeRequiredError`, `KeycloakAdminError` | Client exceptions |
+
+The package follows [Semantic Versioning](https://semver.org/); while it is in `0.x`, a minor
+release may contain breaking changes, which are listed in the
+[changelog](https://github.com/alexkorolex/litestar_keycloak_admin/blob/main/CHANGELOG.md).
+
+## 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
+
+```bash
+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](https://github.com/alexkorolex/litestar_keycloak_admin/blob/main/CONTRIBUTING.md)
+for contribution guidelines,
+[CHANGELOG.md](https://github.com/alexkorolex/litestar_keycloak_admin/blob/main/CHANGELOG.md)
+for user-visible changes, and the
+[release guide](https://github.com/alexkorolex/litestar_keycloak_admin/blob/main/docs/releasing.md)
+for the release process.
+
+## License
+
+Distributed under the
+[MIT License](https://github.com/alexkorolex/litestar_keycloak_admin/blob/main/LICENSE).