Merge pull request #20 from OSSMafia/mnick/19

chore: expanded testing and documentation

Author: mattylight22

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 0.0.8
+current_version = 0.0.9
 commit = True
 tag = True
 

README.md

@@ -37,27 +37,65 @@ clerk_config = ClerkConfig(jwks_url="https://your-clerk-frontend-api.clerk.accou
 clerk_auth_guard = ClerkHTTPBearer(config=clerk_config)
 
 @app.get("/")
-async def read_root(credentials: HTTPAuthorizationCredentials | None = Depends(clerk_auth_guard)):
+async def read_root(credentials: HTTPAuthorizationCredentials = Depends(clerk_auth_guard)):
     return JSONResponse(content=jsonable_encoder(credentials))
 ```
 
-The returned `credentials` model will be either `None` or an `HTTPAuthorizationCredentials` object with these properties:
+The returned `credentials` model will be an `HTTPAuthorizationCredentials` object with these properties:
 
 - `scheme`: Indicates the scheme of the Authorization header (Bearer) 
 - `credentials`: Raw token received from the Authorization header
 - `decoded`: The payload of the decoded token
 
 ## Configuration Options
 
+### Debug Mode
+
+By default, the middleware suppresses exceptions in order to prevent logging sensitive information. You can change this behavior in the `ClerkHTTPBearer`:
+
+```python
+clerk_auth_guard = ClerkHTTPBearer(config=clerk_config, debug_mode=True)  # Set debug_mode=True
+```
+
+
+### Fixing Issued At Time (IAT) Errors
+
+In some instances the system clock of an API may be slightly out-of-sync which can cause issues with verifying the `iat` claim.
+
+This can be solved one of two ways:
+
+1: Disable verifying the `iat` claim, there could be security implications by disabling so make sure it is secure for your use case.
+
+```python
+clerk_config = ClerkConfig(
+    jwks_url="https://your-clerk-frontend-api.clerk.accounts.dev/.well-known/jwks.json",
+    verify_iat=False,
+) 
+
+clerk_auth_guard = ClerkHTTPBearer(config=clerk_config)
+```
+
+2: Adding `leeway` which is a number of seconds to allow tolerance for drift, it can compensate for out-of-sync clocks.
+
+```python
+clerk_config = ClerkConfig(
+    jwks_url="https://your-clerk-frontend-api.clerk.accounts.dev/.well-known/jwks.json",
+    leeway=5.0,
+) 
+
+clerk_auth_guard = ClerkHTTPBearer(config=clerk_config)
+```
+
 ### Disabling Auto Errors
 
 By default, the middleware automatically returns 403 errors if the token is missing or invalid. You can disable this behavior:
 
 ```python
 clerk_config = ClerkConfig(
-    jwks_url="https://your-clerk-frontend-api.clerk.accounts.dev/.well-known/jwks.json", 
-    auto_error=False
-)
+    jwks_url="https://your-clerk-frontend-api.clerk.accounts.dev/.well-known/jwks.json"
+) 
+
+clerk_auth_guard = ClerkHTTPBearer(config=clerk_config, auto_error=False)  # Set auto_error=False
 ```
 
 This allows requests to reach the endpoint for additional logic or custom error handling:
@@ -99,6 +137,15 @@ async def read_todo_list(request: Request):
     return {"message": f"Todo items for user {user_id}"}
 ```
 
+The class stored in `request.state.clerk_auth` looks like this:
+```python
+HTTPAuthorizationCredentials(
+    decoded: Optional[dict],  # Decoded JWT Token
+    scheme: str = "Bearer",
+    credentials: str,  # Raw JWT Token
+)
+```
+
 ## Advanced Usage
 
 ### Role-Based Access Control

docker-compose.yaml

@@ -26,6 +26,10 @@ services:
       context: .
       dockerfile: dockerfile
       target: test
+    environment:
+      - JWT_SUB_CLAIM=1234567890
+      - JWT_AUDIENCE_CLAIM=test
+      - JWT_ISSUER_CLAIM=test_issuer
     networks:
       - default
     depends_on:

fastapi_clerk_auth/__init__.py

@@ -2,7 +2,6 @@
 
 from fastapi import HTTPException, Request
 from fastapi.encoders import jsonable_encoder
-from fastapi.openapi.models import HTTPBearer as HTTPBearerModel
 from fastapi.security import HTTPAuthorizationCredentials as FastAPIHTTPAuthorizationCredentials, HTTPBearer
 from fastapi.security.utils import get_authorization_scheme_param
 import jwt
