lks-idprovider-fastapi 0.1.0__tar.gz

lks_idprovider_fastapi-0.1.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.3
+Name: lks-idprovider-fastapi
+Version: 0.1.0
+Summary: Provider-agnostic FastAPI integration for lks-idprovider API protocols.
+License: LKSISL
+Author: Raul Medeiros
+Author-email: rmedeiros@lksnext.com
+Requires-Python: >=3.11
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: fastapi (>=0.116.1)
+Requires-Dist: lks-idprovider-api (>=0.1.6,<0.2.0)
+Description-Content-Type: text/markdown
+
+# lks-idprovider-fastapi
+
+Provider-agnostic FastAPI integration for lks-idprovider API protocols.
+
+This package provides reusable FastAPI dependencies, decorators, and middleware for REST API security, based on the lks-idprovider API protocols. It is not tied to any specific provider implementation (e.g., Keycloak) and can be used with any compatible backend.
+
+## Features
+- Bearer token security scheme for OpenAPI
+- AuthContext dependency for user/client authentication
+- Role-based and route protection dependencies
+- Easy integration with any provider implementing the API protocols
+
+## Usage
+1. Install this package and your chosen provider implementation.
+2. Configure your provider (e.g., Keycloak) in your FastAPI app.
+3. Inject the provider into the dependencies from this package.
+
+## License
+LKSISL
+

lks_idprovider_fastapi-0.1.0/README.md

@@ -0,0 +1,19 @@
+# lks-idprovider-fastapi
+
+Provider-agnostic FastAPI integration for lks-idprovider API protocols.
+
+This package provides reusable FastAPI dependencies, decorators, and middleware for REST API security, based on the lks-idprovider API protocols. It is not tied to any specific provider implementation (e.g., Keycloak) and can be used with any compatible backend.
+
+## Features
+- Bearer token security scheme for OpenAPI
+- AuthContext dependency for user/client authentication
+- Role-based and route protection dependencies
+- Easy integration with any provider implementing the API protocols
+
+## Usage
+1. Install this package and your chosen provider implementation.
+2. Configure your provider (e.g., Keycloak) in your FastAPI app.
+3. Inject the provider into the dependencies from this package.
+
+## License
+LKSISL

lks_idprovider_fastapi-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["poetry-core>=2.0"]
+build-backend = "poetry.core.masonry.api"
+
+[project]
+name = "lks-idprovider-fastapi"
+version = "0.1.0"
+description = "Provider-agnostic FastAPI integration for lks-idprovider API protocols."
+authors = [
+    {name = "Raul Medeiros", email = "rmedeiros@lksnext.com"}
+]
+license = "LKSISL"
+readme = "README.md"
+requires-python = ">=3.11"
+
+dependencies = [
+    "fastapi>=0.116.1",
+    "lks-idprovider-api>=0.1.6,<0.2.0"
+]
+
+[tool.poetry]
+packages = [{include = "lks_idprovider_fastapi", from = "src"}]
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0.0"
+pytest-cov = "^5.0.0"
+pytest-asyncio = "^0.23.0"
+pytest-dotenv = "^0.5.2"
+lks-idprovider-keycloak = ">=0.1.1,<0.2.0"
+lks-idprovider-entraid = ">=0.1.0,<0.2.0"
+
+
+
+

lks_idprovider_fastapi-0.1.0/src/lks_idprovider_fastapi/__init__.py

@@ -0,0 +1,17 @@
+from .security import get_bearer_token
+from .dependencies import (
+    get_auth_context,
+    login_required,
+    requires_role,
+    requires_any_role,
+)
+
+__all__ = [
+    # Security
+    "get_bearer_token",
+    # Dependencies
+    "get_auth_context",
+    "login_required",
+    "requires_role",
+    "requires_any_role",
+]

lks_idprovider_fastapi-0.1.0/src/lks_idprovider_fastapi/dependencies.py

