auth-gate 0.1.0__tar.gz

auth_gate-0.1.0/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2018 The Python Packaging Authority
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

auth_gate-0.1.0/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: auth-gate
+Version: 0.1.0
+Summary: Enterprise-grade authentication for microservices with Kong and Keycloak integration
+Home-page: https://github.com/tradelink-org/auth-gate
+Author: Brian Mburu
+Author-email: Brian Mburu <brian.mburu@students.jkuat.ac.ke>
+Maintainer-email: Brian Mburu <brian.mburu@students.jkuat.ac.ke>
+License: MIT
+Project-URL: Homepage, https://github.com/tradelink-org/auth-gate
+Project-URL: Repository, https://github.com/tradelink-org/auth-gate.git
+Project-URL: Documentation, https://github.com/tradelink-org/auth-gate.git
+Project-URL: Bug Tracker, https://github.com/tradelink-org/auth-gate/issues
+Keywords: authentication,keycloak,kong,fastapi,microservices
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Framework :: FastAPI
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.109.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: pydantic-settings>=2.1.0
+Requires-Dist: httpx>=0.26.0
+Requires-Dist: python-jose[cryptography]>=3.3.0
+Requires-Dist: starlette>=0.35.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.7.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# Auth Gate
+
+Enterprise-grade authentication for microservices with Kong and Keycloak integration.
+
+## Features
+
+-   **Dual-mode authentication**: Support for both Kong header-based auth (production) and direct Keycloak validation (development)
+-   **Service-to-service authentication**: Built-in client credentials flow for secure inter-service communication
+-   **Circuit breaker pattern**: Resilient handling of Keycloak failures with automatic recovery
+-   **FastAPI integration**: Ready-to-use dependencies for protecting endpoints
+-   **Role-based access control**: Fine-grained permission management with role and scope validation
+-   **Middleware support**: Automatic request authentication with configurable exclusions
+
+## Installation
+
+```bash
+pip install auth-gate
+
+```
+
+### For Development
+
+```bash
+pip install auth-gate[dev]
+
+```
+
+## Quick Start
+
+### Basic Usage
+
+```py
+from fastapi import FastAPI, Depends
+from auth_gate import (
+    AuthMiddleware,
+    get_current_user,
+    require_admin,
+    UserContext,
+    AuthSettings
+)
+
+# Initialize FastAPI app
+app = FastAPI()
+
+# Add authentication middleware
+app.add_middleware(
+    AuthMiddleware,
+    excluded_paths={"/health", "/metrics"},
+    excluded_prefixes={"/docs", "/openapi.json"}
+)
+
+# Protected endpoint - requires authentication
+@app.get("/api/profile")
+async def get_profile(user: UserContext = Depends(get_current_user)):
+    return {
+        "user_id": user.user_id,
+        "username": user.username,
+        "roles": user.roles
+    }
+
+# Admin-only endpoint
+@app.get("/api/admin/users")
+async def list_users(admin: UserContext = Depends(require_admin)):
+    return {"message": "Admin access granted"}
+
+# Role-based access
+from auth_gate import require_roles
+
+require_supplier_or_admin = require_roles("supplier", "admin")
+
+@app.get("/api/products")
+async def list_products(user: UserContext = Depends(require_supplier_or_admin)):
+    return {"products": []}
+```
+
+### Service-to-service Auth
+
+```py
+from auth_gate import ServiceAuthClient
+import httpx
+
+# Get service auth client
+auth_client = ServiceAuthClient()
+
+# Make authenticated service call
+async def call_other_service():
+    # Get service token (automatically cached and refreshed)
+    auth_header = await auth_client.get_service_token()
+
+    async with httpx.AsyncClient() as client:
+        response = await client.get(
+            "http://other-service/api/data",
+            headers={"Authorization": auth_header}
+        )
+        return response.json()
+```
+
+## Configuration
+
+Configure via envirinment variables:
+
+```bash
+# Authentication mode
+AUTH_MODE=kong_headers  # or "direct_keycloak", "bypass" (testing only)
+
+# Keycloak settings
+KEYCLOAK_REALM_URL=https://keycloak.example.com/realms/tradelink
+KEYCLOAK_CLIENT_ID=my-service
+KEYCLOAK_CLIENT_SECRET=secret
+
+# Service account (for S2S auth)
+SERVICE_CLIENT_ID=my-service-account
+SERVICE_CLIENT_SECRET=secret
+
+# Optional settings
+VERIFY_HMAC=false
+INTERNAL_HMAC_KEY=your-hmac-key
+```
+
+## Advanced Features
+
+### Custom Excluded Paths
+
+```py
+app.add_middleware(
+    AuthMiddleware,
+    excluded_paths={"/health", "/metrics", "/public"},
+    excluded_prefixes={"/static", "/docs"},
+    optional_auth_paths={"/api/products"}  # Auth optional for these paths
+)
+```
+
+### Direct Validator Usage
+
+```py
+from auth_gate import UserValidator, AuthMode
+
+validator = UserValidator(mode=AuthMode.DIRECT_KEYCLOAK)
+user_context = await validator.validate_keycloak_token(token)
+```
+
+### Circuit Breaker Configuration
+
+The S2S auth client includes automatic circuit breaker protection:
+
+-   Opens after 5 consecutive failures
+-   Attempts recovery after 60 seconds
+-   Provides fail-fast behavior when Keycloak is unavailable
+
+## Development
+
+### Running Tests
+
+```bash
+pytest tests/ --cov=auth_gate
+```
+
+### Code quality
+
+```bash
+black src/
+ruff check src/
+mypy src/
+```
+
+## License
+
+For use within tradelink suite of services - See LICENSE file for details.
+
+## Support
+
+For issues and questions, please use the [GitHub issue tracker](https://github.com/tradelink-org/auth-gate/issues).

auth_gate-0.1.0/README.md

@@ -0,0 +1,172 @@
+# Auth Gate
+
+Enterprise-grade authentication for microservices with Kong and Keycloak integration.
+
+## Features
+
+-   **Dual-mode authentication**: Support for both Kong header-based auth (production) and direct Keycloak validation (development)
+-   **Service-to-service authentication**: Built-in client credentials flow for secure inter-service communication
+-   **Circuit breaker pattern**: Resilient handling of Keycloak failures with automatic recovery
+-   **FastAPI integration**: Ready-to-use dependencies for protecting endpoints
+-   **Role-based access control**: Fine-grained permission management with role and scope validation
+-   **Middleware support**: Automatic request authentication with configurable exclusions
+
+## Installation
+
+```bash
+pip install auth-gate
+
+```
+
+### For Development
+
+```bash
+pip install auth-gate[dev]
+
+```
+
+## Quick Start
+
+### Basic Usage
+
+```py
+from fastapi import FastAPI, Depends
+from auth_gate import (
+    AuthMiddleware,
+    get_current_user,
+    require_admin,
+    UserContext,
+    AuthSettings
+)
+
+# Initialize FastAPI app
+app = FastAPI()
+
+# Add authentication middleware
+app.add_middleware(
+    AuthMiddleware,
+    excluded_paths={"/health", "/metrics"},
+    excluded_prefixes={"/docs", "/openapi.json"}
+)
+
+# Protected endpoint - requires authentication
+@app.get("/api/profile")
+async def get_profile(user: UserContext = Depends(get_current_user)):
+    return {
+        "user_id": user.user_id,
+        "username": user.username,
+        "roles": user.roles
+    }
+
+# Admin-only endpoint
+@app.get("/api/admin/users")
+async def list_users(admin: UserContext = Depends(require_admin)):
+    return {"message": "Admin access granted"}
+
+# Role-based access
+from auth_gate import require_roles
+
+require_supplier_or_admin = require_roles("supplier", "admin")
+
+@app.get("/api/products")
+async def list_products(user: UserContext = Depends(require_supplier_or_admin)):
+    return {"products": []}
+```
+
+### Service-to-service Auth
+
+```py
+from auth_gate import ServiceAuthClient
+import httpx
+
+# Get service auth client
+auth_client = ServiceAuthClient()
+
+# Make authenticated service call
+async def call_other_service():
+    # Get service token (automatically cached and refreshed)
+    auth_header = await auth_client.get_service_token()
+
+    async with httpx.AsyncClient() as client:
+        response = await client.get(
+            "http://other-service/api/data",
+            headers={"Authorization": auth_header}
+        )
+        return response.json()
+```
+
+## Configuration
+
+Configure via envirinment variables:
+
+```bash
+# Authentication mode
+AUTH_MODE=kong_headers  # or "direct_keycloak", "bypass" (testing only)
+
+# Keycloak settings
+KEYCLOAK_REALM_URL=https://keycloak.example.com/realms/tradelink
+KEYCLOAK_CLIENT_ID=my-service
+KEYCLOAK_CLIENT_SECRET=secret
+
+# Service account (for S2S auth)
+SERVICE_CLIENT_ID=my-service-account
+SERVICE_CLIENT_SECRET=secret
+
+# Optional settings
+VERIFY_HMAC=false
+INTERNAL_HMAC_KEY=your-hmac-key
+```
+
+## Advanced Features
+
+### Custom Excluded Paths
+
+```py
+app.add_middleware(
+    AuthMiddleware,
+    excluded_paths={"/health", "/metrics", "/public"},
+    excluded_prefixes={"/static", "/docs"},
+    optional_auth_paths={"/api/products"}  # Auth optional for these paths
+)
+```
+
+### Direct Validator Usage
+
+```py
+from auth_gate import UserValidator, AuthMode
+
+validator = UserValidator(mode=AuthMode.DIRECT_KEYCLOAK)
+user_context = await validator.validate_keycloak_token(token)
+```
+
+### Circuit Breaker Configuration
+
+The S2S auth client includes automatic circuit breaker protection:
+
+-   Opens after 5 consecutive failures
+-   Attempts recovery after 60 seconds
+-   Provides fail-fast behavior when Keycloak is unavailable
+
+## Development
+
+### Running Tests
+
+```bash
+pytest tests/ --cov=auth_gate
+```
+
+### Code quality
+
+```bash
+black src/
+ruff check src/
+mypy src/
+```
+
+## License
+
+For use within tradelink suite of services - See LICENSE file for details.
+
+## Support
+
+For issues and questions, please use the [GitHub issue tracker](https://github.com/tradelink-org/auth-gate/issues).

auth_gate-0.1.0/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "auth-gate"
+version = "0.1.0"
+description = "Enterprise-grade authentication for microservices with Kong and Keycloak integration"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [
+    {name = "Brian Mburu", email = "brian.mburu@students.jkuat.ac.ke"}
+]
+maintainers = [
+    {name = "Brian Mburu", email = "brian.mburu@students.jkuat.ac.ke"}
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+    "Framework :: FastAPI",
+]
+keywords = ["authentication", "keycloak", "kong", "fastapi", "microservices"]
+
+dependencies = [
+    "fastapi>=0.109.0",
+    "pydantic>=2.5.0",
+    "pydantic-settings>=2.1.0",
+    "httpx>=0.26.0",
+    "python-jose[cryptography]>=3.3.0",
+    "starlette>=0.35.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-cov>=4.1.0",
+    "black>=23.0.0",
+    "mypy>=1.7.0",
+    "ruff>=0.1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/tradelink-org/auth-gate"
+Repository = "https://github.com/tradelink-org/auth-gate.git"
+Documentation = "https://github.com/tradelink-org/auth-gate.git"
+"Bug Tracker" = "https://github.com/tradelink-org/auth-gate/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.black]
+line-length = 100
+target-version = ["py311"]
+
+[tool.ruff]
+line-length = 100
+select = ["E", "F", "I", "N", "W"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+ignore_missing_imports = true

auth_gate-0.1.0/setup.cfg

@@ -0,0 +1,49 @@
+[metadata]
+name = auth-gate
+version = 0.1.0
+author = Brian Mburu
+author_email = brian.mburu@students.jkuat.ac.ke
+description = Enterprise-grade authentication for microservices with Kong and Keycloak integration
+long_description = file: README.md
+long_description_content_type = text/markdown
+url = https://github.com/tradelink-org/auth-gate
+project_urls = 
+	Bug Tracker = https://github.com/tradelink-org/auth-gate/issues
+	Documentation = https://auth-client.tradelink.io
+classifiers = 
+	Programming Language :: Python :: 3
+	Programming Language :: Python :: 3.11
+	Programming Language :: Python :: 3.12
+	License :: OSI Approved :: MIT License
+	Operating System :: OS Independent
+	Framework :: FastAPI
+
+[options]
+package_dir = 
+	= src
+packages = find:
+python_requires = >=3.11
+install_requires = 
+	fastapi>=0.109.0
+	pydantic>=2.5.0
+	pydantic-settings>=2.1.0
+	httpx>=0.26.0
+	python-jose[cryptography]>=3.3.0
+	starlette>=0.35.0
+
+[options.packages.find]
+where = src
+
+[options.extras_require]
+dev = 
+	pytest>=7.4.0
+	pytest-asyncio>=0.21.0
+	pytest-cov>=4.1.0
+	black>=23.0.0
+	mypy>=1.7.0
+	ruff>=0.1.0
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

auth_gate-0.1.0/src/auth_gate/__init__.py

@@ -0,0 +1,52 @@
+"""
+Tradelink Authentication Client
+
+Enterprise authentication client for microservices with Kong/Keycloak integration.
+"""
+
+from .config import AuthMode, AuthSettings
+from .fastapi_utils import (
+    get_current_user,
+    get_optional_user,
+    require_admin,
+    require_customer,
+    require_moderator,
+    require_roles,
+    require_scopes,
+    require_supplier,
+    require_supplier_or_admin,
+    verify_hmac_signature,
+)
+from .middleware import AuthMiddleware
+from .s2s_auth import CircuitBreaker, CircuitBreakerOpenError, ServiceAuthClient
+from .schemas import UserContext
+from .user_auth import UserValidator
+
+__version__ = "1.0.0"
+
+__all__ = [
+    # Configuration
+    "AuthSettings",
+    "AuthMode",
+    # Schemas
+    "UserContext",
+    # User Authentication
+    "UserValidator",
+    # Service-to-Service
+    "ServiceAuthClient",
+    "CircuitBreaker",
+    "CircuitBreakerOpenError",
+    # Middleware
+    "AuthMiddleware",
+    # FastAPI Dependencies
+    "get_current_user",
+    "get_optional_user",
+    "require_roles",
+    "require_scopes",
+    "require_admin",
+    "require_supplier",
+    "require_customer",
+    "require_moderator",
+    "require_supplier_or_admin",
+    "verify_hmac_signature",
+]

auth_gate-0.1.0/src/auth_gate/config.py

@@ -0,0 +1,99 @@
+"""
+Configuration management for Tradelink Auth Client
+"""
+
+from enum import Enum
+from typing import Optional
+
+from pydantic_settings import BaseSettings
+
+
+class AuthMode(Enum):
+    """Authentication modes for different environments"""
+
+    KONG_HEADERS = "kong_headers"  # Production: Kong validates tokens
+    DIRECT_KEYCLOAK = "direct_keycloak"  # Development: Direct Keycloak validation
+    BYPASS = "bypass"  # Testing only - NEVER use in production
+
+
+class AuthSettings(BaseSettings):
+    """
+    Centralized configuration for authentication client.
+    All settings can be overridden via environment variables.
+    """
+
+    model_config = {
+        "env_file": (".env", ".env.test", ".env.prod"),
+        "extra": "ignore",
+        "env_file_encoding": "utf-8",
+        "case_sensitive": True,
+    }
+
+    # Authentication Mode
+    AUTH_MODE: str = "kong_headers"
+
+    # Keycloak Configuration
+    KEYCLOAK_REALM_URL: str = "http://localhost:8080/realms/master"
+    KEYCLOAK_CLIENT_ID: str = "backend-service"
+    KEYCLOAK_CLIENT_SECRET: str = ""
+
+    # Service Account Configuration (for S2S)
+    SERVICE_CLIENT_ID: str = "service-account"
+    SERVICE_CLIENT_SECRET: str = ""
+
+    # HMAC Verification (optional)
+    VERIFY_HMAC: bool = False
+    INTERNAL_HMAC_KEY: str = ""
+
+    # Circuit Breaker Settings
+    CIRCUIT_BREAKER_FAILURE_THRESHOLD: int = 5
+    CIRCUIT_BREAKER_RECOVERY_TIMEOUT: int = 60
+
+    # Token Settings
+    TOKEN_CACHE_TTL: int = 300  # seconds
+    TOKEN_REFRESH_BUFFER: int = 30  # seconds before expiry
+
+    # HTTP Client Settings
+    HTTP_TIMEOUT: float = 10.0
+    HTTP_MAX_KEEPALIVE_CONNECTIONS: int = 10
+
+    @property
+    def auth_mode_enum(self) -> AuthMode:
+        """Get AUTH_MODE as enum"""
+        try:
+            return AuthMode(self.AUTH_MODE.lower())
+        except ValueError:
+            raise ValueError(f"Invalid AUTH_MODE: {self.AUTH_MODE}")
+
+    @property
+    def is_production(self) -> bool:
+        """Check if running in production mode"""
+        return self.auth_mode_enum == AuthMode.KONG_HEADERS
+
+    @property
+    def is_development(self) -> bool:
+        """Check if running in development mode"""
+        return self.auth_mode_enum == AuthMode.DIRECT_KEYCLOAK
+
+    @property
+    def is_testing(self) -> bool:
+        """Check if running in testing/bypass mode"""
+        return self.auth_mode_enum == AuthMode.BYPASS
+
+
+# Global settings instance
+_settings: Optional[AuthSettings] = None
+
+
+def get_settings() -> AuthSettings:
+    """Get or create settings instance"""
+    global _settings
+    if _settings is None:
+        _settings = AuthSettings()
+    return _settings
+
+
+def reset_settings() -> None:
+    """Reset settings (useful for testing)"""
+    global _settings
+    _settings = None