usso 0.27.22__py3-none-any.whl → 0.28.1__py3-none-any.whl

usso/__init__.py

@@ -1,4 +1,25 @@
-from .core import UserData, Usso
+"""USSO - Universal Single Sign-On Client
+
+A plug-and-play client for integrating universal single sign-on (SSO)
+with Python frameworks, enabling secure and seamless authentication
+across microservices.
+"""
+
+from .auth import APIHeaderConfig, AuthConfig, HeaderConfig, UssoAuth
 from .exceptions import USSOException
+from .models.user import UserData
+
+__version__ = "0.28.0"
 
-__all__ = ["UserData", "Usso", "USSOException"]
+__all__ = [
+    # Main client
+    "UssoAuth",
+    # Configuration
+    "AuthConfig",
+    "HeaderConfig",
+    "APIHeaderConfig",
+    # Models
+    "UserData",
+    # Exceptions
+    "USSOException",
+]

usso/auth/__init__.py

@@ -0,0 +1,9 @@
+"""USSO Authentication Module.
+
+This module provides the core authentication functionality for USSO.
+"""
+
+from .client import UssoAuth
+from .config import APIHeaderConfig, AuthConfig, HeaderConfig
+
+__all__ = ["UssoAuth", "AuthConfig", "HeaderConfig", "APIHeaderConfig"]

usso/auth/api_key.py

@@ -0,0 +1,43 @@
+import logging
+from urllib.parse import urlparse
+
+import cachetools.func
+import httpx
+
+from ..exceptions import USSOException
+from ..models.user import UserData
+
+logger = logging.getLogger("usso")
+
+
+def _handle_exception(error_type: str, **kwargs):
+    """Handle API key related exceptions."""
+    if kwargs.get("raise_exception", True):
+        raise USSOException(
+            status_code=401, error=error_type, message=kwargs.get("message")
+        )
+    logger.error(kwargs.get("message") or error_type)
+
+
+@cachetools.func.ttl_cache(maxsize=128, ttl=10 * 60)
+def fetch_api_key_data(jwk_url: str, api_key: str):
+    """Fetch user data using an API key.
+
+    Args:
+        jwk_url: The JWK URL to use for verification
+        api_key: The API key to verify
+
+    Returns:
+        UserData: The user data associated with the API key
+
+    Raises:
+        USSOException: If the API key is invalid or verification fails
+    """
+    try:
+        parsed = urlparse(jwk_url)
+        url = f"{parsed.scheme}://{parsed.netloc}/api_key/verify"
+        response = httpx.post(url, json={"api_key": api_key})
+        response.raise_for_status()
+        return UserData(**response.json())
+    except Exception as e:
+        _handle_exception("error", message=str(e))

usso/auth/client.py

@@ -0,0 +1,87 @@
+import logging
+
+import usso_jwt.exceptions
+import usso_jwt.schemas
+
+from ..exceptions import _handle_exception
+from ..models.user import UserData
+from .api_key import fetch_api_key_data
+from .config import AuthConfig, AvailableJwtConfigs
+
+logger = logging.getLogger("usso")
+
+
+class UssoAuth:
+    """Main authentication client for USSO.
+
+    This client handles token validation, user data retrieval,
+    and API key verification.
+    """
+
+    def __init__(
+        self,
+        *,
+        jwt_config: AvailableJwtConfigs | None = None,
+    ):
+        """Initialize the USSO authentication client.
+
+        Args:
+            jwt_config: JWT configuration(s) to use for token validation
+        """
+        if jwt_config is None:
+            jwt_config = AuthConfig()
+        self.jwt_configs = AuthConfig.validate_jwt_configs(jwt_config)
+
+    def user_data_from_token(
+        self,
+        token: str,
+        *,
+        expected_acr: str | None = "access",
+        raise_exception: bool = True,
+        **kwargs,
+    ) -> UserData | None:
+        """Get user data from a JWT token.
+
+        Args:
+            token: The JWT token to validate
+            expected_acr: Expected authentication context reference
+            raise_exception: Whether to raise exception on error
+            **kwargs: Additional arguments to pass to token verification
+
+        Returns:
+            UserData if token is valid, None otherwise
+
+        Raises:
+            USSOException: If token is invalid and raise_exception is True
+        """
+        exp = None
+        for jwk_config in self.jwt_configs:
+            try:
+                jwt_obj = usso_jwt.schemas.JWT(
+                    token=token, config=jwk_config, payload_class=UserData
+                )
+                if jwt_obj.verify(expected_acr=expected_acr, **kwargs):
+                    return jwt_obj.payload
+            except usso_jwt.exceptions.JWTError as e:
+                exp = e
+
+        _handle_exception(
+            "Unauthorized",
+            message=str(exp) if exp else None,
+            raise_exception=raise_exception,
+            **kwargs,
+        )
+
+    def user_data_from_api_key(self, api_key: str) -> UserData:
+        """Get user data from an API key.
+
+        Args:
+            api_key: The API key to verify
+
+        Returns:
+            UserData: The user data associated with the API key
+
+        Raises:
+            USSOException: If the API key is invalid
+        """
+        return fetch_api_key_data(self.jwt_configs[0].jwk_url, api_key)

