Merge pull request #1136 from sirosen/id-token-decoder

Implement JWTDecoder and IDTokenDecoder, use them to reimplement decoding and improve the behavior and customizability of GlobusApp

Author: sirosen

changelog.d/20250219_000456_sirosen_id_token_decoder.rst

@@ -0,0 +1,28 @@
+Added
+~~~~~
+
+- Introduce ``globus_sdk.IDTokenDecoder``, which implements ``id_token``
+  decoding. (:pr:`NUMBER`)
+
+  - For integration with ``GlobusApp``, a new builder protocol is defined,
+    ``IDTokenDecoderProvider``. This defines instantiation within the context
+    of an app.
+
+  - When ``OAuthTokenResponse.decode_id_token`` is called, it now internally
+    instantiates an ``IDTokenDecoder`` and uses it to perform the decode.
+
+  - ``IDTokenDecoder`` objects cache OpenID configuration data and JWKs
+    after looking them up. If a decoder is used multiple times, it will reuse
+    the cached data.
+
+  - Token storage constructs can now contain an ``IDTokenDecoder`` in their
+    ``id_token_decoder`` attribute. The decoder is used preferentially when
+    trying to read the ``sub`` field from an ``id_token`` to store.
+
+  - ``GlobusAppConfig`` can now contain ``id_token_decoder``, an
+    ``IDTokenDecoder`` or ``IDTokenDecoderProvider``.
+    The default is ``IDTokenDecoder``.
+
+  - ``GlobusApp`` initialization will now use the config's
+    ``id_token_decoder`` and attach the ``IDTokenDecoder`` to the
+    token storage which is used.

docs/authorization/globus_app/config.rst

@@ -36,3 +36,7 @@ Providers
     :members:
     :special-members: __call__
     :member-order: bysource
+
+.. autoclass:: IDTokenDecoderProvider()
+    :members: for_globus_app
+    :member-order: bysource

docs/services/auth.rst

@@ -52,6 +52,9 @@ batching, and other functionality.
    :exclude-members: __dict__,__weakref__
    :show-inheritance:
 
+.. autoclass:: IDTokenDecoder
+   :show-inheritance:
+
 .. autoclass:: DependentScopeSpec
 
 Auth Responses

src/globus_sdk/__init__.pyi

