fastapi-keycloak-middleware

What it is and what it does

fastapi-keycloak-middleware is a FastAPI middleware that bridges your application to Keycloak for user authentication and authorization. It handles OIDC token validation (either locally using Keycloak's public key or via the token introspection endpoint), stores user identity and authorization scopes in the request context, and provides decorators and dependencies to enforce role or permission checks on individual endpoints. The package wraps python-keycloak and integrates with Starlette's authentication mechanisms, so it fits naturally into the FastAPI ecosystem.

You use it by installing the middleware into your FastAPI app, configuring it with your Keycloak server details, and then decorating endpoints or using dependency injection to require specific roles or permissions. It supports custom callbacks to fetch user objects from your database and to map Keycloak roles to application-specific permissions, making it flexible for varied authorization schemes.

Use it for:

• Protect FastAPI endpoints with Keycloak authentication, validating bearer tokens on each request.
• Enforce role-based access control (RBAC) on specific routes using decorators without manual token inspection.
• Retrieve the authenticated user object or authorization result within endpoint handlers via FastAPI dependencies.
• Integrate a FastAPI microservice into an existing Keycloak-based identity infrastructure.
• Map Keycloak roles to application-specific permissions through custom callback functions.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

FastAPI middleware that integrates Keycloak for OIDC-based authentication and authorization, validating access tokens and enforcing role-based access control on endpoints.

Yes, if you are already using Keycloak and FastAPI. The package significantly reduces boilerplate for token validation and role enforcement. However, verify the license before use in commercial settings, and note that maintenance is aging (215 days since last release)—acceptable for stable middleware but monitor for security updates or breaking changes in FastAPI or Keycloak.

Install

fastapi-keycloak-middleware on PyPI

pip install fastapi-keycloak-middleware

uv add fastapi-keycloak-middleware

poetry add fastapi-keycloak-middleware

Installing fastapi-keycloak-middleware

Before you install

Low install friction; depends only on fastapi and python-keycloak. Maintenance status is aging—last release was 215 days ago—so expect slower response to issues, though no known vulnerabilities are recorded.

License in practice

License treatment is unclear; no SPDX identifier or raw license text is available in the metadata. Verify the actual license before adopting in a commercial or restricted-license context.

Quickstart

pip install fastapi-keycloak-middleware

from fastapi import FastAPI, Depends
from fastapi_keycloak_middleware import FastAPIKeycloakMiddleware

app = FastAPI()
app.add_middleware(FastAPIKeycloakMiddleware, server_url="https://keycloak.example.com", client_id="my-app", realm="my-realm")

@app.get("/protected")
async def protected(request):
    return {"user": request.user}

Requires a running Keycloak server and valid OIDC client credentials (server URL, client ID, realm name).

Verify before relying

• Whether the package supports fine-grained authorization via Keycloak Authorization services (mentioned as a future plan in the description).
• Current state of the repository (archived status, commit history, community activity) to assess true maintenance health beyond release date.

Package facts

Evidence: fastapi_keycloak_middleware-1.6.0-py3-none-any.whl

Tags

More Security packages