FastAPI Keycloak Middleware

Full documentation is available at Read The Docs

This package provides a middleware for FastAPI that simplifies integrating with Keycloak for authentication and authorization. It supports OIDC and supports validating access tokens, reading roles and basic authentication. In addition it provides several dependencies to easily integrate into your FastAPI application.

It relies on the python-keycloak package, which is the only dependency outside of the FastAPI ecosystem which would be installed anyway. Shoutout to the author of fastapi-auth-middleware which served as inspiration for this package and some of its code.

In the future, I plan to add support for fine grained authorization using Keycloak Authorization services.

Motivation

Using FastAPI and Keycloak quite a lot, and keeping to repeat myself quite a lot when it comes to authentiating users, I decided to create this library to help with this.

There is a clear separation between the authentication and authorization:

• Authentication is about verifying the identity of the user (who they are). This is done by an authentication backend that verifies the users access token obtained from the identity provider (Keycloak in this case).
• Authorization is about deciding which resources can be accessed. This package provides convenience dependencies to enforce certain roles or permissions on FastAPI endpoints.

Installation

Install the package using poetry:

poetry add fastapi-keycloak-middleware

or pip:

pip install fastapi-keycloak-middleware

Features

The package helps with:

• An easy to use middleware that validates the request for an access token
• Validation can done in one of two ways:
  • Validate locally using the realm public keys (JWKS) obtained from Keycloak, supporting key rotation without restarts
  • Validate using the Keycloak token introspection endpoint
• Using Starlette authentication mechanisms to store both the user object as well as the authorization scopes in the Request object
• Ability to provide custom callback functions to retrieve the user object (e.g. from your database) and to provide an arbitrary mapping to authentication scopes (e.g. roles to permissions)
• Support for service principals (client credentials tokens) with a configurable detection, working with any identity provider
• A dependency to enforce certain roles or permissions on FastAPI endpoints, for users and services alike
• Convenience dependencies to retrieve the user or service object, the authorization scopes or all token claims within the FastAPI endpoint

Upgrading from 1.x? See the migration guide.

Acknowledgements

This package is heavily inspired by fastapi-auth-middleware which provides some of the same functionality but without the direct integration into Keycloak. Thanks for writing and providing this great piece of software!

Contributing

The client is written in pure Python. Any changes or pull requests are more than welcome, but please adhere to the code style.

Ruff is used both for code formatting and linting. Before committing, please run the following command to ensure that your code is properly formatted:

ruff check .
ruff format .

A pre-commit hook configuration is supplied as part of the project.

Development

This project is using Act to handle local development tasks. It is used to work locally and also to test Github actions before deploying them.