@@ -0,0 +1,191 @@
+from typing import Union, Optional, Callable
+from fastapi import Depends, HTTPException, status
+from lks_idprovider_fastapi.security import get_bearer_token
+from lks_idprovider.models.auth import AuthContext
+from lks_idprovider.protocols import ClientCredentialsProvider, IdentityProvider
+
+
+# Default provider factory - should be overridden in production
+def get_default_provider() -> Union[ClientCredentialsProvider, IdentityProvider]:
+    """Default provider factory that raises an error.
+
+    This should be overridden in production applications to return
+    the actual provider instance.
+    """
+    raise HTTPException(
+        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        detail="No provider configured. Please override get_default_provider dependency.",
+    )
+
+
+async def get_auth_context(
+    token: str = Depends(get_bearer_token),
+    provider: Union[ClientCredentialsProvider, IdentityProvider] = Depends(
+        get_default_provider
+    ),
+) -> AuthContext:
+    """
+    Dependency that resolves and returns an AuthContext for the current request.
+
+    Args:
+        token (str): The bearer token extracted from the request, provided by the get_bearer_token dependency.
+        provider (Any): An instance of either IdentityProvider or ClientCredentialsProvider, injected as a dependency.
+
+    Returns:
+        AuthContext: The authentication context associated with the provided token.
+
+    Raises:
+        HTTPException: If authentication fails or the provider is not properly initialized.
+    """
+
+    try:
+        if isinstance(provider, IdentityProvider):
+            ctx = await provider.get_auth_context(token)
+        elif isinstance(provider, ClientCredentialsProvider):
+            ctx = await provider.get_client_auth_context(token)
+        return ctx
+    except Exception as e:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail=str(e))
+
+
+async def login_required(
+    token: str = Depends(get_bearer_token),
+    provider: Union[ClientCredentialsProvider, IdentityProvider] = Depends(
+        get_default_provider
+    ),
+) -> AuthContext:
+    """
+    Dependency that validates the token and returns an AuthContext.
+
+    This is a convenience alias for get_auth_context that clearly indicates
+    the endpoint requires a valid login/authentication.
+
+    Args:
+        token (str): The bearer token extracted from the request.
+        provider: An instance of either IdentityProvider or ClientCredentialsProvider.
+
+    Returns:
+        AuthContext: The authentication context for the validated token.
+
+    Raises:
+        HTTPException: If authentication fails.
+    """
+    return await get_auth_context(token, provider)
+
+
+def _check_role_access(
+    auth_context: AuthContext, role_names: list[str], client: Optional[str] = None
+) -> None:
+    """
+    Helper function to check if the user has any of the required roles.
+
+    Args:
+        auth_context: The authentication context.
+        role_names: List of role names to check.
+        client: Optional client ID for client-specific roles.
+
+    Raises:
+        HTTPException: If the user doesn't have any of the required roles.
+    """
+    # Check if user has any of the required roles
+    user_has_role = any(
+        role.name in role_names and role.client == client for role in auth_context.roles
+    )
+
+    if not user_has_role:
+        # Create a more streamlined and descriptive error message
+        if len(role_names) == 1:
+            role_desc = f"'{role_names[0]}'"
+            message = f"Required role {role_desc}"
+        else:
+            roles_str = "', '".join(role_names)
+            role_desc = f"['{roles_str}']"
+            message = f"At least one of roles {role_desc}"
+
+        client_part = f" for client '{client}'" if client else ""
+        detail = f"Access denied. {message}{client_part} is required."
+
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail=detail,
+        )
+
+
+def _create_role_dependency(
+    role_names: list[str], client: Optional[str] = None
+) -> Callable[[AuthContext], AuthContext]:
+    """
+    Internal helper to create a role dependency function.
+    """
+
+    def role_dependency(
+        auth_context: AuthContext = Depends(get_auth_context),
+    ) -> AuthContext:
+        """
+        Internal dependency that validates role access.
+        """
+        _check_role_access(auth_context, role_names, client)
+        return auth_context
+
+    return role_dependency
+
+
+def requires_role(
+    role_name: str, client: Optional[str] = None
+) -> Callable[[AuthContext], AuthContext]:
+    """
+    Dependency factory that creates a role-based access control dependency.
+
+    This function returns a dependency that checks if the authenticated user/client
+    has the specified role. It builds on top of get_auth_context.
+
+    Args:
+        role_name (str): The name of the required role.
+        client (Optional[str]): The client ID for client-specific roles. If None,
+                               checks for realm/global roles.
+
+    Returns:
+        Callable: A FastAPI dependency function that validates role access.
+
+    Example:
+        ```python
+        @app.get("/admin")
+        async def admin_endpoint(
+            auth_context: AuthContext = Depends(requires_role("admin"))
+        ):
+            return {"message": "Admin access granted"}
+
+        @app.get("/client-specific")
+        async def client_endpoint(
+            auth_context: AuthContext = Depends(requires_role("manager", client="my-app"))
+        ):
+            return {"message": "Client-specific role access granted"}
+        ```
+    """
+    return _create_role_dependency([role_name], client)
+
+
+def requires_any_role(
+    *role_names: str, client: Optional[str] = None
+) -> Callable[[AuthContext], AuthContext]:
+    """
+    Dependency factory that creates a role-based access control dependency
+    that accepts any of the specified roles.
+
+    Args:
+        *role_names: Variable number of role names. User must have at least one.
+        client (Optional[str]): The client ID for client-specific roles.
+
+    Returns:
+        Callable: A FastAPI dependency function that validates role access.
+
+    Example:
+        ```python
+        @app.get("/editor")
+        async def editor_endpoint(
+            auth_context: AuthContext = Depends(requires_any_role("editor", "admin"))
+        ):
+            return {"message": "Editor or admin access granted"}
+        ```
+    """
+    return _create_role_dependency(list(role_names), client)

lks_idprovider_fastapi-0.1.0/src/lks_idprovider_fastapi/security.py

@@ -0,0 +1,10 @@
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from fastapi import Depends
+
+bearer_scheme = HTTPBearer(auto_error=True)
+
+
+def get_bearer_token(
+    credentials: HTTPAuthorizationCredentials = Depends(bearer_scheme),
+) -> str:
+    return credentials.credentials