@@ -35,6 +35,7 @@ from .services.auth import (
     GetConsentsResponse,
     GetIdentitiesResponse,
     IdentityMap,
+    IDTokenDecoder,
     NativeAppAuthClient,
     OAuthAuthorizationCodeResponse,
     OAuthClientCredentialsResponse,
@@ -173,6 +174,7 @@ __all__ = (
     "OAuthDependentTokenResponse",
     "OAuthRefreshTokenResponse",
     "OAuthTokenResponse",
+    "IDTokenDecoder",
     "ComputeAPIError",
     "ComputeClient",
     "ComputeClientV2",

src/globus_sdk/globus_app/__init__.py

@@ -2,6 +2,7 @@
 from .client_app import ClientApp
 from .config import GlobusAppConfig
 from .protocols import (
+    IDTokenDecoderProvider,
     LoginFlowManagerProvider,
     TokenStorageProvider,
     TokenValidationErrorHandler,
@@ -14,6 +15,7 @@
     "ClientApp",
     "GlobusAppConfig",
     # Protocols
+    "IDTokenDecoderProvider",
     "TokenValidationErrorHandler",
     "TokenStorageProvider",
     "LoginFlowManagerProvider",

src/globus_sdk/globus_app/app.py

@@ -5,7 +5,13 @@
 import copy
 import typing as t
 
-from globus_sdk import AuthClient, AuthLoginClient, GlobusSDKUsageError, Scope
+from globus_sdk import (
+    AuthClient,
+    AuthLoginClient,
+    GlobusSDKUsageError,
+    IDTokenDecoder,
+    Scope,
+)
 from globus_sdk._types import ScopeCollectionType, UUIDLike
 from globus_sdk.authorizers import GlobusAuthorizer
 from globus_sdk.gare import GlobusAuthorizationParameters
@@ -97,6 +103,11 @@ def __init__(
             scope_requirements=self._scope_requirements,
         )
 
+        # setup an ID Token Decoder based on config; build one if it was not provided
+        self._id_token_decoder = self._initialize_id_token_decoder(
+            app_name=self.app_name, config=self.config, login_client=self._login_client
+        )
+
         # initialize our authorizer factory
         self._initialize_authorizer_factory()
         self._authorizer_factory_initialized = True
@@ -239,6 +250,34 @@ def _resolve_token_storage(
             f"TokenStorage, TokenStorageProvider, or a supported string value."
         )
 
+    def _initialize_id_token_decoder(
+        self, *, app_name: str, config: GlobusAppConfig, login_client: AuthLoginClient
+    ) -> IDTokenDecoder:
+        """
+        Create an IDTokenDecoder or use the one provided via config, and set it on
+        the token storage adapters.
+
+        It is only set on inner storage if the decoder was not already set, so a
+        non-null value won't be overwritten.
+
+        This must run near the end of app initialization, when the `_token_storage`
+        (inner) and `token_storage` (validating storage, outer) storages have both
+        been initialized.
+        """
+        if isinstance(self.config.id_token_decoder, IDTokenDecoder):
+            id_token_decoder: IDTokenDecoder = self.config.id_token_decoder
+        else:
+            id_token_decoder = self.config.id_token_decoder.for_globus_app(
+                app_name=app_name,
+                config=config,
+                login_client=login_client,
+            )
+        if self._token_storage.id_token_decoder is None:
+            self._token_storage.id_token_decoder = id_token_decoder
+        self.token_storage.id_token_decoder = id_token_decoder
+
+        return id_token_decoder
+
     @abc.abstractmethod
     def _initialize_authorizer_factory(self) -> None:
         """

src/globus_sdk/globus_app/config.py

@@ -3,6 +3,7 @@
 import dataclasses
 import typing as t
 
+import globus_sdk
 from globus_sdk.config import get_environment_name
 from globus_sdk.login_flows import (
     CommandLineLoginFlowManager,
@@ -19,6 +20,7 @@
 from globus_sdk.tokenstorage.v2.validating_token_storage import IdentityMismatchError
 
 from .protocols import (
+    IDTokenDecoderProvider,
     LoginFlowManagerProvider,
     TokenStorageProvider,
     TokenValidationErrorHandler,
@@ -101,6 +103,11 @@ class GlobusAppConfig:
         Default: ``resolve_by_login_flow`` (runs a login flow, storing the resulting
         tokens).
 
+    :ivar ``IDTokenDecoder`` | ``IDTokenDecoderProvider`` id_token_decoder:
+        An ID token decoder or a provider which produces a decoder. The decoder is used
+        when decoding ``id_token`` JWTs from Globus Auth.
+        Defaults to ``IDTokenDecoder``.
+
     :ivar str environment: The Globus environment of services to interact with. This is
         mostly used for testing purposes. This may additionally be set with the
         environment variable `GLOBUS_SDK_ENVIRONMENT`. Default: ``"production"``.
@@ -115,6 +122,9 @@ class GlobusAppConfig:
     token_validation_error_handler: TokenValidationErrorHandler | None = (
         resolve_by_login_flow
     )
+    id_token_decoder: globus_sdk.IDTokenDecoder | IDTokenDecoderProvider = (
+        globus_sdk.IDTokenDecoder
+    )
     environment: str = dataclasses.field(default_factory=get_environment_name)
 
 

src/globus_sdk/globus_app/protocols.py

@@ -2,22 +2,20 @@
 
 import typing as t
 
-from globus_sdk import AuthLoginClient
-from globus_sdk._types import UUIDLike
-from globus_sdk.login_flows import LoginFlowManager
-from globus_sdk.tokenstorage import TokenStorage
-
 if t.TYPE_CHECKING:
-    from globus_sdk.tokenstorage import TokenValidationError
+    from globus_sdk import AuthLoginClient, IDTokenDecoder
+    from globus_sdk._types import UUIDLike
+    from globus_sdk.login_flows import LoginFlowManager
+    from globus_sdk.tokenstorage import TokenStorage, TokenValidationError
 
     from .app import GlobusApp
     from .config import GlobusAppConfig
 
 
 @t.runtime_checkable
 class TokenStorageProvider(t.Protocol):
-    """
-    A protocol for a factory which can create ``TokenStorages``.
+    r"""
+    A protocol for a factory which can create ``TokenStorage``\s.
 
     SDK-provided :ref:`token_storages` support this protocol.
     """
@@ -43,8 +41,8 @@ def for_globus_app(
 
 @t.runtime_checkable
 class LoginFlowManagerProvider(t.Protocol):
-    """
-    A protocol for a factory which can create ``LoginFlowManagers``.
+    r"""
+    A protocol for a factory which can create ``LoginFlowManager``\s.
 
     SDK-provided :ref:`login_flow_managers` support this protocol.
     """
@@ -62,6 +60,32 @@ def for_globus_app(
         """
 
 
+@t.runtime_checkable
+class IDTokenDecoderProvider(t.Protocol):
+    r"""
+    A protocol for a factory which can create ``IDTokenDecoder``\s.
+
+    The SDK-provided ``IDTokenDecoder`` class supports this protocol.
+    """
+
+    @classmethod
+    def for_globus_app(
+        cls,
+        *,
+        app_name: str,
+        config: GlobusAppConfig,
+        login_client: AuthLoginClient,
+    ) -> IDTokenDecoder:
+        """
+        Create an ``IDTokenDecoder`` for use in a GlobusApp.
+
+        :param app_name: The name supplied to the GlobusApp.
+        :param config: The configuration supplied to the GlobusApp.
+        :param login_client: A login client to use for instantiating an
+            ``IDTokenDecoder``.
+        """
+
+
 class TokenValidationErrorHandler(t.Protocol):
     """
     A handler invoked when a :class:`TokenValidationError` is raised during a

src/globus_sdk/services/auth/__init__.py

@@ -10,6 +10,7 @@
     GlobusAuthorizationCodeFlowManager,
     GlobusNativeAppFlowManager,
 )
+from .id_token_decoder import IDTokenDecoder
 from .identity_map import IdentityMap
 from .response import (
     GetConsentsResponse,
@@ -32,6 +33,7 @@
     # high-level helpers
     "DependentScopeSpec",
     "IdentityMap",
+    "IDTokenDecoder",
     # flow managers
     "GlobusNativeAppFlowManager",
     "GlobusAuthorizationCodeFlowManager",