usso/auth/config.py

@@ -0,0 +1,115 @@
+import json
+from typing import Any, Literal, Union
+
+import usso_jwt.config
+from pydantic import BaseModel, model_validator
+
+from ..models.user import UserData
+from ..utils.string_utils import get_authorization_scheme_param
+
+
+class HeaderConfig(BaseModel):
+    type: Literal["Authorization", "Cookie", "CustomHeader"] = "Cookie"
+    name: str = "usso_access_token"
+
+    @model_validator(mode="before")
+    def validate_header(cls, data: dict):
+        if data.get("type") == "Authorization" and not data.get("name"):
+            data["name"] = "Bearer"
+        elif data.get("type") == "Cookie":
+            data["name"] = data.get("name", "usso_access_token")
+        elif data.get("type") == "CustomHeader":
+            data["name"] = data.get("name", "x-usso-access-token")
+        return data
+
+    def __hash__(self):
+        return hash(self.model_dump_json())
+
+    def get_key(self, request) -> str | None:
+        headers: dict[str, Any] = getattr(request, "headers", {})
+        cookies: dict[str, str] = getattr(
+            request, "cookies", headers.get("Cookie", {})
+        )
+        if self.type == "CustomHeader":
+            return headers.get(self.name)
+        elif self.type == "Cookie":
+            return cookies.get(self.name)
+        elif self.type == "Authorization":
+            authorization = headers.get("Authorization")
+        if self.type == "Authorization":
+            authorization = headers.get("Authorization")
+            scheme, credentials = get_authorization_scheme_param(authorization)
+            if scheme.lower() == self.name.lower():
+                return credentials
+
+
+class APIHeaderConfig(HeaderConfig):
+    verify_endpoint: str = "https://sso.usso.io/api_key/verify"
+
+
+class AuthConfig(usso_jwt.config.JWTConfig):
+    """Configuration for JWT processing."""
+
+    api_key_header: APIHeaderConfig | None = APIHeaderConfig(
+        type="CustomHeader", name="x-api-key"
+    )
+    jwt_header: HeaderConfig | None = HeaderConfig()
+    static_api_keys: list[str] | None = None
+
+    def get_api_key(self, request) -> str | None:
+        if self.api_key_header:
+            return self.api_key_header.get_key(request)
+        return None
+
+    def get_jwt(self, request) -> str | None:
+        if self.jwt_header:
+            return self.jwt_header.get_key(request)
+        return None
+
+    def verify_token(
+        self, token: str, *, raise_exception: bool = True, **kwargs
+    ) -> bool:
+        from usso_jwt import exceptions as jwt_exceptions
+        from usso_jwt import schemas
+
+        try:
+            return schemas.JWT(
+                token=token,
+                config=self,
+                payload_class=UserData,
+            ).verify(**kwargs)
+        except jwt_exceptions.JWTError as e:
+            if raise_exception:
+                raise e
+            return False
+
+    @classmethod
+    def _parse_config(
+        cls, config: Union[str, dict, "AuthConfig"]
+    ) -> "AuthConfig":
+        """Parse a single JWT configuration."""
+        if isinstance(config, str):
+            config = json.loads(config)
+        if isinstance(config, dict):
+            return cls(**config)
+        if isinstance(config, cls):
+            return config
+        raise ValueError("Invalid JWT configuration")
+
+    @classmethod
+    def validate_jwt_configs(
+        cls,
+        jwt_config: Union[
+            str, dict, "AuthConfig", list[str], list[dict], list["AuthConfig"]
+        ],
+    ) -> list["AuthConfig"]:
+        if isinstance(jwt_config, (str, dict, cls)):
+            return [cls._parse_config(jwt_config)]
+        if isinstance(jwt_config, list):
+            return [cls._parse_config(config) for config in jwt_config]
+        raise ValueError("Invalid jwt_config format")
+
+
+AvailableJwtConfigs = (
+    str | dict | AuthConfig | list[str] | list[dict] | list[AuthConfig]
+)