@@ -19,6 +18,7 @@ class ClerkConfig(BaseModel):
     verify_exp: bool = True
     verify_aud: bool = False
     verify_iss: bool = False
+    verify_iat: bool = True
     jwks_cache_keys: bool = False
     jwks_max_cached_keys: int = 16
     jwks_cache_set: bool = True
@@ -97,8 +97,6 @@ def __init__(
             description=description,
             auto_error=auto_error,
         )
-        self.model = HTTPBearerModel(bearerFormat=bearerFormat, description=description)
-        self.scheme_name = scheme_name or self.__class__.__name__
         self.auto_error = auto_error
         self.add_state = add_state
         self.config = config
@@ -137,6 +135,7 @@ def _decode_token(self, token: str) -> dict | None:
                     "verify_exp": self.config.verify_exp,
                     "verify_aud": self.config.verify_aud,
                     "verify_iss": self.config.verify_iss,
+                    "verify_iat": self.config.verify_iat,
                 },
                 leeway=self.config.leeway,
             )
@@ -159,6 +158,7 @@ async def __call__(self, request: Request) -> Optional[HTTPAuthorizationCredenti
             return None
 
         decoded_token: dict | None = self._decode_token(token=credentials)
+
         if not decoded_token and self.auto_error:
             raise HTTPException(status_code=HTTP_403_FORBIDDEN, detail="Forbidden")
         response = HTTPAuthorizationCredentials(scheme=scheme, credentials=credentials, decoded=decoded_token)

pyproject.toml

@@ -1,15 +1,12 @@
 [project]
 name = "fastapi_clerk_auth"
-version = "0.0.8"
+version = "0.0.9"
 description = "FastAPI Auth Middleware for Clerk (https://clerk.com)"
 readme = "README.md"
 requires-python = ">=3.9"
 authors = [
     { name = "Matt Nick", email = "[email protected]" },
 ]
-maintainers = [
-    { name = "Matt Nick", email = "[email protected]" },
-]
 classifiers = [
     "Development Status :: 5 - Production/Stable",
     "Framework :: FastAPI",

tests/conftest.py

@@ -4,15 +4,70 @@
 import pytest
 
 
+def generate_jwt(payload: dict) -> str:
+    with open("./mock_files/test_private_key.pem") as key_file:
+        private_key = key_file.read()
+
+    return jwt.encode(payload, private_key, algorithm="RS256", headers={"kid": "ins_test_key_1"})
+
+
 @pytest.fixture
-def jwt_token():
-    return generate_jwt()
+def jwt_token_default():
+    payload = {
+        "sub": "1234567890",
+        "iat": int(time()),
+        "exp": int(time()) + 300,
+    }
+    return generate_jwt(payload)
 
 
-def generate_jwt():
-    with open("./mock_files/test_private_key.pem") as key_file:
-        private_key = key_file.read()
+@pytest.fixture
+def jwt_token_audience():
+    payload = {
+        "sub": "1234567890",
+        "aud": "test",
+        "iat": int(time()),
+        "exp": int(time()) + 300,
+    }
+    return generate_jwt(payload)
 
-    payload = {"sub": "1234567890", "iat": int(time()), "exp": int(time()) + 300}
 
-    return jwt.encode(payload, private_key, algorithm="RS256", headers={"kid": "ins_test_key_1"})
+@pytest.fixture
+def jwt_token_issuer():
+    payload = {
+        "sub": "1234567890",
+        "iat": int(time()),
+        "exp": int(time()) + 300,
+        "iss": "test_issuer",
+    }
+    return generate_jwt(payload)
+
+
+@pytest.fixture
+def jwt_token_iat_future():
+    payload = {
+        "sub": "1234567890",
+        "iat": int(time()) + 600,
+        "exp": int(time()) + 900,
+    }
+    return generate_jwt(payload)
+
+
+@pytest.fixture
+def jwt_token_iat_future_short_leeway():
+    payload = {
+        "sub": "1234567890",
+        "iat": int(time()) + 10,
+        "exp": int(time()) + 600,
+    }
+    return generate_jwt(payload)
+
+
+@pytest.fixture
+def jwt_token_expired():
+    payload = {
+        "sub": "1234567890",
+        "iat": int(time()),
+        "exp": int(time()) - 300,
+    }
+    return generate_jwt(payload)