Skip to content

Commit

Permalink
Update README.md to enhance clarity and structure, including improved…
Browse files Browse the repository at this point in the history 
… descriptions, added table of contents, and refined installation instructions.
  • Loading branch information
@deepmancer
deepmancer committed Dec 10, 2024
1 parent 35fc483 commit dad927b
Showing 1 changed file with 123 additions and 57 deletions.
180 changes: 123 additions & 57 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,18 +1,19 @@
# FastAPI Auth JWT

<p align="center">
<img src="https://raw.githubusercontent.com/deepmancer/fastapi-auth-jwt/main/fastapi_auth_jwt_logo.png" alt="FastAPI Auth JWT">
<img src="https://raw.githubusercontent.com/deepmancer/fastapi-auth-jwt/main/fastapi_auth_jwt_logo.png" alt="FastAPI Auth JWT" style="width: 80%;">
</p>

<p align="center">
<em>Highly-customizable and ready-to-use session authentication for FastAPI applications </em>
<em>Seamless, production-ready JWT authentication for your FastAPI applications.</em>
</p>

<p align="center">
<a href="https://github.com/deepmancer/fastapi-auth-jwt/actions/" target="_blank">
<a href="https://github.com/deepmancer/fastapi-auth-jwt/actions" target="_blank">
<img src="https://github.com/deepmancer/fastapi-auth-jwt/workflows/Build/badge.svg" alt="Build Status">
</a>
<a href="https://pypi.org/project/fastapi-auth-jwt/" target="_blank">
<img src="https://img.shields.io/pypi/v/fastapi-auth-jwt.svg" alt="Package version">
<img src="https://img.shields.io/pypi/v/fastapi-auth-jwt.svg" alt="PyPI Version">
</a>
<a href="https://codecov.io/gh/deepmancer/fastapi-auth-jwt" target="_blank">
<img src="https://codecov.io/gh/deepmancer/fastapi-auth-jwt/branch/main/graph/badge.svg" alt="Coverage">
Expand All @@ -24,49 +25,95 @@

---

