authly

Name	authly JSON
Version	0.1.4 JSON
	download
home_page	None
Summary	Authentication and Authorization for Python FastAPI
upload_time	2025-02-15 17:06:09
maintainer	None
docs_url	None
author	Ove Ranheim
requires_python	<4.0,>=3.11
license	None
keywords
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # Authly

Authly is a robust Python framework for Authentication and User Token Handling built on FastAPI. It provides secure, scalable, and easy-to-integrate authentication services with features like JWT token management, user sessions, and secure password handling.

## Features

- **Secure Authentication**
  - JWT-based authentication with access and refresh tokens
  - Password hashing with bcrypt
  - Rate limiting and brute force protection
  - Secure token storage and management

- **User Management**
  - User registration and verification
  - Role-based access control (admin/user)
  - User profile management
  - Session management

- **Token Management**
  - Automatic token rotation
  - Token invalidation and cleanup
  - Refresh token handling
  - Token blacklisting

- **Security Features**
  - Secure secret management
  - CORS protection
  - Security headers
  - Rate limiting

- **Database Integration**
  - PostgreSQL support with psycopg
  - Connection pooling
  - Transaction management
  - Vector support (pgvector)

## Installation

```bash
pip install authly
```

Or with Poetry:

```bash
poetry add authly
```

## Quick Start

1. Create a new project and install dependencies:

```bash
poetry new myproject
cd myproject
poetry add authly
```

2. Set up your environment variables:

```bash
# .env
JWT_SECRET_KEY="your-production-secret-here"
JWT_REFRESH_SECRET_KEY="your-refresh-secret-key-here"
JWT_ALGORITHM="HS256"
ACCESS_TOKEN_EXPIRE_MINUTES=30
REFRESH_TOKEN_EXPIRE_DAYS=7
```

3. Create your FastAPI application:

```python
from fastapi import FastAPI
from authly import Authly, AuthlyConfig
from authly.config import EnvSecretProvider
from authly.api import auth_router, users_router

# Initialize configuration
secret_provider = EnvSecretProvider()
config = AuthlyConfig.load(secret_provider)

# Create database pool
pool = AsyncConnectionPool(
    "postgresql://user:password@localhost:5432/db"
)

# Initialize Authly
authly = Authly.initialize(pool, config)

# Create FastAPI app
app = FastAPI()

# Include Authly routers
app.include_router(auth_router, prefix="/api/v1")
app.include_router(users_router, prefix="/api/v1")
```

## Sequence diagrams

