source-zendesk-support-native: switch to RotatingOAuth2Credentials for OAuth authentication

Zendesk will start expiring access tokens on 30SEP2025, so the connector
needs to support rotating access & refresh tokens with the
`RotatingOAuth2Credentials` class instead of
`LongLivedClientCredentialsOAuth2Credentials` that's currently used.

We have existing users that have authenticated with OAuth already, so
the connector needs to support both type of OAuth credentials internally
but only show the `RotatingOAuth2Credentials` option in the UI. This
will let existing users' tasks to continue working until they can
re-authenticate with the new OAuth option.

Once all existing users have re-authenticated & migrated off of the
deprecated OAuth option, we can remove support for it from the connector.

Author: Alex-Bair

source-zendesk-support-native/source_zendesk_support_native/models.py

@@ -7,7 +7,8 @@
     BasicAuth,
     BaseDocument,
     LongLivedClientCredentialsOAuth2Credentials,
-    OAuth2Spec,
+    RotatingOAuth2Credentials,
+    OAuth2RotatingTokenSpec,
     ResourceConfig,
     ResourceState,
 )
@@ -28,6 +29,11 @@
 # lowercase letter, and only contain lowercase letters, digits, or dashes.
 SUBDOMAIN_REGEX = r"^[a-z][a-z0-9-]{2,62}$"
 
+# Zendesk supports variable access token durations, between 5 minutes to 2 days.
+# To reduce how frequently we need to perform token rotations, we use the
+# largest possible access token duration.
+MAX_VALID_ACCESS_TOKEN_DURATION = int(timedelta(days=2).total_seconds())
+
 def urlencode_field(field: str):
     return "{{#urlencode}}{{{ " + field + " }}}{{/urlencode}}"
 
@@ -37,11 +43,11 @@ def urlencode_field(field: str):
     "client_id": "{{{ client_id }}}",
     "client_secret": "{{{ client_secret }}}",
     "redirect_uri": "{{{ redirect_uri }}}",
-    "scope": "read"
+    "scope": "read",
+    "expires_in": MAX_VALID_ACCESS_TOKEN_DURATION,
 }
 
