Metadata-Version: 2.3
Name: fastapi-auth-gateway
Version: 1.2.1
Summary: FastAPI Auth Gateway
License: MIT
Author: Amil
Author-email: amilalizada@gmail.com
Requires-Python: >=3.10,<4.0
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Dist: aiohttp (>=3.11.11,<4.0.0)
Requires-Dist: fastapi (>=0.115.7,<0.116.0)
Requires-Dist: starlette (>=0.45.3,<0.46.0)
Project-URL: Homepage, https://github.com/amilalizada/fastapi-auth-gateway
Project-URL: Repository, https://github.com/amilalizada/fastapi-auth-gateway
Description-Content-Type: text/markdown

# FastAPI Authentication Gateway Middleware

This module provides middleware for verifying authorization tokens from request headers or cookies in a FastAPI application. It ensures secure authentication by validating tokens against an external authentication service.

# Features

- Middleware for FastAPI that intercepts requests for authentication validation.

- Supports token authentication via headers or cookies.

- Configurable validation service URL, headers, and timeout.

- Custom error messages and headers.

- Ability to exclude specific URLs from authentication.

## Installation

You can install the package using `pip`:

```sh
pip install fastapi-auth-gateway

Alternatively, if you prefer to use poetry for package dependencies:

poetry shell
poetry add fastapi-auth-gateway
```

# Usage

## Middleware Setup

To use the authentication middleware, include it in your FastAPI application:

```sh
from fastapi_auth_gateway import FastAPIAuthGateway, AuthLocation

app = FastAPI()

app.add_middleware(
    FastAPIAuthGateway,
    validation_service_url="https://auth.example.com/validate",
    key="Authorization",
    auth_location=AuthLocation.HEADER,
    timeout=10,
    custom_headers={"X-Custom-Header": "Value"},
    custom_error={"error": "Unauthorized access"},
    exclude_urls=["/public", "/health"]
)
```

## Token Validation Process

- The middleware extracts the token from either the request header (Authorization) or a cookie.

- If a token is missing, it returns a 401 Unauthorized response.

- The token is validated against an external authentication service via AuthValidationClient.

- If the token is invalid, it returns the error response from the authentication service.

- If the token is valid, the request proceeds to the next middleware or endpoint.


# Components

`FastAPIAuthGateway`

A middleware that intercepts requests and verifies authentication tokens before allowing access to endpoints.

`AuthValidationClient`

A client that handles the authentication validation process using aiohttp to communicate with an external validation service.

`AuthLocation`

An enumeration defining where authentication tokens can be extracted from:

- `HEADER`: Extract token from request headers.

- `COOKIE`: Extract token from request cookies.

# Configuration Options

| Parameter | Type | Description |
| --- | --- | --- |
| `validation_service_url` | `str` | The URL of the authentication validation service. |
| `key` | `str` | The key used for token extraction (e.g., "Authorization"). |
| `auth_location` | `AuthLocation` | Defines whether authentication is handled via headers or cookies. |
| `timeout` | `int` | Timeout for authentication requests (in seconds). |
| `custom_headers` | `dict`(optional) | Custom headers to include in authentication requests. |
| `custom_error` | `dict`(optional) | Custom error message response for unauthorized access. |
| `exclude_urls` | `list`(optional) | List of endpoint paths to exclude from authentication. |

Example Response

If authentication fails, the middleware returns a `401 Unauthorized` response:
```sh
{
    "message": "Unauthorized"
}
```

# License

This project is licensed under the MIT License.