usso/exceptions.py

@@ -1,3 +1,7 @@
+import logging
+
+logger = logging.getLogger("usso")
+
 error_messages = {
     "invalid_signature": "Unauthorized. The JWT signature is invalid.",
     "invalid_token": "Unauthorized. The JWT is invalid or not provided.",
@@ -15,3 +19,12 @@ class USSOException(Exception):
         if message is None:
             self.message = error_messages[error]
         super().__init__(message)
+
+
+def _handle_exception(error_type: str, **kwargs):
+    """Handle JWT-related exceptions."""
+    if kwargs.get("raise_exception", True):
+        raise USSOException(
+            status_code=401, error=error_type, message=kwargs.get("message")
+        )
+    logger.error(kwargs.get("message") or error_type)

usso/integrations/django/__init__.py

@@ -0,0 +1,3 @@
+from .middleware import USSOAuthenticationMiddleware
+
+__all__ = ["USSOAuthenticationMiddleware"]

usso/{django → integrations/django}/middleware.py

@@ -1,4 +1,5 @@
 import logging
+from urllib.parse import urlparse
 
 from django.conf import settings
 from django.contrib.auth.models import User
@@ -6,17 +7,20 @@ from django.db.utils import IntegrityError
 from django.http import JsonResponse
 from django.http.request import HttpRequest
 from django.utils.deprecation import MiddlewareMixin
-
-from usso import UserData, Usso, USSOException
+from usso import AuthConfig, UserData, UssoAuth, USSOException
 
 logger = logging.getLogger("usso")
 
 
 class USSOAuthenticationMiddleware(MiddlewareMixin):
+    @property
+    def jwt_config(self) -> AuthConfig:
+        return settings.USSO_JWT_CONFIG
 
     def process_request(self, request: HttpRequest):
         """
-        Middleware to authenticate users by JWT token and create or return a user in the database.
+        Middleware to authenticate users by JWT token and create or
+        return a user in the database.
         """
         try:
             if hasattr(request, "user") and request.user.is_authenticated:
@@ -31,44 +35,48 @@ class USSOAuthenticationMiddleware(MiddlewareMixin):
             # Handle any errors raised by USSO authentication
             return JsonResponse({"error": str(e)}, status=401)
 
-    def get_request_token(self, request: HttpRequest) -> str | None:
-        authorization = request.headers.get("Authorization")
-        if authorization:
-            scheme, credentials = Usso(
-                jwks_url=settings.USSO_JWK_URL
-            ).get_authorization_scheme_param(authorization)
-            if scheme.lower() == "bearer":
-                return credentials  # Bearer token
-
-        return request.COOKIES.get("usso_access_token")
+    def get_request_jwt(self, request: HttpRequest) -> str | None:
+        return self.jwt_config.get_jwt(request)
 
-    def jwt_access_security_none(self, request: HttpRequest) -> UserData | None:
+    def jwt_access_security_none(
+        self,
+        request: HttpRequest,
+    ) -> UserData | None:
         """Return the user associated with a token value."""
-        token = self.get_request_token(request)
+        usso_auth = UssoAuth(jwt_config=self.jwt_config)
+        api_key = self.jwt_config.get_api_key(request)
+        if api_key:
+            return usso_auth.user_data_from_api_key(api_key)
+
+        token = self.get_request_jwt(request)
         if not token:
             return None
-        return Usso(jwks_url=settings.USSO_JWK_URL).user_data_from_token(
-            token, raise_exception=False
-        )
+        return usso_auth.user_data_from_token(token, raise_exception=False)
 
     def jwt_access_security(self, request: HttpRequest) -> UserData | None:
         """Return the user associated with a token value."""
-        token = self.get_request_token(request)
-        if not token:
-            raise USSOException(
-                status_code=401,
-                error="unauthorized",
-            )
+        usso_auth = UssoAuth(jwt_config=self.jwt_config)
+        api_key = self.jwt_config.get_api_key(request)
+        if api_key:
+            return usso_auth.user_data_from_api_key(api_key)
 
-        # Get user data from the token
-        return Usso(jwks_url=settings.USSO_JWK_URL).user_data_from_token(token)
+        token = self.get_request_jwt(request)
+        if not token:
+            return None
+        return usso_auth.user_data_from_token(token, raise_exception=False)
 
     def get_or_create_user(self, user_data: UserData) -> User:
         """
-        Check if a user exists by phone. If not, create a new user and return it.
+        Check if a user exists by phone. If not, create a new user
+        and return it.
         """
+        if self.jwt_config.jwk_url:
+            domain = urlparse(self.jwt_config.jwk_url).netloc
+        else:
+            domain = "example.com"
         phone = user_data.phone
-        email = user_data.email or f"{user_data.user_id}@example.com"  # Fallback email
+        email = user_data.email or f"{user_data.user_id}@{domain}"
+        # Fallback email
 
         try:
             # Try to get the user by phone
@@ -87,4 +95,4 @@ class USSOAuthenticationMiddleware(MiddlewareMixin):
 
         except IntegrityError as e:
             logger.error(f"Integrity error while creating user: {str(e)}")
-            raise ValueError(f"Error while creating user: {str(e)}")
+            raise ValueError(f"Error while creating user: {str(e)}") from e

usso/integrations/fastapi/__init__.py

@@ -0,0 +1,8 @@
+from .dependency import USSOAuthentication
+from .handler import EXCEPTION_HANDLERS, usso_exception_handler
+
+__all__ = [
+    "USSOAuthentication",
+    "EXCEPTION_HANDLERS",
+    "usso_exception_handler",
+]

usso/integrations/fastapi/dependency.py

@@ -0,0 +1,80 @@
+import logging
+
+from fastapi import Request, WebSocket
+
+from ...auth import UssoAuth
+from ...auth.config import AuthConfig, AvailableJwtConfigs
+from ...exceptions import _handle_exception
+from ...models.user import UserData
+from ...utils.method_utils import instance_method
+
+logger = logging.getLogger("usso")
+
+
+class USSOAuthentication(UssoAuth):
+    def __init__(
+        self,
+        jwt_config: AvailableJwtConfigs | None = None,
+        raise_exception: bool = True,
+    ):
+        if jwt_config is None:
+            jwt_config = AuthConfig()
+
+        super().__init__(jwt_config=jwt_config)
+        self.raise_exception = raise_exception
+
+    def __call__(self, request: Request) -> UserData:
+        return self.usso_access_security(request)
+
+    @instance_method
+    def get_request_jwt(self, request: Request | WebSocket) -> str | None:
+        for jwt_config in self.jwt_configs:
+            token = jwt_config.get_jwt(request)
+            if token:
+                return token
+        return None
+
+    @instance_method
+    def get_request_api_key(self, request: Request | WebSocket) -> str | None:
+        for jwt_config in self.jwt_configs:
+            token = jwt_config.get_api_key(request)
+            if token:
+                return token
+        return None
+
+    # @instance_method
+    def usso_access_security(self, request: Request) -> UserData | None:
+        """Return the user associated with a token value."""
+        api_key = self.get_request_api_key(request)
+        if api_key:
+            return self.user_data_from_api_key(api_key)
+
+        token = self.get_request_jwt(request)
+        if token:
+            return self.user_data_from_token(
+                token, raise_exception=self.raise_exception
+            )
+
+        _handle_exception(
+            "Unauthorized",
+            message="No token provided",
+            raise_exception=self.raise_exception,
+        )
+
+    # @instance_method
+    def jwt_access_security_ws(self, websocket: WebSocket) -> UserData | None:
+        """Return the user associated with a token value."""
+        api_key = self.get_request_api_key(websocket)
+        if api_key:
+            return self.user_data_from_api_key(api_key)
+
+        token = self.get_request_jwt(websocket)
+        if token:
+            return self.user_data_from_token(
+                token, raise_exception=self.raise_exception
+            )
+        _handle_exception(
+            "Unauthorized",
+            message="No token provided",
+            raise_exception=self.raise_exception,
+        )

usso/integrations/fastapi/handler.py

@@ -0,0 +1,16 @@
+from fastapi import Request
+from fastapi.responses import JSONResponse
+
+from ...exceptions import USSOException
+
+
+async def usso_exception_handler(request: Request, exc: USSOException):
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={"message": exc.message, "error": exc.error},
+    )
+
+
+EXCEPTION_HANDLERS = {
+    USSOException: usso_exception_handler,
+}

