Add ACR support to integrations

Author: frankie567

fief_client/__init__.py

@@ -1,6 +1,7 @@
 "Fief client for Python."
 from fief_client.client import (
     Fief,
+    FiefAccessTokenACRTooLow,
     FiefAccessTokenExpired,
     FiefAccessTokenInfo,
     FiefAccessTokenInvalid,
@@ -25,6 +26,7 @@
     "FiefAccessTokenInfo",
     "FiefUserInfo",
     "FiefError",
+    "FiefAccessTokenACRTooLow",
     "FiefAccessTokenExpired",
     "FiefAccessTokenMissingPermission",
     "FiefAccessTokenMissingScope",

fief_client/client.py

@@ -24,6 +24,32 @@ class FiefACR(str, Enum):
     LEVEL_ONE = "1"
     """Level 1. Password authentication was performed."""
 
+    def __lt__(self, other: object) -> bool:
+        return self._compare(other, True, True)
+
+    def __le__(self, other: object) -> bool:
+        return self._compare(other, False, True)
+
+    def __gt__(self, other: object) -> bool:
+        return self._compare(other, True, False)
+
+    def __ge__(self, other: object) -> bool:
+        return self._compare(other, False, False)
+
+    def _compare(self, other: object, strict: bool, asc: bool) -> bool:
+        if not isinstance(other, FiefACR):
+            return NotImplemented  # pragma: no cover
+
+        if self == other:
+            return not strict
+
+        for elem in FiefACR:
+            if self == elem:
+                return asc
+            elif other == elem:
+                return not asc
+        raise RuntimeError()  # pragma: no cover
+
 
 class FiefTokenResponse(TypedDict):
     """
@@ -134,6 +160,10 @@ class FiefAccessTokenMissingScope(FiefError):
     """The access token is missing a required scope."""
 
 
+class FiefAccessTokenACRTooLow(FiefError):
+    """The access token doesn't meet the minimum ACR level."""
+
+
 class FiefAccessTokenMissingPermission(FiefError):
     """The access token is missing a required permission."""
 
@@ -254,6 +284,7 @@ def _validate_access_token(
         jwks: jwk.JWKSet,
         *,
         required_scope: Optional[List[str]] = None,
+        required_acr: Optional[FiefACR] = None,
         required_permissions: Optional[List[str]] = None,
     ) -> FiefAccessTokenInfo:
         try:
@@ -265,6 +296,15 @@ def _validate_access_token(
                     if scope not in access_token_scope:
                         raise FiefAccessTokenMissingScope()
 
+            try:
+                acr = FiefACR(claims["acr"])
+            except ValueError as e:
+                raise FiefAccessTokenInvalid() from e
+
+            if required_acr is not None:
+                if acr < required_acr:
+                    raise FiefAccessTokenACRTooLow()
+
             permissions: List[str] = claims["permissions"]
             if required_permissions is not None:
                 for required_permission in required_permissions:
@@ -274,7 +314,7 @@ def _validate_access_token(
             return {
                 "id": uuid.UUID(claims["sub"]),
                 "scope": access_token_scope,
-                "acr": claims["acr"],
+                "acr": acr,
                 "permissions": permissions,
                 "access_token": access_token,
             }
@@ -574,6 +614,7 @@ def validate_access_token(
         access_token: str,
         *,
         required_scope: Optional[List[str]] = None,
+        required_acr: Optional[FiefACR] = None,
         required_permissions: Optional[List[str]] = None,
     ) -> FiefAccessTokenInfo:
         """
@@ -583,6 +624,8 @@ def validate_access_token(
 
         :param access_token: The access token to validate.
         :param required_scope: Optional list of scopes to check for.
+        :param required_acr: Optional minimum ACR level required.
+        Read more: https://docs.fief.dev/going-further/acr/
         :param required_permissions: Optional list of permissions to check for.
 
         **Example: Validate access token with required scopes**
@@ -600,6 +643,21 @@ def validate_access_token(
         print(access_token_info)
         ```
 
+        **Example: Validate access token with minimum ACR level**
+
+        ```py
+        try:
+            access_token_info = fief.validate_access_token("ACCESS_TOKEN", required_acr=FiefACR.LEVEL_ONE)
+        except FiefAccessTokenInvalid:
+            print("Invalid access token")
+        except FiefAccessTokenExpired:
+            print("Expired access token")
+        except FiefAccessTokenACRTooLow:
+            print("ACR too low")
+
+        print(access_token_info)
+        ```
+
         **Example: Validate access token with required permissions**
 
         ```py
@@ -620,6 +678,7 @@ def validate_access_token(
             access_token,
             jwks,
             required_scope=required_scope,
+            required_acr=required_acr,
             required_permissions=required_permissions,
         )
 
@@ -983,6 +1042,7 @@ async def validate_access_token(
         access_token: str,
         *,
         required_scope: Optional[List[str]] = None,
+        required_acr: Optional[FiefACR] = None,
         required_permissions: Optional[List[str]] = None,
     ) -> FiefAccessTokenInfo:
         """
@@ -992,6 +1052,8 @@ async def validate_access_token(
 
         :param access_token: The access token to validate.
         :param required_scope: Optional list of scopes to check for.
+        :param required_acr: Optional minimum ACR level required.
+        Read more: https://docs.fief.dev/going-further/acr/
         :param required_permissions: Optional list of permissions to check for.
 
         **Example: Validate access token with required scopes**
@@ -1009,6 +1071,21 @@ async def validate_access_token(
         print(access_token_info)
         ```
 
+        **Example: Validate access token with minimum ACR level**
+
+        ```py
+        try:
+            access_token_info = await fief.validate_access_token("ACCESS_TOKEN", required_acr=FiefACR.LEVEL_ONE)
+        except FiefAccessTokenInvalid:
+            print("Invalid access token")
+        except FiefAccessTokenExpired:
+            print("Expired access token")
+        except FiefAccessTokenACRTooLow:
+            print("ACR too low")
+
+        print(access_token_info)
+        ```
+
         **Example: Validate access token with required permissions**
 
         ```py
@@ -1029,6 +1106,7 @@ async def validate_access_token(
             access_token,
             jwks,
             required_scope=required_scope,
+            required_acr=required_acr,
             required_permissions=required_permissions,
         )
 

fief_client/integrations/fastapi.py

@@ -21,11 +21,13 @@
 
 from fief_client import (
     Fief,
+    FiefAccessTokenACRTooLow,
     FiefAccessTokenExpired,
     FiefAccessTokenInfo,
     FiefAccessTokenInvalid,
     FiefAccessTokenMissingPermission,
     FiefAccessTokenMissingScope,
+    FiefACR,
     FiefAsync,
     FiefUserInfo,
 )
@@ -124,6 +126,7 @@ def authenticated(
         self,
         optional: bool = False,
         scope: Optional[List[str]] = None,
+        acr: Optional[FiefACR] = None,
         permissions: Optional[List[str]] = None,
     ):
         """
@@ -135,6 +138,9 @@ def authenticated(
         an unauthorized response will be raised.
         :param scope: Optional list of scopes required.
         If the access token lacks one of the required scope, a forbidden response will be raised.
+        :param acr: Optional minimum ACR level required.
+        If the access token doesn't meet the minimum level, a forbidden response will be raised.
+        Read more: https://docs.fief.dev/going-further/acr/
         :param permissions: Optional list of permissions required.
         If the access token lacks one of the required permission, a forbidden response will be raised.
 
@@ -164,7 +170,10 @@ async def _authenticated(
 
             try:
                 result = self.client.validate_access_token(
-                    token, required_scope=scope, required_permissions=permissions
+                    token,
+                    required_scope=scope,
+                    required_acr=acr,
+                    required_permissions=permissions,
                 )
                 if isawaitable(result):
                     info = await result
@@ -174,7 +183,11 @@ async def _authenticated(
                 if optional:
                     return None
                 return await self.get_unauthorized_response(request, response)
-            except (FiefAccessTokenMissingScope, FiefAccessTokenMissingPermission):
+            except (
+                FiefAccessTokenMissingScope,
+                FiefAccessTokenACRTooLow,
+                FiefAccessTokenMissingPermission,
+            ):
                 return await self.get_forbidden_response(request, response)
 
             return info
@@ -185,6 +198,7 @@ def current_user(
         self,
         optional: bool = False,
         scope: Optional[List[str]] = None,
+        acr: Optional[FiefACR] = None,
         permissions: Optional[List[str]] = None,
         refresh: bool = False,
     ):
@@ -199,6 +213,9 @@ def current_user(
         an unauthorized response will be raised.
         :param scope: Optional list of scopes required.
         If the access token lacks one of the required scope, a forbidden response will be raised.
+        :param acr: Optional minimum ACR level required.
+        If the access token doesn't meet the minimum level, a forbidden response will be raised.
+        Read more: https://docs.fief.dev/going-further/acr/
         :param permissions: Optional list of permissions required.
         If the access token lacks one of the required permission, a forbidden response will be raised.
         :param refresh: If `True`, the user information will be refreshed from the Fief API.
@@ -215,7 +232,7 @@ async def get_current_user(
         ```
         """
         signature = self._get_current_user_call_signature(
-            self.authenticated(optional, scope, permissions)
+            self.authenticated(optional, scope, acr, permissions)
         )
 
         @with_signature(signature)

fief_client/integrations/flask.py

@@ -7,10 +7,12 @@
 
 from fief_client import (
     Fief,
+    FiefAccessTokenACRTooLow,
     FiefAccessTokenExpired,
     FiefAccessTokenInfo,
     FiefAccessTokenInvalid,
     FiefAccessTokenMissingScope,
+    FiefACR,
     FiefUserInfo,
 )
 from fief_client.client import FiefAccessTokenMissingPermission
@@ -47,7 +49,7 @@ class FiefAuthForbidden(FiefAuthError):
     Request forbidden error.
 
     This error is raised when using the `authenticated` or `current_user` decorator
-    but the access token doesn't match the list of scopes or permissions.
+    but the access token doesn't match the list of scopes, permissions or minimum ACR level.
 
     You should implement an `errorhandler` to define the behavior of your server when
     this happens.
@@ -166,6 +168,7 @@ def authenticated(
         *,
         optional: bool = False,
         scope: Optional[List[str]] = None,
+        acr: Optional[FiefACR] = None,
         permissions: Optional[List[str]] = None,
     ):
         """
@@ -178,6 +181,9 @@ def authenticated(
         a `FiefAuthUnauthorized` error will be raised.
         :param scope: Optional list of scopes required.
         If the access token lacks one of the required scope, a `FiefAuthForbidden` error will be raised.
+        :param acr: Optional minimum ACR level required.
+        If the access token doesn't meet the minimum level, a `FiefAuthForbidden` error will be raised.
+        Read more: https://docs.fief.dev/going-further/acr/
         :param permissions: Optional list of permissions required.
         If the access token lacks one of the required permission, a `FiefAuthForbidden` error will be raised.
 
@@ -203,7 +209,10 @@ def decorated_function(*args, **kwargs):
 
                 try:
                     info = self.client.validate_access_token(
-                        token, required_scope=scope, required_permissions=permissions
+                        token,
+                        required_scope=scope,
+                        required_acr=acr,
+                        required_permissions=permissions,
                     )
                 except (FiefAccessTokenInvalid, FiefAccessTokenExpired) as e:
                     if optional:
@@ -212,6 +221,7 @@ def decorated_function(*args, **kwargs):
                     raise FiefAuthUnauthorized() from e
                 except (
                     FiefAccessTokenMissingScope,
+                    FiefAccessTokenACRTooLow,
                     FiefAccessTokenMissingPermission,
                 ) as e:
                     raise FiefAuthForbidden() from e
@@ -229,6 +239,7 @@ def current_user(
         *,
         optional: bool = False,
         scope: Optional[List[str]] = None,
+        acr: Optional[FiefACR] = None,
         permissions: Optional[List[str]] = None,
         refresh: bool = False,
     ):
@@ -242,6 +253,9 @@ def current_user(
         a `FiefAuthUnauthorized` error will be raised.
         :param scope: Optional list of scopes required.
         If the access token lacks one of the required scope, a `FiefAuthForbidden` error will be raised.
+        :param acr: Optional minimum ACR level required.
+        If the access token doesn't meet the minimum level, a `FiefAuthForbidden` error will be raised.
+        Read more: https://docs.fief.dev/going-further/acr/
         :param permissions: Optional list of permissions required.
         If the access token lacks one of the required permission, a `FiefAuthForbidden` error will be raised.
         :param refresh: If `True`, the user information will be refreshed from the Fief API.
@@ -260,7 +274,9 @@ def get_current_user():
 
         def _current_user(f):
             @wraps(f)
-            @self.authenticated(optional=optional, scope=scope, permissions=permissions)
+            @self.authenticated(
+                optional=optional, scope=scope, acr=acr, permissions=permissions
+            )
             def decorated_function(*args, **kwargs):
                 access_token_info: Optional[FiefAccessTokenInfo] = g.access_token_info