### System Architecture
- [🏗️ Component Architecture](https://github.com/descoped/authly/blob/master/docs/component-architecture.md)

### Authentication Flows
- [🔐 User Registration and Verification Flow](https://github.com/descoped/authly/blob/master/docs/user-registration-and-verification-flow.md)
- [🔑 User Authentication Flow](https://github.com/descoped/authly/blob/master/docs/user-authentication-flow.md)
- [🚪 Logout Flow](https://github.com/descoped/authly/blob/master/docs/logout-flow.md)

### Token Management
- [🔄 Token Refresh Flow](https://github.com/descoped/authly/blob/master/docs/token-refresh-flow.md)
- [📊 State Diagram for Token Lifecycle](https://github.com/descoped/authly/blob/master/docs/state-diagram-for-token-lifecycle.md)
- [📊 State Diagram for User Account](https://github.com/descoped/authly/blob/master/docs/state-diagram-for-user-account.md)


## API Documentation

### Authentication Endpoints

#### POST /auth/token
Login and obtain access token.

**Request Body:**
```json
{
    "username": "string",
    "password": "string",
    "grant_type": "password"
}
```

**Response:**
```json
{
    "access_token": "string",
    "refresh_token": "string",
    "token_type": "Bearer",
    "expires_in": 1800
}
```

**Status Codes:**
- 200: Successful login
- 400: Invalid request body
- 401: Invalid credentials
- 403: Account not verified/inactive
- 429: Too many requests

#### POST /auth/refresh
Refresh access token using refresh token.

**Request Body:**
```json
{
    "refresh_token": "string",
    "grant_type": "refresh_token"
}
```

**Response:**
```json
{
    "access_token": "string",
    "refresh_token": "string",
    "token_type": "Bearer",
    "expires_in": 1800
}
```

**Status Codes:**
- 200: Token refreshed successfully
- 400: Invalid refresh token
- 401: Invalid or expired refresh token

#### POST /auth/logout
Logout and invalidate all active tokens.

**Headers:**
- Authorization: Bearer {access_token}

**Response:**
```json
{
    "message": "Successfully logged out",
    "invalidated_tokens": 2
}
```

**Status Codes:**
- 200: Successful logout
- 401: Invalid token
- 500: Server error

### User Management Endpoints

#### POST /users/
Create a new user account.

**Request Body:**
```json
{
    "username": "string",
    "email": "string",
    "password": "string"
}
```

**Response:**
```json
{
    "id": "uuid",
    "username": "string",
    "email": "string",
    "created_at": "datetime",
    "updated_at": "datetime",
    "last_login": "datetime",
    "is_active": true,
    "is_verified": false,
    "is_admin": false
}
```

**Status Codes:**
- 201: User created successfully
- 400: Invalid request body or duplicate username/email
- 500: Server error

#### GET /users/me
Get current user information.

**Headers:**
- Authorization: Bearer {access_token}

**Response:**
```json
{
    "id": "uuid",
    "username": "string",
    "email": "string",
    "created_at": "datetime",
    "updated_at": "datetime",
    "last_login": "datetime",
    "is_active": true,
    "is_verified": true,
    "is_admin": false
}
```

**Status Codes:**
- 200: Success
- 401: Not authenticated
- 403: Forbidden

#### GET /users/{user_id}
Get user information by ID.

**Headers:**
- Authorization: Bearer {access_token}

**Parameters:**
- user_id: UUID of the user

**Response:**
```json
{
    "id": "uuid",
    "username": "string",
    "email": "string",
    "created_at": "datetime",
    "updated_at": "datetime",
    "last_login": "datetime",
    "is_active": true,
    "is_verified": true,
    "is_admin": false
}
```

**Status Codes:**
- 200: Success
- 404: User not found
- 401: Not authenticated

#### PUT /users/{user_id}
Update user information.

**Headers:**
- Authorization: Bearer {access_token}

**Parameters:**
- user_id: UUID of the user

**Request Body:**
```json
{
    "username": "string",
    "email": "string",
    "password": "string",
    "is_active": true,
    "is_verified": true,
    "is_admin": false
}
```

**Response:**
```json
{
    "id": "uuid",
    "username": "string",
    "email": "string",
    "created_at": "datetime",
    "updated_at": "datetime",
    "last_login": "datetime",
    "is_active": true,
    "is_verified": true,
    "is_admin": false
}
```

**Status Codes:**
- 200: Success
- 400: Invalid request body
- 401: Not authenticated
- 403: Forbidden
- 404: User not found

#### DELETE /users/{user_id}
Delete a user account.

**Headers:**
- Authorization: Bearer {access_token}

**Parameters:**
- user_id: UUID of the user

**Status Codes:**
- 204: Successfully deleted
- 401: Not authenticated
- 403: Forbidden
- 404: User not found

#### PUT /users/{user_id}/verify
Verify a user account.

**Headers:**
- Authorization: Bearer {access_token}

**Parameters:**
- user_id: UUID of the user

**Response:**
```json
{
    "id": "uuid",
    "username": "string",
    "email": "string",
    "created_at": "datetime",
    "updated_at": "datetime",
    "last_login": "datetime",
    "is_active": true,
    "is_verified": true,
    "is_admin": false
}
```

**Status Codes:**
- 200: Successfully verified
- 401: Not authenticated
- 403: Forbidden
- 404: User not found

## Configuration

Authly can be configured through environment variables or configuration providers:

```python
from authly.config import FileSecretProvider, StaticSecretProvider

# Using environment variables
provider = EnvSecretProvider()

# Using file-based secrets
provider = FileSecretProvider(Path("secrets.json"))

# Using static secrets (for testing)
provider = StaticSecretProvider(
    secret_key="test-secret-key",
    refresh_secret_key="test-refresh-key"
)
```

## Database Setup

1. Create the required database and user:

```sql
CREATE USER authly WITH PASSWORD 'your_password';
CREATE DATABASE authly_db;
GRANT ALL PRIVILEGES ON DATABASE authly_db TO authly;
```

2. Run the initialization scripts:

```sql
-- Enable required extensions
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

-- Create tables
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    username VARCHAR(50) UNIQUE NOT NULL,
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    -- Additional fields...
);

CREATE TABLE tokens (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    token_jti VARCHAR(64) NOT NULL UNIQUE,
    -- Additional fields...
);
```

## Security Features

### Password Hashing and Storage

Authly uses bcrypt for secure password hashing with the following security measures:

- Automatic salt generation for each password
- Configurable work factor for future-proofing against hardware improvements
- Memory-hard hashing algorithm resistant to GPU/ASIC attacks

Example implementation:

```python
from authly.auth import get_password_hash, verify_password

# Hash password with bcrypt
hashed = get_password_hash("user_password")

# Verify password - timing-safe comparison
is_valid = verify_password("user_password", hashed)
```

### Password Hashing with bcrypt in Terminal

This guide shows how to generate bcrypt password hashes using Terminal commands, similar to what authentication libraries do under the hood.

#### Quick Start

```bash
htpasswd -nbB username password
```

This generates a bcrypt hash in the format: `username:$2y$05$...`

#### Installation

If htpasswd is not available:

```bash
brew install apache2
```

### Advanced Usage

#### Match Python's Default Cost Factor (12)

```bash
htpasswd -nbBC 12 username password
```

#### Python Equivalent

For reference, this is equivalent to:

```python
import bcrypt
bcrypt.hashpw(password.encode('utf-8'), bcrypt.gensalt(rounds=12))
```

### Hash Format

The output hash follows this structure:
- `$2y$` - bcrypt algorithm identifier
- `XX$` - cost factor (05 for htpasswd default, 12 for Python default)
- Rest of string - salt and hash combined

#### Notes
- Default cost factor in htpasswd is 5
- Default cost factor in Python's bcrypt is 12
- Both use the same underlying Blowfish-based bcrypt algorithm
- Higher cost factors are more secure but slower to compute


### Token Security

Authly implements a comprehensive token security system:

#### JWT Token Management
- Short-lived access tokens (configurable, default 30 minutes)
- Separate refresh tokens with longer lifetime
- JTI (JWT ID) claim for token revocation
- Token payload encryption for sensitive data
- Automatic token rotation on refresh

#### Token Storage and Validation
```python
# Token creation with JTI
access_token = create_access_token(
    data={"sub": user_id, "jti": token_jti},
    secret_key=config.secret_key,
    algorithm="HS256",
    expires_delta=30  # minutes
)

# Token validation
try:
    payload = decode_token(token, secret_key, algorithm="HS256")
    is_valid = await token_service.is_token_valid(payload["jti"])
except JWTError:
    raise InvalidToken()
```

#### Token Cleanup and Management
- Automatic cleanup of expired tokens
- Token blacklisting for immediate revocation
- Database-backed token storage for persistence
- Transaction-safe token operations

### Rate Limiting and Brute Force Protection

Comprehensive protection against automated attacks:

#### Rate Limiting Implementation
```python
from authly.api.rate_limiter import RateLimiter

# Configure rate limits
limiter = RateLimiter(
    max_requests=5,     # Maximum requests
    window_seconds=60   # Time window
)

# Usage in endpoint
async def login_endpoint():
    await limiter.check_rate_limit(f"login:{username}")
```

#### Login Security
- Progressive delays on failed attempts
- Account lockout after multiple failures
- IP-based rate limiting
- User agent tracking
- Geographic location monitoring (optional)

### Secure Session Management

Robust session handling features:

- Secure session creation and validation
- Session timeout management
- Concurrent session control
- Forced logout capabilities
- Session activity tracking

### Database Security

Secure database operations:

- Prepared statements for SQL injection prevention
- Connection pooling with SSL/TLS
- Transaction isolation
- Automatic connection encryption
- Least privilege database users

### API Security Headers

Comprehensive security headers implementation:

```python
class SecurityHeadersMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request: Request, call_next):
        response = await call_next(request)
        response.headers.update({
            "X-Content-Type-Options": "nosniff",
            "Strict-Transport-Security": "max-age=31536000",
            "X-Frame-Options": "DENY",
            "Content-Security-Policy": "default-src 'self'",
            "X-XSS-Protection": "1; mode=block",
            "Referrer-Policy": "strict-origin-when-cross-origin"
        })
        return response
```

### Secret Management

Secure handling of sensitive configuration:

- Encrypted secret storage
- Automatic key rotation
- Secure memory wiping
- Hardware security module (HSM) support
- Environment variable protection

### CORS Protection

Configurable CORS policy:

```python
app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://trusted-domain.com"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)
```

### Security Best Practices

Additional security measures:

1. **Input Validation**
   - Strict type checking
   - Schema validation
   - Content length limits
   - Character encoding validation

2. **Output Encoding**
   - HTML escaping
   - JSON encoding
   - CSV injection prevention
   - File name sanitization

3. **Error Handling**
   - Generic error messages
   - No stack traces in production
   - Structured error logging
   - Security event auditing

4. **Secure Development**
   - Regular dependency updates
   - Security scanning integration
   - Code review requirements
   - Security testing automation

## Testing

Run the test suite:

```bash
pytest
```

Run specific tests:

```bash
pytest tests/test_auth.py -v
pytest tests/test_users.py -v
```

Run the API test script:

```bash
./api-test.sh
```

## Development

1. Clone the repository:

```bash
git clone https://github.com/yourusername/authly.git
cd authly
```

2. Install development dependencies:

```bash
poetry install
```

3. Run linting:

```bash
poetry run flake8
poetry run black .
poetry run isort .
```

## Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Support

For support, please open an issue in the GitHub repository or contact the maintainers.

## Acknowledgments

- FastAPI
- PostgreSQL
- Python-Jose
- Bcrypt
- Psycopg
            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "authly",
    "maintainer": null,
    "docs_url": null,
    "requires_python": "<4.0,>=3.11",
    "maintainer_email": null,
    "keywords": null,
    "author": "Ove Ranheim",
    "author_email": "oranheim@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/e6/da/4d73e7fc7e75a4527ea57605b809ac8b7114469083f0b8fce194ff540ba2/authly-0.1.4.tar.gz",
    "platform": null,
    "description": "# Authly\n\nAuthly is a robust Python framework for Authentication and User Token Handling built on FastAPI. It provides secure, scalable, and easy-to-integrate authentication services with features like JWT token management, user sessions, and secure password handling.\n\n## Features\n\n- **Secure Authentication**\n  - JWT-based authentication with access and refresh tokens\n  - Password hashing with bcrypt\n  - Rate limiting and brute force protection\n  - Secure token storage and management\n\n- **User Management**\n  - User registration and verification\n  - Role-based access control (admin/user)\n  - User profile management\n  - Session management\n\n- **Token Management**\n  - Automatic token rotation\n  - Token invalidation and cleanup\n  - Refresh token handling\n  - Token blacklisting\n\n- **Security Features**\n  - Secure secret management\n  - CORS protection\n  - Security headers\n  - Rate limiting\n\n- **Database Integration**\n  - PostgreSQL support with psycopg\n  - Connection pooling\n  - Transaction management\n  - Vector support (pgvector)\n\n## Installation\n\n```bash\npip install authly\n```\n\nOr with Poetry:\n\n```bash\npoetry add authly\n```\n\n## Quick Start\n\n1. Create a new project and install dependencies:\n\n```bash\npoetry new myproject\ncd myproject\npoetry add authly\n```\n\n2. Set up your environment variables:\n\n```bash\n# .env\nJWT_SECRET_KEY=\"your-production-secret-here\"\nJWT_REFRESH_SECRET_KEY=\"your-refresh-secret-key-here\"\nJWT_ALGORITHM=\"HS256\"\nACCESS_TOKEN_EXPIRE_MINUTES=30\nREFRESH_TOKEN_EXPIRE_DAYS=7\n```\n\n3. Create your FastAPI application:\n\n```python\nfrom fastapi import FastAPI\nfrom authly import Authly, AuthlyConfig\nfrom authly.config import EnvSecretProvider\nfrom authly.api import auth_router, users_router\n\n# Initialize configuration\nsecret_provider = EnvSecretProvider()\nconfig = AuthlyConfig.load(secret_provider)\n\n# Create database pool\npool = AsyncConnectionPool(\n    \"postgresql://user:password@localhost:5432/db\"\n)\n\n# Initialize Authly\nauthly = Authly.initialize(pool, config)\n\n# Create FastAPI app\napp = FastAPI()\n\n# Include Authly routers\napp.include_router(auth_router, prefix=\"/api/v1\")\napp.include_router(users_router, prefix=\"/api/v1\")\n```\n\n## Sequence diagrams\n\n### System Architecture\n- [\ud83c\udfd7\ufe0f Component Architecture](https://github.com/descoped/authly/blob/master/docs/component-architecture.md)\n\n### Authentication Flows\n- [\ud83d\udd10 User Registration and Verification Flow](https://github.com/descoped/authly/blob/master/docs/user-registration-and-verification-flow.md)\n- [\ud83d\udd11 User Authentication Flow](https://github.com/descoped/authly/blob/master/docs/user-authentication-flow.md)\n- [\ud83d\udeaa Logout Flow](https://github.com/descoped/authly/blob/master/docs/logout-flow.md)\n\n### Token Management\n- [\ud83d\udd04 Token Refresh Flow](https://github.com/descoped/authly/blob/master/docs/token-refresh-flow.md)\n- [\ud83d\udcca State Diagram for Token Lifecycle](https://github.com/descoped/authly/blob/master/docs/state-diagram-for-token-lifecycle.md)\n- [\ud83d\udcca State Diagram for User Account](https://github.com/descoped/authly/blob/master/docs/state-diagram-for-user-account.md)\n\n\n## API Documentation\n\n### Authentication Endpoints\n\n#### POST /auth/token\nLogin and obtain access token.\n\n**Request Body:**\n```json\n{\n    \"username\": \"string\",\n    \"password\": \"string\",\n    \"grant_type\": \"password\"\n}\n```\n\n**Response:**\n```json\n{\n    \"access_token\": \"string\",\n    \"refresh_token\": \"string\",\n    \"token_type\": \"Bearer\",\n    \"expires_in\": 1800\n}\n```\n\n**Status Codes:**\n- 200: Successful login\n- 400: Invalid request body\n- 401: Invalid credentials\n- 403: Account not verified/inactive\n- 429: Too many requests\n\n#### POST /auth/refresh\nRefresh access token using refresh token.\n\n**Request Body:**\n```json\n{\n    \"refresh_token\": \"string\",\n    \"grant_type\": \"refresh_token\"\n}\n```\n\n**Response:**\n```json\n{\n    \"access_token\": \"string\",\n    \"refresh_token\": \"string\",\n    \"token_type\": \"Bearer\",\n    \"expires_in\": 1800\n}\n```\n\n**Status Codes:**\n- 200: Token refreshed successfully\n- 400: Invalid refresh token\n- 401: Invalid or expired refresh token\n\n#### POST /auth/logout\nLogout and invalidate all active tokens.\n\n**Headers:**\n- Authorization: Bearer {access_token}\n\n**Response:**\n```json\n{\n    \"message\": \"Successfully logged out\",\n    \"invalidated_tokens\": 2\n}\n```\n\n**Status Codes:**\n- 200: Successful logout\n- 401: Invalid token\n- 500: Server error\n\n### User Management Endpoints\n\n#### POST /users/\nCreate a new user account.\n\n**Request Body:**\n```json\n{\n    \"username\": \"string\",\n    \"email\": \"string\",\n    \"password\": \"string\"\n}\n```\n\n**Response:**\n```json\n{\n    \"id\": \"uuid\",\n    \"username\": \"string\",\n    \"email\": \"string\",\n    \"created_at\": \"datetime\",\n    \"updated_at\": \"datetime\",\n    \"last_login\": \"datetime\",\n    \"is_active\": true,\n    \"is_verified\": false,\n    \"is_admin\": false\n}\n```\n\n**Status Codes:**\n- 201: User created successfully\n- 400: Invalid request body or duplicate username/email\n- 500: Server error\n\n#### GET /users/me\nGet current user information.\n\n**Headers:**\n- Authorization: Bearer {access_token}\n\n**Response:**\n```json\n{\n    \"id\": \"uuid\",\n    \"username\": \"string\",\n    \"email\": \"string\",\n    \"created_at\": \"datetime\",\n    \"updated_at\": \"datetime\",\n    \"last_login\": \"datetime\",\n    \"is_active\": true,\n    \"is_verified\": true,\n    \"is_admin\": false\n}\n```\n\n**Status Codes:**\n- 200: Success\n- 401: Not authenticated\n- 403: Forbidden\n\n#### GET /users/{user_id}\nGet user information by ID.\n\n**Headers:**\n- Authorization: Bearer {access_token}\n\n**Parameters:**\n- user_id: UUID of the user\n\n**Response:**\n```json\n{\n    \"id\": \"uuid\",\n    \"username\": \"string\",\n    \"email\": \"string\",\n    \"created_at\": \"datetime\",\n    \"updated_at\": \"datetime\",\n    \"last_login\": \"datetime\",\n    \"is_active\": true,\n    \"is_verified\": true,\n    \"is_admin\": false\n}\n```\n\n**Status Codes:**\n- 200: Success\n- 404: User not found\n- 401: Not authenticated\n\n#### PUT /users/{user_id}\nUpdate user information.\n\n**Headers:**\n- Authorization: Bearer {access_token}\n\n**Parameters:**\n- user_id: UUID of the user\n\n**Request Body:**\n```json\n{\n    \"username\": \"string\",\n    \"email\": \"string\",\n    \"password\": \"string\",\n    \"is_active\": true,\n    \"is_verified\": true,\n    \"is_admin\": false\n}\n```\n\n**Response:**\n```json\n{\n    \"id\": \"uuid\",\n    \"username\": \"string\",\n    \"email\": \"string\",\n    \"created_at\": \"datetime\",\n    \"updated_at\": \"datetime\",\n    \"last_login\": \"datetime\",\n    \"is_active\": true,\n    \"is_verified\": true,\n    \"is_admin\": false\n}\n```\n\n**Status Codes:**\n- 200: Success\n- 400: Invalid request body\n- 401: Not authenticated\n- 403: Forbidden\n- 404: User not found\n\n#### DELETE /users/{user_id}\nDelete a user account.\n\n**Headers:**\n- Authorization: Bearer {access_token}\n\n**Parameters:**\n- user_id: UUID of the user\n\n**Status Codes:**\n- 204: Successfully deleted\n- 401: Not authenticated\n- 403: Forbidden\n- 404: User not found\n\n#### PUT /users/{user_id}/verify\nVerify a user account.\n\n**Headers:**\n- Authorization: Bearer {access_token}\n\n**Parameters:**\n- user_id: UUID of the user\n\n**Response:**\n```json\n{\n    \"id\": \"uuid\",\n    \"username\": \"string\",\n    \"email\": \"string\",\n    \"created_at\": \"datetime\",\n    \"updated_at\": \"datetime\",\n    \"last_login\": \"datetime\",\n    \"is_active\": true,\n    \"is_verified\": true,\n    \"is_admin\": false\n}\n```\n\n**Status Codes:**\n- 200: Successfully verified\n- 401: Not authenticated\n- 403: Forbidden\n- 404: User not found\n\n## Configuration\n\nAuthly can be configured through environment variables or configuration providers:\n\n```python\nfrom authly.config import FileSecretProvider, StaticSecretProvider\n\n# Using environment variables\nprovider = EnvSecretProvider()\n\n# Using file-based secrets\nprovider = FileSecretProvider(Path(\"secrets.json\"))\n\n# Using static secrets (for testing)\nprovider = StaticSecretProvider(\n    secret_key=\"test-secret-key\",\n    refresh_secret_key=\"test-refresh-key\"\n)\n```\n\n## Database Setup\n\n1. Create the required database and user:\n\n```sql\nCREATE USER authly WITH PASSWORD 'your_password';\nCREATE DATABASE authly_db;\nGRANT ALL PRIVILEGES ON DATABASE authly_db TO authly;\n```\n\n2. Run the initialization scripts:\n\n```sql\n-- Enable required extensions\nCREATE EXTENSION IF NOT EXISTS vector;\nCREATE EXTENSION IF NOT EXISTS \"uuid-ossp\";\n\n-- Create tables\nCREATE TABLE users (\n    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n    username VARCHAR(50) UNIQUE NOT NULL,\n    email VARCHAR(255) UNIQUE NOT NULL,\n    password_hash VARCHAR(255) NOT NULL,\n    -- Additional fields...\n);\n\nCREATE TABLE tokens (\n    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,\n    token_jti VARCHAR(64) NOT NULL UNIQUE,\n    -- Additional fields...\n);\n```\n\n## Security Features\n\n### Password Hashing and Storage\n\nAuthly uses bcrypt for secure password hashing with the following security measures:\n\n- Automatic salt generation for each password\n- Configurable work factor for future-proofing against hardware improvements\n- Memory-hard hashing algorithm resistant to GPU/ASIC attacks\n\nExample implementation:\n\n```python\nfrom authly.auth import get_password_hash, verify_password\n\n# Hash password with bcrypt\nhashed = get_password_hash(\"user_password\")\n\n# Verify password - timing-safe comparison\nis_valid = verify_password(\"user_password\", hashed)\n```\n\n### Password Hashing with bcrypt in Terminal\n\nThis guide shows how to generate bcrypt password hashes using Terminal commands, similar to what authentication libraries do under the hood.\n\n#### Quick Start\n\n```bash\nhtpasswd -nbB username password\n```\n\nThis generates a bcrypt hash in the format: `username:$2y$05$...`\n\n#### Installation\n\nIf htpasswd is not available:\n\n```bash\nbrew install apache2\n```\n\n### Advanced Usage\n\n#### Match Python's Default Cost Factor (12)\n\n```bash\nhtpasswd -nbBC 12 username password\n```\n\n#### Python Equivalent\n\nFor reference, this is equivalent to:\n\n```python\nimport bcrypt\nbcrypt.hashpw(password.encode('utf-8'), bcrypt.gensalt(rounds=12))\n```\n\n### Hash Format\n\nThe output hash follows this structure:\n- `$2y$` - bcrypt algorithm identifier\n- `XX$` - cost factor (05 for htpasswd default, 12 for Python default)\n- Rest of string - salt and hash combined\n\n#### Notes\n- Default cost factor in htpasswd is 5\n- Default cost factor in Python's bcrypt is 12\n- Both use the same underlying Blowfish-based bcrypt algorithm\n- Higher cost factors are more secure but slower to compute\n\n\n### Token Security\n\nAuthly implements a comprehensive token security system:\n\n#### JWT Token Management\n- Short-lived access tokens (configurable, default 30 minutes)\n- Separate refresh tokens with longer lifetime\n- JTI (JWT ID) claim for token revocation\n- Token payload encryption for sensitive data\n- Automatic token rotation on refresh\n\n#### Token Storage and Validation\n```python\n# Token creation with JTI\naccess_token = create_access_token(\n    data={\"sub\": user_id, \"jti\": token_jti},\n    secret_key=config.secret_key,\n    algorithm=\"HS256\",\n    expires_delta=30  # minutes\n)\n\n# Token validation\ntry:\n    payload = decode_token(token, secret_key, algorithm=\"HS256\")\n    is_valid = await token_service.is_token_valid(payload[\"jti\"])\nexcept JWTError:\n    raise InvalidToken()\n```\n\n#### Token Cleanup and Management\n- Automatic cleanup of expired tokens\n- Token blacklisting for immediate revocation\n- Database-backed token storage for persistence\n- Transaction-safe token operations\n\n### Rate Limiting and Brute Force Protection\n\nComprehensive protection against automated attacks:\n\n#### Rate Limiting Implementation\n```python\nfrom authly.api.rate_limiter import RateLimiter\n\n# Configure rate limits\nlimiter = RateLimiter(\n    max_requests=5,     # Maximum requests\n    window_seconds=60   # Time window\n)\n\n# Usage in endpoint\nasync def login_endpoint():\n    await limiter.check_rate_limit(f\"login:{username}\")\n```\n\n#### Login Security\n- Progressive delays on failed attempts\n- Account lockout after multiple failures\n- IP-based rate limiting\n- User agent tracking\n- Geographic location monitoring (optional)\n\n### Secure Session Management\n\nRobust session handling features:\n\n- Secure session creation and validation\n- Session timeout management\n- Concurrent session control\n- Forced logout capabilities\n- Session activity tracking\n\n### Database Security\n\nSecure database operations:\n\n- Prepared statements for SQL injection prevention\n- Connection pooling with SSL/TLS\n- Transaction isolation\n- Automatic connection encryption\n- Least privilege database users\n\n### API Security Headers\n\nComprehensive security headers implementation:\n\n```python\nclass SecurityHeadersMiddleware(BaseHTTPMiddleware):\n    async def dispatch(self, request: Request, call_next):\n        response = await call_next(request)\n        response.headers.update({\n            \"X-Content-Type-Options\": \"nosniff\",\n            \"Strict-Transport-Security\": \"max-age=31536000\",\n            \"X-Frame-Options\": \"DENY\",\n            \"Content-Security-Policy\": \"default-src 'self'\",\n            \"X-XSS-Protection\": \"1; mode=block\",\n            \"Referrer-Policy\": \"strict-origin-when-cross-origin\"\n        })\n        return response\n```\n\n### Secret Management\n\nSecure handling of sensitive configuration:\n\n- Encrypted secret storage\n- Automatic key rotation\n- Secure memory wiping\n- Hardware security module (HSM) support\n- Environment variable protection\n\n### CORS Protection\n\nConfigurable CORS policy:\n\n```python\napp.add_middleware(\n    CORSMiddleware,\n    allow_origins=[\"https://trusted-domain.com\"],\n    allow_credentials=True,\n    allow_methods=[\"*\"],\n    allow_headers=[\"*\"],\n)\n```\n\n### Security Best Practices\n\nAdditional security measures:\n\n1. **Input Validation**\n   - Strict type checking\n   - Schema validation\n   - Content length limits\n   - Character encoding validation\n\n2. **Output Encoding**\n   - HTML escaping\n   - JSON encoding\n   - CSV injection prevention\n   - File name sanitization\n\n3. **Error Handling**\n   - Generic error messages\n   - No stack traces in production\n   - Structured error logging\n   - Security event auditing\n\n4. **Secure Development**\n   - Regular dependency updates\n   - Security scanning integration\n   - Code review requirements\n   - Security testing automation\n\n## Testing\n\nRun the test suite:\n\n```bash\npytest\n```\n\nRun specific tests:\n\n```bash\npytest tests/test_auth.py -v\npytest tests/test_users.py -v\n```\n\nRun the API test script:\n\n```bash\n./api-test.sh\n```\n\n## Development\n\n1. Clone the repository:\n\n```bash\ngit clone https://github.com/yourusername/authly.git\ncd authly\n```\n\n2. Install development dependencies:\n\n```bash\npoetry install\n```\n\n3. Run linting:\n\n```bash\npoetry run flake8\npoetry run black .\npoetry run isort .\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create your feature branch\n3. Commit your changes\n4. Push to the branch\n5. Create a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Support\n\nFor support, please open an issue in the GitHub repository or contact the maintainers.\n\n## Acknowledgments\n\n- FastAPI\n- PostgreSQL\n- Python-Jose\n- Bcrypt\n- Psycopg",
    "bugtrack_url": null,
    "license": null,
    "summary": "Authentication and Authorization for Python FastAPI",
    "version": "0.1.4",
    "project_urls": null,
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "dfe6dab417c85d6b1dd4e7fa6443279c07ace656a98afafc759c08fcbf023ae7",
                "md5": "17f8d848a56dbbd8e9be2edbc67e9662",
                "sha256": "847e60c097e8d67fa11825e83a3b378296fdeaa0996589148fad22bd810f5cd8"
            },
            "downloads": -1,
            "filename": "authly-0.1.4-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "17f8d848a56dbbd8e9be2edbc67e9662",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "<4.0,>=3.11",
            "size": 33316,
            "upload_time": "2025-02-15T17:06:07",
            "upload_time_iso_8601": "2025-02-15T17:06:07.819838Z",
            "url": "https://files.pythonhosted.org/packages/df/e6/dab417c85d6b1dd4e7fa6443279c07ace656a98afafc759c08fcbf023ae7/authly-0.1.4-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "e6da4d73e7fc7e75a4527ea57605b809ac8b7114469083f0b8fce194ff540ba2",
                "md5": "d111b10683ddbb2bc819080bf44011d0",
                "sha256": "e0bc96942edc7f2efeff9e43daed3cd5d3a9e993ef3f3cdefb6670990f8a96ab"
            },
            "downloads": -1,
            "filename": "authly-0.1.4.tar.gz",
            "has_sig": false,
            "md5_digest": "d111b10683ddbb2bc819080bf44011d0",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "<4.0,>=3.11",
            "size": 28021,
            "upload_time": "2025-02-15T17:06:09",
            "upload_time_iso_8601": "2025-02-15T17:06:09.842163Z",
            "url": "https://files.pythonhosted.org/packages/e6/da/4d73e7fc7e75a4527ea57605b809ac8b7114469083f0b8fce194ff540ba2/authly-0.1.4.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-02-15 17:06:09",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "lcname": "authly"
}