Registry / security / fastapi-keycloak-middleware

fastapi-keycloak-middleware

library1.6.0pypypi✓ verified 86d ago

Middleware for FastAPI that authenticates users against a Keycloak server. Supports OIDC, role-based access, and token validation. Current version 1.6.0, requires Python >=3.11, <4. Release cadence is irregular.

security

pip install fastapi-keycloak-middleware

INSTALL

IMPORT

SIG · FASTAPI-KEYCLOAK-M

fastapi-keycloak-middleware

securitypythonv1.6.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

KeycloakMiddleware

✓ from fastapi_keycloak_middleware import KeycloakMiddleware

✗ from fastapi_keycloak_middleware.middleware import KeycloakMiddleware

Old import path before v1.5.0.

KeycloakConfiguration

✓ from fastapi_keycloak_middleware import KeycloakConfiguration

✗ from fastapi_keycloak_middleware.config import KeycloakConfiguration

Config class moved to top-level in v1.5.0.

Minimal FastAPI app with Keycloak authentication.

import os from fastapi import FastAPI from fastapi_keycloak_middleware import KeycloakConfiguration, KeycloakMiddleware app = FastAPI() config = KeycloakConfiguration( url=os.environ.get('KEYCLOAK_URL', 'http://localhost:8080'), realm=os.environ.get('KEYCLOAK_REALM', 'master'), client_id=os.environ.get('KEYCLOAK_CLIENT_ID', 'my-client'), client_secret=os.environ.get('KEYCLOAK_CLIENT_SECRET', ''), ) middleware = KeycloakMiddleware(app=app, configuration=config) app.add_middleware(middleware) @app.get('/') async def root(): return {'message': 'Hello World'}

Debug

Known issues

breakingIn v1.5.0, the import path changed: KeycloakMiddleware and KeycloakConfiguration are now at the package top level, not in submodules.

fix

Update imports to 'from fastapi_keycloak_middleware import KeycloakMiddleware, KeycloakConfiguration'.

affects: <1.5.0

deprecatedThe 'verify_token' parameter in KeycloakConfiguration was deprecated in v1.4.0 and removed in v1.5.0. Use 'skip_verification' instead.

fix

Replace 'verify_token=False' with 'skip_verification=True'.

affects: >=1.4.0,<1.5.0

gotchaMiddleware order matters: KeycloakMiddleware must be added before other middleware (like CORS) to ensure token validation occurs first.

fix

Add KeycloakMiddleware using app.add_middleware() before any other middleware.

affects: all

Errors

Common errors & fixes

ImportError: cannot import name 'KeycloakMiddleware' from 'fastapi_keycloak_middleware'

Using an outdated import path (e.g., from submodules) that existed before v1.5.0.

fix

Update import to: from fastapi_keycloak_middleware import KeycloakMiddleware

fastapi_keycloak_middleware.exceptions.ConfigurationError: Missing required configuration: 'url'

The KeycloakConfiguration object was not provided with a 'url' field.

fix

Ensure KeycloakConfiguration includes 'url' parameter (e.g., KeycloakConfiguration(url='...', realm='...', client_id='...')).

TypeError: object of type 'KeycloakMiddleware' has no len()

Misusing the middleware object: it should be passed to app.add_middleware(), not used as a decorator or added as a list.

fix

Use app.add_middleware(KeycloakMiddleware, configuration=config) instead of app.add_middleware(middleware_instance).

Upgrade

Version history

1.6.0latest on PyPI · released Jan 11, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

20 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

No resource links recorded.