usso/models/user.py

@@ -0,0 +1,119 @@
+from collections.abc import Callable
+from enum import StrEnum
+from typing import Any, Literal
+
+from pydantic import BaseModel
+
+
+class TokenType(StrEnum):
+    ACCESS = "access"
+    REFRESH = "refresh"
+    SECURE_TOKEN = "secure"
+    ONE_TIME_TOKEN = "one_time"
+    TEMPORARY_TOKEN = "temporary"
+    MFA_TEMPORARY_TOKEN = "mfa_temporary"
+
+
+class UserData(BaseModel):
+    jti: str | None = None
+    typ: TokenType | None = None
+    iss: str | None = None
+    aud: str | None = None
+    iat: int | None = None
+    nbf: int | None = None
+    exp: int | None = None
+    sub: str | None = None
+    tenant_id: str | None = None
+    workspace_id: str | None = None
+    roles: list[str] | None = None
+    scopes: list[str] | None = None
+    acr: str | None = None
+    signing_level: str | None = None
+
+    claims: dict | None = None
+
+    def __init__(
+        self,
+        *,
+        jti: str | None = None,
+        typ: TokenType | None = None,
+        iss: str | None = None,
+        aud: str | None = None,
+        iat: int | None = None,
+        nbf: int | None = None,
+        exp: int | None = None,
+        sub: str | None = None,
+        tenant_id: str | None = None,
+        workspace_id: str | None = None,
+        roles: list[str] | None = None,
+        scopes: list[str] | None = None,
+        acr: str | None = None,
+        signing_level: str | None = None,
+        **kwargs,
+    ):
+        super().__init__(
+            jti=jti,
+            typ=typ,
+            iss=iss,
+            aud=aud,
+            iat=iat,
+            nbf=nbf,
+            exp=exp,
+            sub=sub,
+            tenant_id=tenant_id,
+            workspace_id=workspace_id,
+            roles=roles,
+            scopes=scopes,
+            acr=acr,
+            signing_level=signing_level,
+        )
+        self.claims = self.model_dump() | kwargs
+
+    @property
+    def user_id(self) -> str:
+        if self.claims and "user_id" in self.claims:
+            return self.claims["user_id"]
+        return self.sub or ""
+
+    @property
+    def email(self) -> str:
+        if self.claims and "email" in self.claims:
+            return self.claims["email"]
+        return ""
+
+    @property
+    def phone(self) -> str:
+        if self.claims and "phone" in self.claims:
+            return self.claims["phone"]
+        return ""
+
+    def model_dump(
+        self,
+        *,
+        mode: Literal["json", "python"] | str = "python",
+        include=None,
+        exclude=None,
+        context: Any | None = None,
+        by_alias: bool | None = None,
+        exclude_unset: bool = False,
+        exclude_defaults: bool = False,
+        exclude_none: bool = True,
+        round_trip: bool = False,
+        warnings: bool | Literal["none", "warn", "error"] = True,
+        fallback: Callable[[Any], Any] | None = None,
+        serialize_as_any: bool = False,
+    ):
+        return super().model_dump(
+            mode=mode,
+            include=include,
+            exclude=exclude,
+            context=context,
+            by_alias=by_alias,
+            exclude_unset=exclude_unset,
+            exclude_defaults=exclude_defaults,
+            exclude_none=exclude_none,
+            round_trip=round_trip,
+            warnings=warnings,
+            fallback=fallback,
+            serialize_as_any=serialize_as_any,
+        )