-
-OAUTH2_SPEC = OAuth2Spec(
+OAUTH2_SPEC = OAuth2RotatingTokenSpec(
     provider="zendesk",
     accessTokenBody=json.dumps(accessTokenBody),
     authUrlTemplate=(
@@ -55,17 +61,35 @@ def urlencode_field(field: str):
     accessTokenUrlTemplate=("https://{{{ config.subdomain }}}.zendesk.com/oauth/tokens"),
     accessTokenResponseMap={
         "access_token": "/access_token",
+        "refresh_token": "/refresh_token",
+        "access_token_expires_at": r"{{#now_plus}}{{ expires_in }}{{/now_plus}}",
     },
     accessTokenHeaders={
         "Content-Type": "application/json",
     },
+    additionalTokenExchangeBody={
+        "expires_in": MAX_VALID_ACCESS_TOKEN_DURATION,
+    },
 )
 
+# Mustache templates in accessTokenUrlTemplate are not interpolated within the connector, so update_oauth_spec reassigns it for use within the connector.
+def update_oauth_spec(subdomain: str):
+    OAUTH2_SPEC.accessTokenUrlTemplate = f"https://{subdomain}.zendesk.com/oauth/tokens"
+
 
 if TYPE_CHECKING:
-    OAuth2Credentials = LongLivedClientCredentialsOAuth2Credentials
+    OAuth2Credentials = RotatingOAuth2Credentials
+    DeprecatedOAuthCredentials = LongLivedClientCredentialsOAuth2Credentials
 else:
-    OAuth2Credentials = LongLivedClientCredentialsOAuth2Credentials.for_provider(OAUTH2_SPEC.provider)
+    OAuth2Credentials = RotatingOAuth2Credentials.for_provider(OAUTH2_SPEC.provider)
+
+    class DeprecatedOAuthCredentials(
+        LongLivedClientCredentialsOAuth2Credentials.for_provider(OAUTH2_SPEC.provider)  # type: ignore
+    ):
+        credentials_title: Literal["Deprecated OAuth Credentials"] = Field(
+            default="Deprecated OAuth Credentials",
+            json_schema_extra={"type": "string"},
+        )
 
 
 class ApiToken(BasicAuth):
@@ -99,7 +123,7 @@ class EndpointConfig(BaseModel):
         default_factory=default_start_date,
         ge=EPOCH,
     )
-    credentials: OAuth2Credentials | ApiToken = Field(
+    credentials: OAuth2Credentials | ApiToken | DeprecatedOAuthCredentials = Field(
         discriminator="credentials_title",
         title="Authentication",
     )
@@ -119,6 +143,38 @@ class Advanced(BaseModel):
         json_schema_extra={"advanced": True},
     )
 
+    # Zendesk is updating their OAuth to expire access tokens, meaning this connector
+    # will need to use RotatingOAuth2Credentials instead of DeprecatedOAuthCredentials.
+    # During the migration period where both types of OAuth credentials are valid, we'll
+    # show the RotatingOAuth2Credentials option as the _only_ OAuth option in the UI &
+    # we'll hide the DeprecatedOAuthCredentials option. This lets existing
+    # captures continue working until users re-authenticate their tasks with the
+    # RotatingOAuth2Credentials option.
+    #
+    # Patching model_json_schema to remove DeprecatedOAuthCredentials makes
+    # RotatingOAuth2Credentials the only OAuth authentication option in the UI, and effectively
+    # "hides" the deprecated OAuth option. This is a bit gross, but it should only be needed for
+    # a little bit until all users that authenticated with OAuth have re-authenticated.
+    @classmethod
+    def model_json_schema(cls, *args, **kwargs) -> dict:
+        schema = super().model_json_schema(*args, **kwargs)
+
+        creds = schema.get("properties", {}).get("credentials", {})
+        one_of = creds.get("oneOf", [])
+        filtered_one_of = []
+
+        for option in one_of:
+            if "$ref" in option:
+                ref = option["$ref"]
+                def_name = ref.split("/")[-1]
+                # Do not include DeprecatedOAuthCredentials as an authentication option.
+                if "DeprecatedOAuthCredentials" in def_name:
+                    continue
+
+            filtered_one_of.append(option)
+
+        creds["oneOf"] = filtered_one_of
+        return schema
 
 ConnectorState = GenericConnectorState[ResourceState]
 

source-zendesk-support-native/source_zendesk_support_native/resources.py

@@ -36,6 +36,7 @@
     OAUTH2_SPEC,
     TICKET_CHILD_RESOURCES,
     POST_CHILD_RESOURCES,
+    update_oauth_spec,
 )
 from .api import (
     backfill_audit_logs,
@@ -846,6 +847,7 @@ def open(
 async def all_resources(
     log: Logger, http: HTTPMixin, config: EndpointConfig
 ) -> list[common.Resource]:
+    update_oauth_spec(config.subdomain)
     http.token_source = TokenSource(oauth_spec=OAUTH2_SPEC, credentials=config.credentials)
 
     resources = [

source-zendesk-support-native/tests/snapshots/snapshots__spec__capture.stdout.json

@@ -42,6 +42,39 @@
           "title": "ApiToken",
           "type": "object"
         },
+        "DeprecatedOAuthCredentials": {
+          "properties": {
+            "credentials_title": {
+              "const": "Deprecated OAuth Credentials",
+              "default": "Deprecated OAuth Credentials",
+              "title": "Credentials Title",
+              "type": "string"
+            },
+            "client_id": {
+              "secret": true,
+              "title": "Client Id",
+              "type": "string"
+            },
+            "client_secret": {
+              "secret": true,
+              "title": "Client Secret",
+              "type": "string"
+            },
+            "access_token": {
+              "secret": true,
+              "title": "Access Token",
+              "type": "string"
+            }
+          },
+          "required": [
+            "client_id",
+            "client_secret",
+            "access_token"
+          ],
+          "title": "OAuth",
+          "type": "object",
+          "x-oauth2-provider": "zendesk"
+        },
         "_OAuth2Credentials": {
           "properties": {
             "credentials_title": {
@@ -60,16 +93,28 @@
               "title": "Client Secret",
               "type": "string"
             },
+            "refresh_token": {
+              "secret": true,
+              "title": "Refresh Token",
+              "type": "string"
+            },
             "access_token": {
               "secret": true,
               "title": "Access Token",
               "type": "string"
+            },
+            "access_token_expires_at": {
+              "format": "date-time",
+              "title": "Access token expiration time.",
+              "type": "string"
             }
           },
           "required": [
             "client_id",
             "client_secret",
-            "access_token"
+            "refresh_token",
+            "access_token",
+            "access_token_expires_at"
           ],
           "title": "OAuth",
           "type": "object",
@@ -92,6 +137,7 @@
         "credentials": {
           "discriminator": {
             "mapping": {
+              "Deprecated OAuth Credentials": "#/$defs/DeprecatedOAuthCredentials",
               "Email & API Token": "#/$defs/ApiToken",
               "OAuth Credentials": "#/$defs/_OAuth2Credentials"
             },
@@ -161,12 +207,14 @@
       "provider": "zendesk",
       "authUrlTemplate": "https://{{{ config.subdomain }}}.zendesk.com/oauth/authorizations/new?response_type=code&client_id={{#urlencode}}{{{ client_id }}}{{/urlencode}}&redirect_uri={{#urlencode}}{{{ redirect_uri }}}{{/urlencode}}&scope=read&state={{#urlencode}}{{{ state }}}{{/urlencode}}",
       "accessTokenUrlTemplate": "https://{{{ config.subdomain }}}.zendesk.com/oauth/tokens",
-      "accessTokenBody": "{\"grant_type\": \"authorization_code\", \"code\": \"{{{ code }}}\", \"client_id\": \"{{{ client_id }}}\", \"client_secret\": \"{{{ client_secret }}}\", \"redirect_uri\": \"{{{ redirect_uri }}}\", \"scope\": \"read\"}",
+      "accessTokenBody": "{\"grant_type\": \"authorization_code\", \"code\": \"{{{ code }}}\", \"client_id\": \"{{{ client_id }}}\", \"client_secret\": \"{{{ client_secret }}}\", \"redirect_uri\": \"{{{ redirect_uri }}}\", \"scope\": \"read\", \"expires_in\": 172800}",
       "accessTokenHeaders": {
         "Content-Type": "application/json"
       },
       "accessTokenResponseMap": {
-        "access_token": "/access_token"
+        "access_token": "/access_token",
+        "access_token_expires_at": "{{#now_plus}}{{ expires_in }}{{/now_plus}}",
+        "refresh_token": "/refresh_token"
       }
     },
     "resourcePathPointers": [