feat: add Workload Identity Federation (WIF) support to connection update (#1887)

* @W-24145082 - Add WIF workgroupAuthMode and authFederationServiceAccount to connection update

The Tableau REST API's update-connection endpoints for workbooks and
datasources (REST API 3.30+) accept two new XML attributes on
<connection> payloads for Workload Identity Federation:

- workgroupAuthMode: "workload-identity-federation" (direct, e.g. Snowflake)
  or "workload-identity-federation-impersonation" (impersonation, e.g.
  BigQuery)
- authFederationServiceAccount: service account email, required for
  impersonation only

Expose both as string properties on ConnectionItem and emit them from
RequestFactory.Connection.update_req (the shared builder used by
workbooks, datasources, and flows for both single and bulk variants).

Also expose two constants on the public API:
WORKGROUP_AUTH_MODE_WIF, WORKGROUP_AUTH_MODE_WIF_IMPERSONATION.

Tests cover direct and impersonation variants against workbook and
datasource update-connection endpoints.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: apply black formatting

Collapse auth_federation_service_account assignment onto a single line
per the project's 120-char limit.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: add CHANGELOG entry for WIF connection update

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix: use googlebigquery and add WIF response attrs in test assets

Address review on #1887: datasource WIF asset was carrying the legacy
"bigquery" connector class, and both WIF assets referenced a 404
schemaLocation URL. Switch the datasource asset to the current
"googlebigquery" class, drop the broken schemaLocation reference, and
populate both WIF response assets with workgroupAuthMode (and
authFederationServiceAccount where impersonation applies) so the new
from_response coverage actually exercises WIF parsing.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat: nest WIF value set under ConnectionItem and extend to bulk and flows

Address review on #1887:

* Replace the two module-level WORKGROUP_AUTH_MODE_WIF* constants with
  a nested value set at ConnectionItem.WorkgroupAuthMode (WIF /
  WIF_IMPERSONATION) and drop the top-level reexports from
  tableauserverclient and tableauserverclient.models. The nested class
  carries the usage rules (resend on every update, no service account
  with direct mode, auth_type unset or "oauth", server echo caveat).
* Extend the two bulk endpoints to really support WIF:
  workbooks.update_connections and datasources.update_connections now
  accept workgroup_auth_mode and auth_federation_service_account
  keyword arguments, and both Workbook.update_connections_req and
  Datasource.update_connections_req builders emit them on the shared
  <connection> payload applied to every connection LUID.
* Document on flows.update_connection that WIF fields on the
  ConnectionItem reach the endpoint via the shared Connection.update_req
  builder and that server-side handling on flow connections may differ
  from workbook / datasource endpoints.
* Rewrite the WIF test suite to cover: parametrized direct and
  impersonation happy paths, OAuth to WIF switch, cleared-fields non
  emission, service-account-without-mode permissive emit,
  from_response WIF parsing, from_response absent (older servers), and
  bulk WIF forwarding. Add a flow WIF test exercising the shared
  builder reach.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: expand WIF guidance in CHANGELOG

Address review on #1887: expand the Unreleased CHANGELOG entry to name
the new nested value set (ConnectionItem.WorkgroupAuthMode.WIF /
WIF_IMPERSONATION), note that the bulk workbooks.update_connections
and datasources.update_connections endpoints now accept the matching
keyword arguments, add flows.update_connection to the list of
endpoints that forward WIF, state the usage rules (resend on every
update, no service account with direct mode, auth_type unset or
"oauth", server does not echo on GET today), and clarify that "3.30+"
is a Tableau Server REST API version (26.3 server release) and that
older servers silently ignore unknown connection attributes.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: sushmasreedharan-tableau

CHANGELOG.md

@@ -1,6 +1,38 @@
 
 ## Unreleased
 
+* Added Workload Identity Federation (WIF) support to the connection update
+  endpoints. `ConnectionItem` has two new string properties,
+  `workgroup_auth_mode` and `auth_federation_service_account`, that are
+  emitted on the `<connection>` payload by `workbooks.update_connection`,
+  `workbooks.update_connections`, `datasources.update_connection`,
+  `datasources.update_connections`, and `flows.update_connection`. The two
+  bulk endpoints also accept matching `workgroup_auth_mode` and
+  `auth_federation_service_account` keyword arguments and apply them to
+  every connection LUID in the request. Set `workgroup_auth_mode` to one of
+  the values on the new nested value set
+  `ConnectionItem.WorkgroupAuthMode`:
+  - `ConnectionItem.WorkgroupAuthMode.WIF` =
+    `"workload-identity-federation"` — direct WIF, e.g. Snowflake
+  - `ConnectionItem.WorkgroupAuthMode.WIF_IMPERSONATION` =
+    `"workload-identity-federation-impersonation"` — impersonation WIF,
+    e.g. Google BigQuery
+  Usage rules:
+  - Resend `workgroup_auth_mode` on every subsequent update of a WIF
+    connection; omitting it on a later update returns HTTP 400.
+  - Leave `auth_type` unset (or `"oauth"`) when sending a WIF mode; the
+    server derives the stored auth type from the mode.
+  - Set `auth_federation_service_account` only with `WIF_IMPERSONATION`.
+    The server rejects a service account with the direct `WIF` mode. TSC
+    does not validate this combination client-side.
+  - The server does not echo these attributes on GET responses today, so
+    `ConnectionItem.workgroup_auth_mode` and
+    `ConnectionItem.auth_federation_service_account` parsed from a response
+    will typically be `None` even when the connection is WIF-configured.
+  Requires Tableau Server REST API 3.30+ (Tableau Server release 26.3) with
+  WIF configured and enabled on the site. Older servers silently ignore
+  unknown connection attributes, so these fields are safe to leave unset on
+  pre-3.30 targets.
 * Bumped the urllib3 floor to 2.6.3 to pick up the fix for CVE-2026-21441
   (GHSA-38jv-5279-wg99, 8.9 High): urllib3's streaming decompression
   safeguards were bypassed when HTTP redirects were followed. TSC's manual

tableauserverclient/models/connection_item.py

@@ -50,8 +50,50 @@ class ConnectionItem:
 
     database_name: str
         The name of the database for the connection.
+
+    workgroup_auth_mode: str
+        Workload Identity Federation (WIF) auth mode. Set to one of the
+        values on ``ConnectionItem.WorkgroupAuthMode`` to switch an existing
+        connection to WIF on an update. Requires Tableau Server 26.3 / REST
+        API 3.30+ with WIF configured and enabled on the site. See the
+        ``WorkgroupAuthMode`` nested class for usage notes. The server does
+        not echo this attribute on GET responses today, so values parsed
+        from a response are typically ``None``.
+
+    auth_federation_service_account: str
+        Service-account email required by the server for the
+        ``WorkgroupAuthMode.WIF_IMPERSONATION`` mode (e.g. Google BigQuery)
+        and rejected for the direct ``WorkgroupAuthMode.WIF`` mode (e.g.
+        Snowflake). Also requires REST API 3.30+. Not echoed on GET today,
+        so typically ``None`` when parsed from a response.
     """
 
+    class WorkgroupAuthMode:
+        """
+        Workload Identity Federation (WIF) auth-mode values for
+        :attr:`ConnectionItem.workgroup_auth_mode`.
+
+        Requires Tableau Server 26.3 / REST API 3.30+ with WIF configured
+        and enabled on the site. Older servers silently ignore unknown
+        connection attributes, so emitting these against an older server is
+        a no-op rather than an error.
+
+        Usage notes:
+
+        - Send ``workgroup_auth_mode`` on every subsequent update of a WIF
+          connection. Once a connection has been switched to WIF, omitting
+          the attribute on a later update returns HTTP 400.
+        - Leave :attr:`ConnectionItem.auth_type` unset (or ``"oauth"``) when
+          sending a WIF mode; the server derives the stored auth type from
+          the mode.
+        - Do not set :attr:`ConnectionItem.auth_federation_service_account`
+          with the direct ``WIF`` mode (the server rejects it). Set it only
+          with ``WIF_IMPERSONATION``.
+        """
+
+        WIF = "workload-identity-federation"
+        WIF_IMPERSONATION = "workload-identity-federation-impersonation"
+
     def __init__(self):
         self._datasource_id: str | None = None
         self._datasource_name: str | None = None
@@ -66,6 +108,8 @@ def __init__(self):
         self._query_tagging: bool | None = None
         self._auth_type: str | None = None
         self._database_name: str | None = None
+        self._workgroup_auth_mode: str | None = None
+        self._auth_federation_service_account: str | None = None
 
     @property
     def datasource_id(self) -> str | None:
@@ -106,6 +150,22 @@ def auth_type(self) -> str | None:
     def auth_type(self, value: str | None):
         self._auth_type = value
 
+    @property
+    def workgroup_auth_mode(self) -> str | None:
+        return self._workgroup_auth_mode
+
+    @workgroup_auth_mode.setter
+    def workgroup_auth_mode(self, value: str | None):
+        self._workgroup_auth_mode = value
+
+    @property
+    def auth_federation_service_account(self) -> str | None:
+        return self._auth_federation_service_account
+
+    @auth_federation_service_account.setter
+    def auth_federation_service_account(self, value: str | None):
+        self._auth_federation_service_account = value
+
     @property
     def database_name(self) -> str | None:
         return self._database_name
@@ -136,6 +196,8 @@ def from_response(cls, resp, ns) -> list["ConnectionItem"]:
                 string_to_bool(s) if (s := connection_xml.get("queryTagging", None)) else None
             )
             connection_item._auth_type = connection_xml.get("authenticationType", None)
+            connection_item._workgroup_auth_mode = connection_xml.get("workgroupAuthMode", None)
+            connection_item._auth_federation_service_account = connection_xml.get("authFederationServiceAccount", None)
             # The REST API GET /connections response uses "dbName" for the database
             # name attribute.  This is different from the publish request body, which
             # uses "databaseName" (see _add_connections_element in request_factory.py).

tableauserverclient/server/endpoint/datasources_endpoint.py

@@ -396,6 +396,8 @@ def update_connections(
         username: str | None = None,
         password: str | None = None,
         embed_password: bool | None = None,
+        workgroup_auth_mode: str | None = None,
+        auth_federation_service_account: str | None = None,
     ) -> list[ConnectionItem]:
         """
         Bulk updates one or more datasource connections by LUID.
@@ -424,6 +426,20 @@ def update_connections(
         embed_password : bool, optional
             Whether to embed the password.
 
+        workgroup_auth_mode : str, optional
+            Workload Identity Federation (WIF) auth mode. See
+            ``ConnectionItem.WorkgroupAuthMode`` for allowed values and
+            usage notes. Applied to every connection LUID in this call.
+            Requires Tableau Server REST API 3.30+ with WIF configured on
+            the site.
+
+        auth_federation_service_account : str, optional
+            Service-account email for WIF impersonation. Required with
+            ``ConnectionItem.WorkgroupAuthMode.WIF_IMPERSONATION`` and
+            rejected by the server with the direct
+            ``ConnectionItem.WorkgroupAuthMode.WIF`` mode. TSC does not
+            validate the combination client-side.
+
         Returns
         -------
         Iterable of str
@@ -438,6 +454,8 @@ def update_connections(
             username=username,
             password=password,
             embed_password=embed_password,
+            workgroup_auth_mode=workgroup_auth_mode,
+            auth_federation_service_account=auth_federation_service_account,
         )
         server_response = self.put_request(url, request_body)
         connection_items = ConnectionItem.from_response(server_response.content, self.parent_srv.namespace)

tableauserverclient/server/endpoint/flows_endpoint.py

@@ -264,6 +264,16 @@ def update_connection(self, flow_item: FlowItem, connection_item: ConnectionItem
 
         REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_flow.htm#update_flow_connection
 
+        Setting ``connection_item.workgroup_auth_mode`` and
+        ``connection_item.auth_federation_service_account`` (see
+        ``ConnectionItem.WorkgroupAuthMode``) will forward the Workload
+        Identity Federation attributes to this endpoint via the shared
+        ``RequestFactory.Connection.update_req`` builder. Server-side
+        handling of these attributes on flow connections is governed by
+        the flow endpoint and may differ from the workbook / datasource
+        endpoints — review the REST reference for flow-specific semantics
+        before relying on it in production.
+
         Parameters
         ----------
         flow_item: FlowItem

tableauserverclient/server/endpoint/workbooks_endpoint.py

@@ -343,6 +343,8 @@ def update_connections(
         username: str | None = None,
         password: str | None = None,
         embed_password: bool | None = None,
+        workgroup_auth_mode: str | None = None,
+        auth_federation_service_account: str | None = None,
     ) -> list[ConnectionItem]:
         """
         Bulk updates one or more workbook connections by LUID.
@@ -371,6 +373,20 @@ def update_connections(
         embed_password : bool, optional
             Whether to embed the password.
 
+        workgroup_auth_mode : str, optional
+            Workload Identity Federation (WIF) auth mode. See
+            ``ConnectionItem.WorkgroupAuthMode`` for allowed values and
+            usage notes. Applied to every connection LUID in this call.
+            Requires Tableau Server REST API 3.30+ with WIF configured on
+            the site.
+
+        auth_federation_service_account : str, optional
+            Service-account email for WIF impersonation. Required with
+            ``ConnectionItem.WorkgroupAuthMode.WIF_IMPERSONATION`` and
+            rejected by the server with the direct
+            ``ConnectionItem.WorkgroupAuthMode.WIF`` mode. TSC does not
+            validate the combination client-side.
+
         Returns
         -------
         Iterable of str
@@ -385,6 +401,8 @@ def update_connections(
             username=username,
             password=password,
             embed_password=embed_password,
+            workgroup_auth_mode=workgroup_auth_mode,
+            auth_federation_service_account=auth_federation_service_account,
         )
 
         # Send request

tableauserverclient/server/request_factory.py

@@ -257,6 +257,8 @@ def update_connections_req(
         username: str | None = None,
         password: str | None = None,
         embed_password: bool | None = None,
+        workgroup_auth_mode: str | None = None,
+        auth_federation_service_account: str | None = None,
     ):
         conn_luids_elem = ET.SubElement(element, "connectionLUIDs")
         for luid in connection_luids:
@@ -275,6 +277,12 @@ def update_connections_req(
         if embed_password is not None:
             connection_elem.set("embedPassword", str(embed_password).lower())
 
+        if workgroup_auth_mode is not None:
+            connection_elem.set("workgroupAuthMode", workgroup_auth_mode)
+
+        if auth_federation_service_account is not None:
+            connection_elem.set("authFederationServiceAccount", auth_federation_service_account)
+
 
 class DQWRequest:
     def add_req(self, dqw_item):
@@ -1184,6 +1192,8 @@ def update_connections_req(
         username: str | None = None,
         password: str | None = None,
         embed_password: bool | None = None,
+        workgroup_auth_mode: str | None = None,
+        auth_federation_service_account: str | None = None,
     ):
         conn_luids_elem = ET.SubElement(element, "connectionLUIDs")
         for luid in connection_luids:
@@ -1202,6 +1212,12 @@ def update_connections_req(
         if embed_password is not None:
             connection_elem.set("embedPassword", str(embed_password).lower())
 
+        if workgroup_auth_mode is not None:
+            connection_elem.set("workgroupAuthMode", workgroup_auth_mode)
+
+        if auth_federation_service_account is not None:
+            connection_elem.set("authFederationServiceAccount", auth_federation_service_account)
+
 
 class Connection:
     @_tsrequest_wrapped
@@ -1226,6 +1242,10 @@ def update_req(self, xml_request: ET.Element, connection_item: "ConnectionItem")
             connection_element.attrib["embedPassword"] = str(connection_item.embed_password).lower()
         if connection_item.query_tagging is not None:
             connection_element.attrib["queryTaggingEnabled"] = str(connection_item.query_tagging).lower()
+        if connection_item.workgroup_auth_mode is not None:
+            connection_element.attrib["workgroupAuthMode"] = connection_item.workgroup_auth_mode
+        if connection_item.auth_federation_service_account is not None:
+            connection_element.attrib["authFederationServiceAccount"] = connection_item.auth_federation_service_account
 
 
 class TaskRequest:

test/assets/datasource_update_connection_wif.xml

@@ -0,0 +1,4 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+    <connection id="be786ae0-d2bf-4a4b-9b34-e2de8d2d4488" type="googlebigquery" serverAddress="www.googleapis.com/bigquery/v2" userName="user@example.com" embedPassword="false" authenticationType="oauth" workgroupAuthMode="workload-identity-federation-impersonation" authFederationServiceAccount="sa@proj.iam.gserviceaccount.com"/>
+</tsResponse>

test/assets/workbook_update_connection_wif.xml

@@ -0,0 +1,4 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+    <connection id="17376070-64d1-4d17-acb4-a56e4b5b1768" type="snowflake" serverAddress="account.snowflakecomputing.com" userName="" embedPassword="false" queryTaggingEnabled="false" authenticationType="oauth" workgroupAuthMode="workload-identity-federation"/>
+</tsResponse>