API Documentation

This part of the documentation covers all the interfaces of Requests. For parts where Requests depends on external libraries, we document the most important right here and provide links to the canonical documentation.

Middleware

class fastapi_keycloak_middleware.KeycloakMiddleware(app: FastAPI, keycloak_configuration: KeycloakConfiguration, exclude_patterns: List[str] | None = None, user_mapper: Callable[[Dict[str, Any]], Awaitable[Any]] | None = None, scope_mapper: Callable[[List[str]], List[str]] | None = None)

This class represents the middleware for FastAPI. It will authenticate a user based on a token. It currently only supports one backend (Keycloak backend).

The middleware will add the user object to the request object. It optionally can also compile a list of scopes and add it to the request object as well, which can later be used for authoirzation.

Parameters:

• app (FastAPI) – The FastAPI app instance, is automatically passed by FastAPI

• keycloak_configuration (KeycloakConfiguration) – KeyCloak configuration object. For potential options, see the KeycloakConfiguration schema.

• exclude_paths (List[str], optional) – List of paths that should be excluded from authentication. Defaults to an empty list. The strings will be compiled to regular expressions and used to match the path. If the path matches, the middleware will skip authentication.

• user_mapper (Callable[ [Dict[str, Any]], Awaitable[Any] ], optional) – Custom async function that gets the userinfo extracted from AT and should return a representation of the user that is meaningful to you, the user of this library, defaults to None

• scope_mapper (Callable[[List[str]], List[str]], optional) – Custom async function that transforms the claim values extracted from the token to permissions meaningful for your application, defaults to None

Support Classes

class fastapi_keycloak_middleware.AuthorizationResult(*, method: None | AuthorizationMethod = None, authorized: bool = False, matched_scopes: List[str] = [])

This class contains the schema representing an authorization result.

class fastapi_keycloak_middleware.KeycloakConfiguration(*, realm: str, url: str, client_id: str, client_secret: str, claims: list[str] = ['sub', 'name', 'family_name', 'given_name', 'preferred_username', 'email'], reject_on_missing_claim: bool = True, authentication_scheme: str = 'Bearer', authorization_method: AuthorizationMethod = AuthorizationMethod.NONE, authorization_claim: str = 'roles', use_introspection_endpoint: bool = False)

This class contains the schema to configure Keycloak.

class fastapi_keycloak_middleware.AuthorizationMethod(value)

This Enum specifies the authorization methods.

class fastapi_keycloak_middleware.MatchStrategy(value)

This Enum specifies the authorization match strategy.

Decorators

These decorators can be used to wrap certain paths in your FastAPI application.

fastapi_keycloak_middleware.require_permission(permissions: str | List[str], match_strategy: MatchStrategy = MatchStrategy.AND) → Callable

Decorator to check if a user has a specific permission.

fastapi_keycloak_middleware.strip_request(func)

Wrapper that strips the request argument from kwargs

FastAPI Depdencies

These are the dependencies that you can use in your FastAPI application.

async fastapi_keycloak_middleware.get_user(request: Request) → Any

This function can be used as FastAPI dependency to easily retrieve the user object

async fastapi_keycloak_middleware.get_authorization_result(authorization_result: AuthorizationResult | None = None) → AuthorizationResult

This function can be used as FastAPI dependency and returns the authorization result