usso/session/async_session.py

@@ -37,7 +37,9 @@ class AsyncUssoSession(httpx.AsyncClient, BaseUssoSession):
         Helper function to prepare headers and parameters for refresh requests.
         """
         headers = (
-            {"x-api-key": self.usso_admin_api_key} if self.usso_admin_api_key else {}
+            {"x-api-key": self.usso_admin_api_key}
+            if self.usso_admin_api_key
+            else {}
         )
         params = {"user_id": self.user_id} if self.user_id else {}
         return headers, params
@@ -51,13 +53,15 @@ class AsyncUssoSession(httpx.AsyncClient, BaseUssoSession):
         self.access_token = data.get("access_token")
         self._refresh_token = data.get("token", {}).get("refresh_token")
         if self.access_token:
-            self.headers.update({"Authorization": f"Bearer {self.access_token}"})
+            self.headers.update({
+                "Authorization": f"Bearer {self.access_token}"
+            })
         return data
 
     def _refresh_sync(self) -> dict:
-        assert (
-            self.refresh_token or self.usso_admin_api_key
-        ), "refresh_token or usso_api_key is required"
+        assert self.refresh_token or self.usso_admin_api_key, (
+            "refresh_token or usso_api_key is required"
+        )
 
         headers, params = self._prepare_refresh_request()
 
@@ -73,9 +77,9 @@ class AsyncUssoSession(httpx.AsyncClient, BaseUssoSession):
         return self._handle_refresh_response(response)
 
     async def _refresh(self) -> dict:
-        assert (
-            self.refresh_token or self.usso_admin_api_key
-        ), "refresh_token or usso_api_key is required"
+        assert self.refresh_token or self.usso_admin_api_key, (
+            "refresh_token or usso_api_key is required"
+        )
 
         headers, params = self._prepare_refresh_request()