Metadata-Version: 2.4
Name: auth-middleware
Version: 0.2.13
Summary: Async Auth Middleware for FastAPI/Starlette
Project-URL: Homepage, https://impalah.github.io/auth-middleware/
Project-URL: Documentation, https://impalah.github.io/auth-middleware/
Project-URL: Repository, https://github.com/impalah/auth-middleware
Project-URL: Source, https://github.com/impalah/auth-middleware
Author-email: impalah <impalah@gmail.com>
License: MIT
License-File: LICENSE
Keywords: auth,fastapi,middleware,starlette
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration :: Authentication/Directory
Requires-Python: >=3.10
Requires-Dist: aiomysql>=0.2.0
Requires-Dist: asyncpg>=0.30.0
Requires-Dist: click>=8.1.8
Requires-Dist: fastapi>=0.115.6
Requires-Dist: httpx>=0.28.1
Requires-Dist: loguru>=0.7.3
Requires-Dist: pydantic-settings>=2.10.1
Requires-Dist: pydantic[email]>=2.10.4
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: python-jose[cryptography]>=3.3.0
Requires-Dist: sqlalchemy[asyncio]>=2.0.36
Requires-Dist: svix-ksuid>=0.6.2
Description-Content-Type: text/markdown

# auth-middleware

Async Auth Middleware for FastAPI/Starlette.

## Installation

Using pip:

```bash
pip install auth-middleware
```

Using poetry

```bash
poetry add auth-middleware
```

## How to use it

Auth Middleware follows the middleware protocol and, therefore, should be added as a middleware to your FastApi or Starlette application.

The steps, using FastAPI:

```python

from fastapi import FastAPI, Depends

from starlette.requests import Request
from starlette.responses import Response

# Step 1: import the functions to control authentication
from auth_middleware.functions import require_groups, require_user
# Step 2: import the Middleware to use
from auth_middleware.jwt_auth_middleware import JwtAuthMiddleware
# Step 3: import the auth provider
from auth_middleware.providers.cognito import CognitoProvider
# Implement group provider (if any)
from auth_middleware.providers.authz.cognito_groups_provider import (
    CognitoGroupsProvider,
)


app: FastAPI = FastAPI()

# Step 4: Add Middleware with a Cognito auth Provider
auth_provider_settings: CognitoAuthzProviderSettings = CognitoAuthzProviderSettings(
    user_pool_id="My Pool Id",
    user_pool_region="AWS_REGION",
    jwt_token_verification_disabled=true,
)

app.add_middleware(
    JwtAuthMiddleware,
    auth_provider=CognitoProvider(
        settings=auth_provider_settings,
        groups_provider=CognitoGroupsProvider,
        # permissions_provider=SqlPermissionsProvider,
    ),
)


@app.get("/",
    dependencies=[
        # Step 5: add the authorization dependencies you want: require_user or requiere_groups
        # Depends(require_groups(["customer", "administrator"])),
        Depends(require_user()),
    ],)
async def root(request: Request):
    # Step 6: user information will be available in the request.state.current_user object
    return {"message": f"Hello {request.state.current_user.name}"}

```

Call the method sending the id_token provided by Cognito:

```bash
curl -X GET http://localhost:8000/ -H "Authorization: Bearer MY_ID_TOKEN"
```

## Middleware configuration

The middleware configuration is done by environment variables (or using and .env file if your project uses python-dotenv).

The main variables are shwon in the table below:

| Name                                        | Description                             | Values                                | Default                                                                |
| ------------------------------------------- | --------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------- |
| AUTH_MIDDLEWARE_LOG_LEVEL                   | Log level for the application           | DEBUG, INFO, WARNING, ERROR, CRITICAL | INFO                                                                   |
| AUTH_MIDDLEWARE_LOG_FORMAT                  | Log format                              | See python logger documentation       | %(log_color)s%(levelname)-9s%(reset)s %(asctime)s %(name)s %(message)s |
| AUTH_MIDDLEWARE_LOGGER_NAME                 | Auth middleware logger name             | A string                              | auth_middleware                                                        |
| AUTH_MIDDLEWARE_DISABLED                    | Auth middleware enabled/disabled        | false, true                           | false                                                                  |
| AUTH_MIDDLEWARE_JWKS_CACHE_INTERVAL_MINUTES | JWKS keys file refreshing interval      | An integer value                      | 20                                                                     |
| AUTH_MIDDLEWARE_JWKS_CACHE_USAGES           | JWKS keys refreshing interval (counter) | An integer value                      | 1000                                                                   |

## The User property

After authentication the Request object contains ifnormation about the current user in the state.current_user variable.

The table below shows the properties of the user object.

| Property | Description                                           |
| -------- | ----------------------------------------------------- |
| id       | Id of the user in the identity provider               |
| name     | User name (or id if not defined)                      |
| email    | User email (if any)                                   |
| groups   | Array of user groups as sent by the identity provider |

## Control authentication and authorization

There are two utility functions to control the authentication and authorization. These functions return an HttpException if the auth/authn fails.

The functions can be invoked directly or can be used as a dependency in frameworks as FastAPI.

To check if a user is logged in use require_user:

```python
require_user()
```

To check if a user has assigned a group or groups use require_groups:

```python
require_groups(["group1", "group2"])
```

## Authentication providers

### Amazon Cognito

TODO

### Azure Entra ID

TODO

### Google Idp

TODO

## Custom auth provider

TODO
