{"id":25426777,"url":"https://github.com/igorbenav/fastsecure","last_synced_at":"2025-10-31T16:30:26.674Z","repository":{"id":277061217,"uuid":"927525679","full_name":"igorbenav/fastsecure","owner":"igorbenav","description":"A modern, flexible authentication system for FastAPI applications with support for multiple authentication methods and strategies.","archived":false,"fork":false,"pushed_at":"2025-02-11T22:29:34.000Z","size":166,"stargazers_count":4,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-11T23:31:53.166Z","etag":null,"topics":["auth","authentication","authorization","fastapi","jwt","session"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/igorbenav.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"igorbenav"}},"created_at":"2025-02-05T05:15:34.000Z","updated_at":"2025-02-11T22:29:38.000Z","dependencies_parsed_at":"2025-02-11T23:32:00.124Z","dependency_job_id":"5b8c830e-a9ab-4d36-b052-6f6ad4f0d0ba","html_url":"https://github.com/igorbenav/fastsecure","commit_stats":null,"previous_names":["igorbenav/fastsecure"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorbenav%2Ffastsecure","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorbenav%2Ffastsecure/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorbenav%2Ffastsecure/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorbenav%2Ffastsecure/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/igorbenav","download_url":"https://codeload.github.com/igorbenav/fastsecure/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239214043,"owners_count":19601075,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["auth","authentication","authorization","fastapi","jwt","session"],"created_at":"2025-02-17T00:21:55.466Z","updated_at":"2025-10-31T16:30:26.642Z","avatar_url":"https://github.com/igorbenav.png","language":"Python","funding_links":["https://github.com/sponsors/igorbenav"],"categories":[],"sub_categories":[],"readme":"# FastSecure\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://igorbenav.github.io/fastsecure/\"\u003e\n    \u003cimg src=\"docs/assets/FastSecure.png\" alt=\"FastSecure logo\" width=\"65%\" height=\"auto\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nA modern, flexible authentication system for FastAPI applications with support for multiple authentication methods and strategies.\n\n## Table of Contents\n\n- [Features](#features)\n- [Installation](#installation)\n- [Core Concepts](#core-concepts)\n- [Basic Usage Guide](#basic-usage-guide)\n  - [Setting Up JWT Authentication](#setting-up-jwt-authentication)\n  - [Setting Up Session Authentication](#setting-up-session-authentication)\n  - [Setting Up OAuth Authentication](#setting-up-oauth-authentication)\n- [Advanced Usage Guide](#advanced-usage-guide)\n  - [Combining Authentication Methods](#combining-authentication-methods)\n  - [Custom Authentication Providers](#custom-authentication-providers)\n  - [Storage Backends](#storage-backends)\n- [Security Best Practices](#security-best-practices)\n- [Troubleshooting](#troubleshooting)\n- [Contributing](#contributing)\n- [License](#license)\n\n\u003e [!WARNING]  \n\u003e FastSecure is still experimental.\n\n## Features\n\n- 🔐 **Multiple Authentication Methods**\n  - JWT tokens with refresh token support and flexible configuration\n  - Session-based authentication with configurable storage backends\n  - OAuth 2.0 providers (Google, GitHub) with standardized user info\n  - Easy to extend with custom authentication providers\n\n- 🔄 **Flexible Authentication Strategies**\n  - Use single or multiple authentication methods\n  - Support for AND logic (require all methods)\n  - Support for OR logic (allow any method)\n  - Optional authentication methods\n  - Path-based authentication requirements\n\n- 🗄️ **Session Storage Options**\n  - In-memory storage for development\n  - Redis backend for distributed systems\n  - Database backend (SQLAlchemy) for persistence\n  - Easy to implement custom storage backends\n\n- 🛡️ **Security Features**\n  - Token expiration and refresh\n  - Session timeout and cleanup\n  - Concurrent session limits\n  - Scope-based authorization\n  - IP tracking and user agent logging\n\n## Installation\n\n1. Install using pip:\n```bash\npip install fastsecure\n```\n\n2. Install using uv or poetry:\n```bash\nuv add fastsecure\n```\n\n```bash\npoetry add fastsecure\n```\n\n## Core Concepts\n\nBefore diving into the implementation, let's understand the core concepts:\n\n### Authentication Manager\n\nThe `AuthenticationManager` is the central component that:\n- Manages authentication providers\n- Handles authentication strategies\n- Enforces authentication requirements\n- Coordinates the authentication flow\n\n### Authentication Providers\n\nProviders implement specific authentication methods:\n- JWT tokens\n- Sessions\n- OAuth\n- Custom methods\n\n### Authentication Strategies\n\nStrategies determine how multiple authentication methods are combined:\n- `AuthStrategy.ANY`: Any provider can authenticate (OR logic)\n- `AuthStrategy.ALL`: All providers must authenticate (AND logic)\n\n### Authentication Requirements\n\nRequirements specify which authentication methods are needed for specific paths:\n- Required providers\n- Optional providers\n- Authentication strategy\n- Required scopes\n\n## Basic Usage Guide\n\n### Setting Up JWT Authentication\n\n1. **Create a Basic FastAPI Application**\n\n```python\nfrom fastapi import FastAPI, Depends, HTTPException\nfrom fastsecure import AuthenticationManager, JWTAuthenticationProvider\n\napp = FastAPI()\n```\n\n2. **Initialize Authentication Manager and JWT Provider**\n\n```python\n# Initialize authentication\nauth_manager = AuthenticationManager()\n\n# Configure JWT provider\njwt_auth = JWTAuthenticationProvider(\n    secret_key=\"your-secret-key\",  # Use a secure key in production!\n    access_token_expire_minutes=30,\n    refresh_token_expire_days=7\n)\n\n# Register the provider\nauth_manager.register_provider(\"jwt\", jwt_auth)\n```\n\n3. **Create Authentication Dependency**\n\n```python\nfrom fastapi import Request\nfrom typing import Optional\n\nasync def requires_auth(request: Request, path: Optional[str] = None) -\u003e dict:\n    \"\"\"\n    FastAPI dependency for authentication requirements.\n    \n    Args:\n        request: The FastAPI request object\n        path: Optional path override for authentication requirements\n    \n    Returns:\n        Authentication result if successful\n    \n    Raises:\n        HTTPException: If authentication fails\n    \"\"\"\n    # Get authentication data from request headers\n    auth_header = request.headers.get(\"Authorization\")\n    if not auth_header:\n        raise HTTPException(status_code=401, detail=\"No authentication provided\")\n    \n    # Parse Bearer token\n    try:\n        scheme, token = auth_header.split()\n        if scheme.lower() != \"bearer\":\n            raise HTTPException(status_code=401, detail=\"Invalid authentication scheme\")\n    except ValueError:\n        raise HTTPException(status_code=401, detail=\"Invalid authorization header\")\n    \n    # Authenticate using the manager\n    result = await auth_manager.authenticate(\n        path or request.url.path,\n        {\"jwt\": {\"access_token\": token}}\n    )\n    \n    if not result.success:\n        raise HTTPException(\n            status_code=401,\n            detail=\"Authentication failed\",\n            headers={\"WWW-Authenticate\": \"Bearer\"}\n        )\n    \n    return result\n\n```\n\n4. **Configure Protected Routes**\n\n```python\n# Add authentication requirement for protected paths\nauth_manager.add_requirement(\n    \"/api/protected/*\",  # Path pattern\n    providers=[\"jwt\"],   # Required providers\n    scopes=[\"read\"]      # Required scopes (optional)\n)\n```\n\n5. **Implement Login and Protected Routes**\n\n```python\nfrom pydantic import BaseModel\n\nclass LoginCredentials(BaseModel):\n    username: str\n    password: str\n\n@app.post(\"/api/auth/login\")\nasync def login(credentials: LoginCredentials):\n    # Validate credentials (implement your own validation)\n    user_id = validate_credentials(credentials)\n    \n    # Authenticate with JWT provider\n    result = await auth_manager.authenticate(\n        \"/api/protected/data\",\n        {\"jwt\": {\n            \"user_id\": user_id,\n            \"scopes\": [\"read\", \"write\"]\n        }}\n    )\n    \n    if not result.success:\n        raise HTTPException(401, \"Authentication failed\")\n    \n    return {\n        \"access_token\": result.access_token,\n        \"refresh_token\": result.refresh_token,\n        \"token_type\": \"Bearer\",\n        \"expires_at\": result.expires_at\n    }\n\n@app.get(\"/api/protected/data\")\nasync def protected_data(auth = Depends(requires_auth)):\n    return {\n        \"message\": \"Authenticated!\",\n        \"user_id\": auth.user_id,\n        \"scopes\": auth.metadata.get(\"scopes\", [])\n    }\n```\n\n### Setting Up Session Authentication\n\n1. **Choose a Storage Backend**\n\n```python\nfrom fastsecure import (\n    SessionAuthenticationProvider,\n    RedisSessionStore,\n    DatabaseSessionStore\n)\n\n# For development (in-memory)\nsession_auth = SessionAuthenticationProvider()\n\n# For production with Redis\nsession_auth = SessionAuthenticationProvider(\n    session_store=RedisSessionStore(\"redis://localhost\"),\n    session_timeout_minutes=60,\n    max_sessions_per_user=3,\n    cleanup_expired=True\n)\n```\n\n2. **Configure Session Authentication**\n\n```python\n# Register the provider\nauth_manager.register_provider(\"session\", session_auth)\n\n# Add requirements\nauth_manager.add_requirement(\n    \"/api/user/*\",\n    providers=[\"session\"]\n)\n```\n\n3. **Implement Session Login**\n\n```python\n@app.post(\"/api/auth/session/login\")\nasync def session_login(\n    credentials: LoginCredentials,\n    request: Request\n):\n    user_id = validate_credentials(credentials)\n    \n    result = await auth_manager.authenticate(\n        \"/api/user/profile\",\n        {\"session\": {\n            \"user_id\": user_id,\n            \"ip_address\": request.client.host,\n            \"user_agent\": request.headers.get(\"user-agent\"),\n            \"scopes\": [\"user:read\"]\n        }}\n    )\n    \n    if not result.success:\n        raise HTTPException(401, \"Authentication failed\")\n    \n    response = JSONResponse({\n        \"message\": \"Logged in successfully\",\n        \"user_id\": user_id\n    })\n    \n    # Set session cookie\n    response.set_cookie(\n        \"session_id\",\n        result.session_id,\n        httponly=True,\n        secure=True,\n        samesite=\"lax\",\n        expires=result.expires_at\n    )\n    \n    return response\n```\n\n### Setting Up OAuth Authentication\n\n1. **Configure OAuth Providers**\n\n```python\nfrom fastsecure import GoogleAuthProvider, GitHubAuthProvider\n\n# Google Sign-In\ngoogle_auth = GoogleAuthProvider(\n    client_id=\"your-client-id\",\n    client_secret=\"your-client-secret\",\n    redirect_uri=\"http://localhost:8000/auth/google/callback\"\n)\n\n# GitHub Sign-In\ngithub_auth = GitHubAuthProvider(\n    client_id=\"your-client-id\",\n    client_secret=\"your-client-secret\",\n    redirect_uri=\"http://localhost:8000/auth/github/callback\"\n)\n\n# Register providers\nauth_manager.register_provider(\"google\", google_auth)\nauth_manager.register_provider(\"github\", github_auth)\n```\n\n2. **Implement OAuth Flow**\n\n```python\n@app.get(\"/auth/google/login\")\nasync def google_login():\n    authorization_url = google_auth.get_authorization_url(\n        state=\"random-secure-state\"  # Implement secure state handling\n    )\n    return RedirectResponse(authorization_url)\n\n@app.get(\"/auth/google/callback\")\nasync def google_callback(code: str, state: str):\n    # Validate state\n    validate_oauth_state(state)\n    \n    result = await auth_manager.authenticate(\n        \"/api/user/profile\",\n        {\"google\": {\"code\": code}}\n    )\n    \n    if not result.success:\n        raise HTTPException(401, \"Authentication failed\")\n    \n    # Get user info from result\n    user_info = result.metadata[\"user_info\"]\n    \n    return {\n        \"message\": \"Logged in with Google\",\n        \"email\": user_info[\"email\"],\n        \"name\": user_info[\"name\"],\n        \"access_token\": result.access_token\n    }\n```\n\n## Advanced Usage Guide\n\n### Combining Authentication Methods\n\n1. **Require Multiple Methods (AND Strategy)**\n\n```python\n# Require both JWT and session authentication\nauth_manager.add_requirement(\n    \"/api/admin/*\",\n    providers=[\"jwt\", \"session\"],\n    strategy=AuthStrategy.ALL,\n    scopes=[\"admin\"]\n)\n\n# Example request handler\n@app.post(\"/api/admin/action\")\nasync def admin_action(auth = Depends(auth_manager.requires_auth)):\n    if \"admin\" not in auth.metadata.get(\"scopes\", []):\n        raise HTTPException(403, \"Insufficient permissions\")\n    return {\"message\": \"Admin action successful\"}\n```\n\n2. **Allow Alternative Methods (OR Strategy)**\n\n```python\n# Allow any authentication method\nauth_manager.add_requirement(\n    \"/api/user/*\",\n    providers=[\"jwt\", \"session\", \"google\"],\n    strategy=AuthStrategy.ANY\n)\n```\n\n3. **Optional Authentication**\n\n```python\n# Add optional authentication methods\nauth_manager.add_requirement(\n    \"/api/public/*\",\n    providers=[\"jwt\"],\n    optional_providers=[\"session\", \"google\"]\n)\n```\n\n### Custom Authentication Providers\n\n1. **Create a Custom Provider**\n\n```python\nfrom fastsecure import AuthenticationProvider, AuthenticationResult\nfrom typing import Dict, Any, Set\n\nclass APIKeyAuthProvider(AuthenticationProvider):\n    def __init__(self, api_keys: Dict[str, str]):\n        self.api_keys = api_keys\n    \n    def get_required_credentials(self) -\u003e Set[str]:\n        return {\"api_key\"}\n    \n    async def authenticate(\n        self,\n        credentials: Dict[str, Any]\n    ) -\u003e AuthenticationResult:\n        api_key = credentials.get(\"api_key\")\n        \n        if api_key not in self.api_keys:\n            return AuthenticationResult(\n                success=False,\n                provider=self.provider_name,\n                metadata={\"error\": \"Invalid API key\"}\n            )\n        \n        return AuthenticationResult(\n            success=True,\n            provider=self.provider_name,\n            user_id=self.api_keys[api_key],\n            metadata={\"api_key\": api_key}\n        )\n    \n    async def validate_authentication(\n        self,\n        auth_data: Dict[str, Any]\n    ) -\u003e bool:\n        return auth_data.get(\"api_key\") in self.api_keys\n```\n\n2. **Register and Use Custom Provider**\n\n```python\n# Initialize with API keys\napi_key_auth = APIKeyAuthProvider({\n    \"key1\": \"user1\",\n    \"key2\": \"user2\"\n})\n\n# Register provider\nauth_manager.register_provider(\"apikey\", api_key_auth)\n\n# Add requirement\nauth_manager.add_requirement(\n    \"/api/service/*\",\n    providers=[\"apikey\"]\n)\n```\n\n### Storage Backends\n\n1. **Implement Custom Session Storage**\n\n```python\nfrom fastsecure import SessionStore\nfrom typing import Dict, Any, List, Optional\nfrom datetime import datetime\n\nclass CustomSessionStore(SessionStore):\n    async def create_session(\n        self,\n        user_id: int,\n        session_id: str,\n        expires_at: datetime,\n        metadata: Dict[str, Any]\n    ) -\u003e bool:\n        # Implement session creation\n        pass\n    \n    async def get_session(\n        self,\n        session_id: str\n    ) -\u003e Optional[Dict[str, Any]]:\n        # Implement session retrieval\n        pass\n    \n    async def update_session(\n        self,\n        session_id: str,\n        metadata: Dict[str, Any]\n    ) -\u003e bool:\n        # Implement session update\n        pass\n    \n    async def delete_session(\n        self,\n        session_id: str\n    ) -\u003e bool:\n        # Implement session deletion\n        pass\n    \n    async def get_user_sessions(\n        self,\n        user_id: int\n    ) -\u003e List[Dict[str, Any]]:\n        # Implement user sessions retrieval\n        pass\n```\n\n## Security Best Practices\n\n1. **JWT Security**\n   - Use strong secret keys\n   - Set appropriate token expiration times\n   - Implement token refresh securely\n   - Use HTTPS for token transmission\n\n2. **Session Security**\n   - Enable secure cookie attributes\n   - Implement session timeout\n   - Limit concurrent sessions\n   - Clean up expired sessions\n\n3. **OAuth Security**\n   - Validate OAuth state parameter\n   - Use HTTPS for callbacks\n   - Validate token scopes\n   - Handle user data securely\n\n4. **General Security**\n   - Implement rate limiting\n   - Use secure password handling\n   - Log security events\n   - Regular security audits\n\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Contact\n\nIgor Benav – [@igorbenav](https://x.com/igorbenav) – igormagalhaesr@gmail.com\n[github.com/igorbenav](https://github.com/igorbenav/)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Figorbenav%2Ffastsecure","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Figorbenav%2Ffastsecure","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Figorbenav%2Ffastsecure/lists"}