Update

Author: bgier-stytch

stytch/consumer/api/policy_cache.py

@@ -0,0 +1,31 @@
+from typing import Optional
+
+from stytch.consumer.api.rbac import RBAC
+from stytch.consumer.models.rbac import Policy
+from stytch.shared.lazy_cache import LazyCache
+
+DEFAULT_REFRESH_INTERVAL = 10 * 60  # 10 minutes
+
+
+class PolicyCache(LazyCache[Policy]):
+    def __init__(
+        self,
+        rbac: RBAC,
+        refresh_interval_seconds: int = DEFAULT_REFRESH_INTERVAL,
+    ) -> None:
+        self.rbac = rbac
+        super().__init__(
+            reload_func=self.reload_policy,
+            async_reload_func=self.reload_policy_async,
+            refresh_interval_seconds=refresh_interval_seconds,
+        )
+
+    def reload_policy(self, _: Optional[Policy]) -> Policy:
+        resp = self.rbac.policy()
+        assert resp.policy is not None
+        return resp.policy
+
+    async def reload_policy_async(self, _: Optional[Policy]) -> Policy:
+        resp = await self.rbac.policy_async()
+        assert resp.policy is not None
+        return resp.policy

stytch/consumer/api/sessions.py

@@ -298,7 +298,9 @@ def exchange_access_token(
         """Use this endpoint to exchange a Connected Apps Access Token back into a Stytch Session for the underlying User.
         This session can be used with the Stytch SDKs and APIs.
 
-        The Access Token must contain the `full_access` scope and must not be more than 5 minutes old. Access Tokens may only be exchanged a single time.
+        The Session returned will be the same Session that was active in your application (the authorizing party) during the initial authorization flow.
+
+        The Access Token must contain the `full_access` scope (only available to First Party clients) and must not be more than 5 minutes old. Access Tokens may only be exchanged a single time.
 
         Fields:
           - access_token: The access token to exchange for a Stytch Session. Must be granted the `full_access` scope.
@@ -337,7 +339,9 @@ async def exchange_access_token_async(
         """Use this endpoint to exchange a Connected Apps Access Token back into a Stytch Session for the underlying User.
         This session can be used with the Stytch SDKs and APIs.
 
-        The Access Token must contain the `full_access` scope and must not be more than 5 minutes old. Access Tokens may only be exchanged a single time.
+        The Session returned will be the same Session that was active in your application (the authorizing party) during the initial authorization flow.
+
+        The Access Token must contain the `full_access` scope (only available to First Party clients) and must not be more than 5 minutes old. Access Tokens may only be exchanged a single time.
 
         Fields:
           - access_token: The access token to exchange for a Stytch Session. Must be granted the `full_access` scope.
@@ -373,13 +377,13 @@ def get_jwks(
     ) -> GetJWKSResponse:
         """Get the JSON Web Key Set (JWKS) for a project.
 
-        JWKS are rotated every ~6 months. Upon rotation, new JWTs will be signed using the new key, and both keys will be returned by this endpoint for a period of 1 month.
+        Within the JWKS, the JSON Web Keys are rotated every ~6 months. Upon rotation, new JWTs will be signed using the new key, and both keys will be returned by this endpoint for a period of 1 month.
 
-        JWTs have a set lifetime of 5 minutes, so there will be a 5 minute period where some JWTs will be signed by the old JWKS, and some JWTs will be signed by the new JWKS. The correct JWKS to use for validation is determined by matching the `kid` value of the JWT and JWKS.
+        JWTs have a set lifetime of 5 minutes, so there will be a 5 minute period where some JWTs will be signed by the old keys, and some JWTs will be signed by the new keys. The correct key to use for validation is determined by matching the `kid` value of the JWT and key.
 
-        If you're using one of our [backend SDKs](https://stytch.com/docs/sdks), the JWKS rotation will be handled for you.
+        If you're using one of our [backend SDKs](https://stytch.com/docs/b2b/sdks), the JSON Web Key (JWK) rotation will be handled for you.
 
-        If you're using your own JWT validation library, many have built-in support for JWKS rotation, and you'll just need to supply this API endpoint. If not, your application should decide which JWKS to use for validation by inspecting the `kid` value.
+        If you're using your own JWT validation library, many have built-in support for JWK rotation, and you'll just need to supply this API endpoint. If not, your application should decide which JWK to use for validation by inspecting the `kid` value.
 
         See our [How to use Stytch Session JWTs](https://stytch.com/docs/guides/sessions/using-jwts) guide for more information.
 
@@ -401,13 +405,13 @@ async def get_jwks_async(
     ) -> GetJWKSResponse:
         """Get the JSON Web Key Set (JWKS) for a project.
 
-        JWKS are rotated every ~6 months. Upon rotation, new JWTs will be signed using the new key, and both keys will be returned by this endpoint for a period of 1 month.
+        Within the JWKS, the JSON Web Keys are rotated every ~6 months. Upon rotation, new JWTs will be signed using the new key, and both keys will be returned by this endpoint for a period of 1 month.
 
-        JWTs have a set lifetime of 5 minutes, so there will be a 5 minute period where some JWTs will be signed by the old JWKS, and some JWTs will be signed by the new JWKS. The correct JWKS to use for validation is determined by matching the `kid` value of the JWT and JWKS.
+        JWTs have a set lifetime of 5 minutes, so there will be a 5 minute period where some JWTs will be signed by the old keys, and some JWTs will be signed by the new keys. The correct key to use for validation is determined by matching the `kid` value of the JWT and key.
 
-        If you're using one of our [backend SDKs](https://stytch.com/docs/sdks), the JWKS rotation will be handled for you.
+        If you're using one of our [backend SDKs](https://stytch.com/docs/b2b/sdks), the JSON Web Key (JWK) rotation will be handled for you.
 
-        If you're using your own JWT validation library, many have built-in support for JWKS rotation, and you'll just need to supply this API endpoint. If not, your application should decide which JWKS to use for validation by inspecting the `kid` value.
+        If you're using your own JWT validation library, many have built-in support for JWK rotation, and you'll just need to supply this API endpoint. If not, your application should decide which JWK to use for validation by inspecting the `kid` value.
 
         See our [How to use Stytch Session JWTs](https://stytch.com/docs/guides/sessions/using-jwts) guide for more information.
 
@@ -432,6 +436,26 @@ def attest(
         session_token: Optional[str] = None,
         session_jwt: Optional[str] = None,
     ) -> AttestResponse:
+        """Exchange an auth token issued by a trusted identity provider for a Stytch session. You must first register a Trusted Auth Token profile in the Stytch dashboard [here](https://stytch.com/docs/dashboard/trusted-auth-tokens). If a session token or session JWT is provided, it will add the trusted auth token as an authentication factor to the existing session.
+
+        Fields:
+          - profile_id: The ID of the trusted auth token profile to use for attestation.
+          - token: The trusted auth token to authenticate.
+          - session_duration_minutes: Set the session lifetime to be this many minutes from now. This will start a new session if one doesn't already exist,
+          returning both an opaque `session_token` and `session_jwt` for this session. Remember that the `session_jwt` will have a fixed lifetime of
+          five minutes regardless of the underlying session duration, and will need to be refreshed over time.
+
+          This value must be a minimum of 5 and a maximum of 527040 minutes (366 days).
+
+          If a `session_token` or `session_jwt` is provided then a successful authentication will continue to extend the session this many minutes.
+
+          If the `session_duration_minutes` parameter is not specified, a Stytch session will not be created.
+          - session_custom_claims: Add a custom claims map to the Session being authenticated. Claims are only created if a Session is initialized by providing a value in `session_duration_minutes`. Claims will be included on the Session object and in the JWT. To update a key in an existing Session, supply a new value. To delete a key, supply a null value.
+
+          Custom claims made with reserved claims ("iss", "sub", "aud", "exp", "nbf", "iat", "jti") will be ignored. Total custom claims size cannot exceed four kilobytes.
+          - session_token: The `session_token` for the session that you wish to add the trusted auth token authentication factor to.
+          - session_jwt: The `session_jwt` for the session that you wish to add the trusted auth token authentication factor to.
+        """  # noqa
         headers: Dict[str, str] = {}
         data: Dict[str, Any] = {
             "profile_id": profile_id,
@@ -459,6 +483,26 @@ async def attest_async(
         session_token: Optional[str] = None,
         session_jwt: Optional[str] = None,
     ) -> AttestResponse:
+        """Exchange an auth token issued by a trusted identity provider for a Stytch session. You must first register a Trusted Auth Token profile in the Stytch dashboard [here](https://stytch.com/docs/dashboard/trusted-auth-tokens). If a session token or session JWT is provided, it will add the trusted auth token as an authentication factor to the existing session.
+
+        Fields:
+          - profile_id: The ID of the trusted auth token profile to use for attestation.
+          - token: The trusted auth token to authenticate.
+          - session_duration_minutes: Set the session lifetime to be this many minutes from now. This will start a new session if one doesn't already exist,
+          returning both an opaque `session_token` and `session_jwt` for this session. Remember that the `session_jwt` will have a fixed lifetime of
+          five minutes regardless of the underlying session duration, and will need to be refreshed over time.
+
+          This value must be a minimum of 5 and a maximum of 527040 minutes (366 days).
+
+          If a `session_token` or `session_jwt` is provided then a successful authentication will continue to extend the session this many minutes.
+
+          If the `session_duration_minutes` parameter is not specified, a Stytch session will not be created.
+          - session_custom_claims: Add a custom claims map to the Session being authenticated. Claims are only created if a Session is initialized by providing a value in `session_duration_minutes`. Claims will be included on the Session object and in the JWT. To update a key in an existing Session, supply a new value. To delete a key, supply a null value.
+
+          Custom claims made with reserved claims ("iss", "sub", "aud", "exp", "nbf", "iat", "jti") will be ignored. Total custom claims size cannot exceed four kilobytes.
+          - session_token: The `session_token` for the session that you wish to add the trusted auth token authentication factor to.
+          - session_jwt: The `session_jwt` for the session that you wish to add the trusted auth token authentication factor to.
+        """  # noqa
         headers: Dict[str, str] = {}
         data: Dict[str, Any] = {
             "profile_id": profile_id,
@@ -612,9 +656,9 @@ def authenticate_jwt_local(
         expires_at = claim.get("expires_at", generic_claims.reserved_claims["exp"])
 
         if authorization_check is not None:
-            rbac_local.perform_consumer_scope_authorization_check(
+            rbac_local.perform_consumer_authorization_check(
                 policy=self.policy_cache.get(),
-                subject_roles=generic_claims.roles_claim,
+                subject_roles=claim["roles"],
                 authorization_check=authorization_check,
             )
 

stytch/consumer/api/test/test_consumer_idp.py

@@ -4,7 +4,7 @@
 from unittest.mock import Mock, patch, MagicMock, AsyncMock
 from typing import Optional
 
-from stytch.b2b.models.rbac import (
+from stytch.consumer.models.rbac import (
     Policy,
     PolicyRole,
     PolicyRolePermission,

stytch/shared/rbac_local.py

@@ -69,6 +69,32 @@ def perform_authorization_check(
     # If we made it here, we didn't find a matching permission
     raise RBACPermissionError(authorization_check)
 
+def perform_consumer_authorization_check(
+    policy: ConsumerPolicy,
+    subject_roles: List[str],
+    authorization_check: ConsumerAuthorizationCheck,
+) -> None:
+    """Performs an authorization check against a policy and a set of roles. If the check
+    succeeds, this method will return. If the check fails, a PermissionError will be
+    raised.
+    """
+    for role in policy.roles:
+        if role.role_id in subject_roles:
+            for permission in role.permissions:
+                has_matching_action = (
+                    "*" in permission.actions
+                    or authorization_check.action in permission.actions
+                )
+                has_matching_resource = (
+                    authorization_check.resource_id == permission.resource_id
+                )
+                if has_matching_action and has_matching_resource:
+                    # All good, we found a matching permission
+                    return
+
+    # If we made it here, we didn't find a matching permission
+    raise RBACPermissionError(authorization_check)
+
 
 def perform_scope_authorization_check(
     policy: Policy,