| **Source Code** | **Website** |
|:-----------------|:------------|
| <a href="https://github.com/deepmancer/fastapi-auth-jwt" target="_blank">github.com/deepmancer/fastapi-auth-jwt</a> | <a href="https://deepmancer.github.io/fastapi-auth-jwt/" target="_blank">deepmancer.github.io/fastapi-auth-jwt</a> |
| **Source Code** | **Documentation** | **Live Demos** |
|:----------------|:------------------|:---------------|
| [GitHub](https://github.com/deepmancer/fastapi-auth-jwt) | [Docs](https://deepmancer.github.io/fastapi-auth-jwt/) | [Examples](https://github.com/deepmancer/fastapi-auth-jwt/tree/main/examples) |

---

## **✨ Features**
## Table of Contents
- [FastAPI Auth JWT](#fastapi-auth-jwt)
- [Table of Contents](#table-of-contents)
- [🌟 Why FastAPI Auth JWT?](#-why-fastapi-auth-jwt)
- [📦 Installation](#-installation)
- [🚀 Getting Started](#-getting-started)
- [🛠️ 1. Define a User Model](#️-1-define-a-user-model)
- [⚙️ 2. Configure Authentication Settings](#️-2-configure-authentication-settings)
- [🔧 3. Initialize the Authentication Backend](#-3-initialize-the-authentication-backend)
- [🔌 4. Add Middleware to FastAPI](#-4-add-middleware-to-fastapi)
- [📚 5. Define Your Routes](#-5-define-your-routes)
- [🧰 Redis Extension](#-redis-extension)
- [⚙️ Key Components \& Configurations](#️-key-components--configurations)
- [📂 Example Projects](#-example-projects)
- [📚 Documentation](#-documentation)
- [🛡️ License](#️-license)
- [⭐ Get Involved](#-get-involved)

---

## 🌟 Why FastAPI Auth JWT?

**FastAPI Auth JWT** empowers developers to implement secure, reliable, and efficient JWT-based authentication in their FastAPI applications. With minimal setup and deep customization options, it helps projects of all sizes establish trust, protect sensitive endpoints, and scale seamlessly.

- 🚀 **Effortless Integration**: Seamlessly add JWT authentication to your FastAPI application with just a few lines of code.
- 🛠️ **Highly Customizable**: Tailor the authentication process to fit your specific needs, including custom user models and storage options.
- 🔄 **Sync and Async Support**: Works out of the box with both synchronous and asynchronous FastAPI applications.
- 💾 **Flexible Token Storage**: Supports in-memory token storage for simple applications and Redis for real-world, distributed backends.
- 🚀 **Quick Setup**: Integrate JWT authentication into new or existing FastAPI projects in just a few lines.
- 🛠️ **Configurable & Extensible**: Easily adapt authentication rules, user schemas, and token lifetimes to meet dynamic requirements.
- 🔄 **Sync & Async Compatible**: Whether your routes are synchronous or asynchronous, the middleware and backend integrate smoothly.
- 💾 **Multiple Storage Backends**: Start with in-memory caching for simplicity, then scale transparently to Redis for high-availability, distributed architectures.
- ✅ **Thoroughly Tested & Documented**: A well-structured codebase with comprehensive tests and clear documentation means you can rely on stable, predictable behavior.

## **📦 Installation**
---

To install the basic package:
## 📦 Installation

**Basic Installation**:
```bash
pip install fastapi-auth-jwt
```

If you want to use Redis for token storage, install the package with Redis support:

**With Redis Support**:
```bash
pip install fastapi-auth-jwt[redis]
```

## **🚀 Quick Start**
**From Source**:
1. Clone the repository:
```bash
git clone https://github.com/deepmancer/fastapi-auth-jwt.git
```
2. Navigate to the directory:
```bash
cd fastapi-auth-jwt
```
3. Install the package:
```bash
pip install .
```

**Requirements**:
- Python 3.8+
- FastAPI 0.65.2+

---

## 🚀 Getting Started

### **🛠️ Basic Setup**
Below is a high-level example to get you started. For more advanced use cases and patterns, refer to the [examples](#-example-projects) section and the [official docs](#-documentation).

1. **🧑‍💻 Define Your User Schema**: Create a Pydantic model representing the user.
### 🛠️ 1. Define a User Model
Create a simple Pydantic model representing your user entity.

```python
from pydantic import BaseModel, Field
from typing import Optional
class User(BaseModel):
username: str
password: str
token: Optional[str] = Field(None)
```

2. **⚙️ Configure Authentication Settings**: Set up your authentication configuration.
### ⚙️ 2. Configure Authentication Settings
Specify your JWT signing secrets, algorithms, and token expiration times.

```python
from pydantic import BaseModel
Expand All @@ -77,7 +124,8 @@ class AuthenticationSettings(BaseModel):
expiration_seconds: int = 3600 # 1 hour
```

3. **🔧 Initialize the Authentication Backend**: Create an instance of the `JWTAuthBackend`.
### 🔧 3. Initialize the Authentication Backend
Integrate the `JWTAuthBackend` using your settings and user schema.

```python
from fastapi_auth_jwt import JWTAuthBackend
Expand All @@ -88,7 +136,8 @@ auth_backend = JWTAuthBackend(
)
```

4. **🔌 Add Middleware to Your FastAPI Application**:
### 🔌 4. Add Middleware to FastAPI
Hook the authentication middleware into your application.

```python
from fastapi import FastAPI
Expand All @@ -99,48 +148,52 @@ app = FastAPI()
app.add_middleware(
JWTAuthenticationMiddleware,
backend=auth_backend,
exclude_urls=["/sign-up", "/login"],
exclude_urls=["/sign-up", "/login"], # Public endpoints
)
```

5. **📚 Create Routes**:
### 📚 5. Define Your Routes
Secure routes automatically validate tokens before accessing the request state.

```python
@app.post("/sign-up")
async def sign_up(request_data: RegisterSchema):
async def sign_up(user: User):
# Implement user creation logic here
return {"message": "User created"}
@app.post("/login")
async def login(request_data: LoginSchema):
async def login(user: User):
token = await auth_backend.create_token(
username=request_data.username,
password=request_data.password,
{"username": user.username, "password": user.password},
expiration=3600
)
return {"token": token}
@app.get("/profile-info")
async def get_profile_info(request: Request):
user: User = request.state.user
async def get_profile_info(request):
user = request.state.user
return {"username": user.username}
@app.post("/logout")
async def logout(request: Request):
user: User = request.state.user
async def logout(request):
user = request.state.user
await auth_backend.invalidate_token(user.token)
return {"message": "Logged out"}
```

### **🧰 Redis Extension**
---

## 🧰 Redis Extension

To enable Redis as the storage backend:
For production environments that require robust session management, enable Redis-backed storage:

```python
from fastapi_auth_jwt import RedisConfig, JWTAuthBackend
redis_config = RedisConfig(
host="localhost",
port=6379,
db=0,
db=0
)
auth_backend_redis = JWTAuthBackend(
Expand All @@ -152,45 +205,58 @@ auth_backend_redis = JWTAuthBackend(
app.add_middleware(
JWTAuthenticationMiddleware,
backend=auth_backend_redis,
exclude_urls=["/sign-up", "/login"],
exclude_urls=["/sign-up", "/login"]
)
```

## **⚙️ Configuration Options**
---

### `AuthConfig`
## ⚙️ Key Components & Configurations

- 🛡️ `secret` (str): Secret key for signing JWT tokens.
- 🧮 `jwt_algorithm` (str): Algorithm used for token encoding (default: `HS256`).
- ⏲️ `expiration_seconds` (int): Token expiration time in seconds (default: `3600`).
**AuthenticationSettings**:
- `secret`: JWT signing secret.
- `jwt_algorithm`: Algorithm for token signing (default: `"HS256"`).
- `expiration_seconds`: Token validity period in seconds.

### `StorageConfig`
**StorageConfig**:
- `storage_type`: Set to `MEMORY` or `REDIS` for distributed environments.

- 🗄️ `storage_type` (StorageTypes): Type of storage backend (`MEMORY` or `REDIS`).
**RedisConfig**:
- `host`, `port`, `db`: Core Redis connection parameters.
- `password`: Optional if your Redis server requires it.

### `RedisConfig`
With these configurations, you can tailor your authentication layer to match your exact operational needs—be it local development, CI/CD pipelines, or full-scale production deployments.

- 🌐 `host` (str): Redis server hostname (default: `localhost`).
- 🛠️ `port` (int): Redis server port (default: `6379`).
- 🗃️ `db` (int): Redis database index (default: `0`).
- 🔑 `password` (Optional[str]): Redis server password (default: `None`).
---

## **📂 Example Projects**
## 📂 Example Projects

For fully working examples, refer to the [examples directory](https://github.com/deepmancer/fastapi-auth-jwt/tree/main/examples) in the repository.
Check out the [examples directory](https://github.com/deepmancer/fastapi-auth-jwt/tree/main/examples) for ready-to-run scenarios, including both standard and Redis-backed workflows. Each example demonstrates best practices for integrating JWT authentication into real-world FastAPI applications.

## **📚 Documentation**
---

Complete documentation is available in the [docs directory](https://github.com/deepmancer/fastapi-auth-jwt/blob/main/docs/README.md).
## 📚 Documentation

## **📝 License**
Extensive and continuously updated documentation is available at the [official docs](https://deepmancer.github.io/fastapi-auth-jwt/). There you will find detailed setup guides, API references, configuration tips, and troubleshooting advice.

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
---

## **📬 Contact**
## 🛡️ License

For any questions, suggestions, or issues, please feel free to open an issue or reach out via [GitHub Issues](https://github.com/deepmancer/fastapi-auth-jwt/issues).
This project is licensed under the MIT License. See the [LICENSE](https://github.com/deepmancer/fastapi-auth-jwt/blob/main/LICENSE) file for more details.

---

With `fastapi-auth-jwt`, adding secure, flexible JWT-based authentication to your FastAPI applications is easier than ever. Get started today and enjoy a streamlined authentication experience!
## ⭐ Get Involved

Your feedback and contributions are welcome! Here’s how you can support and shape the future of **FastAPI Auth JWT**:

- ⭐ **Star** this repository to stay informed and show appreciation.
- 🖇️ **Fork** the project and experiment with new ideas.
- 🐛 **Report Issues** or request enhancements via [GitHub Issues](https://github.com/deepmancer/fastapi-auth-jwt/issues).
- 🤝 **Contribute** code, documentation, or examples to help others learn and succeed.
- 📬 **Reach Out** with questions, suggestions, or integration stories.

---

With **FastAPI Auth JWT**, you can implement secure, stable, and scalable JWT authentication in minutes—focusing on building great features instead of reinventing authentication logic.

0 comments on commit dad927b

Please sign in to comment.