docs: expand update_connection_auth sample header for Snowflake keypair (#1844)

* feat: add sample for converting connection auth to Snowflake keypair

Adds samples/update_connection_to_keypair.py demonstrating how to
convert an existing Tableau Cloud datasource or workbook connection
from username/password to Snowflake keypair authentication using the
REST API v3.27 flow. Documents the prerequisite that the private key
must first be saved under Site Settings -> Saved Credentials for Data
Sources on the site.

Refs #1602

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

* Tighten embed_password comment and note flow-connection version

The prior comment said embed_password=True "tells the server to use the
pre-saved credential" which was vague. Server code (RestApiAppService
updateConnectionImpl -> embedOAuthUserKeychainConnections) looks up the
credential by (dbClass, username, role, auth) and binds it to the
connection; without that pre-saved match, the update still writes
'auth-keypair' into metadata but subsequent extract refreshes fail.
Spell that out so a copy-paste reader knows what "pre-saved" actually
requires.

Also add a note that flow connections gained the same capability in
REST API v3.28 (datasources and workbook connections were v3.27).

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

* Fold keypair sample into existing update_connection_auth

update_connection_auth.py already covers exactly this workflow (change
a connection's auth_type + credentials via the update-connection
endpoint). The prior keypair-specific sample added no new code path --
only Snowflake-keypair context that belongs in the shared sample's
header.

Delete the dedicated keypair sample; expand update_connection_auth's
header comment to list common authentication_type values (including
auth-keypair) and to spell out the pre-saved-credential prerequisite
that applies to any embed_password=True conversion.

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

* docs(samples): fix wire values, add security callout, add workbook REST ref

Round-1 review of update_connection_auth.py header caught three real
inaccuracies and one missing security note:

- "Username Password" was not the wire value; it's "UsernamePassword"
  (confirmed against test/assets/datasource_connections_update_no_auth.xml,
  test/assets/workbook_update_connections_no_auth.xml, and the
  UsernamePassword assertions in test_datasource.py and test_workbook.py).
- "oauth" had no grep-able backing as an authentication_type wire value
  on this endpoint. Dropped.
- "sqlserver" is a connection type (type=), not an authentication_type
  wire value. Dropped.
- v3.27 (datasource/workbook) and v3.28 (flow) version claim had no
  code backing -- @api decorators on update_connection are 2.3 for
  datasource/workbook and 3.3 for flow. Dropped rather than restating.
- Added a SECURITY callout: datasource_password is a positional CLI
  argument, so private-key material passed there leaks to shell
  history, ps output, and audit logs.
- Added the workbooks_and_views REST reference alongside the
  data-sources one; this sample updates both.
- Softened the credential lookup-key description ("attributes
  including..." instead of asserting a specific tuple).

Docs-only. samples/update_connection_auth.py parses cleanly.

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

* Correct authentication_type wire values in the sample header

The prior list included "UsernamePassword" (one word) as a canonical
value. Grepping the monolith source of truth shows that string is
not a valid authentication_type -- it does not appear in
codegen/constants.data, in the connection.authentication values that
Tableau Desktop writes into .tds/.twb, or in the REST reference docs.
It is only present in TSC's hand-authored test fixtures, where it
survives round-trip tests because TSC doesn't validate the string --
so a sample-user who copies it and posts to a real server hits an
unhelpful rejection.

Replaced with the actual documented set from codegen/constants.data
and the public REST reference:

  - auth-user-pass      (canonical username+password)
  - username-password   (SAP HANA / Sybase ASE / NetWeaver / Denodo / Salesforce)
  - auth-keypair        (Snowflake keypair)
  - oauth
  - auth-none
  - AD Service Principal
  - Azure AD Password

TSC's `UsernamePassword` test fixtures are a separate follow-up --
they don't break tests, but they steer future readers wrong.

---------

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

Author: jacalata

samples/update_connection_auth.py

@@ -1,3 +1,41 @@
+####
+# This script updates a single connection on a datasource or workbook to embed
+# credentials. It's a generic authentication-change helper: the same code path
+# works whether you're setting username+password or moving a Snowflake
+# connection to keypair auth.
+#
+# Common authentication_type values (case-sensitive wire values):
+#   - "auth-user-pass"         -- username + password (canonical)
+#   - "username-password"      -- alternate spelling used by some connectors
+#                                 (SAP HANA, SAP Sybase ASE, SAP NetWeaver BW,
+#                                 Denodo, Salesforce)
+#   - "auth-keypair"           -- Snowflake keypair (see prerequisite below)
+#   - "oauth"                  -- OAuth
+#   - "auth-none"              -- no auth on the connection
+#   - "AD Service Principal"   -- Azure AD Service Principal
+#   - "Azure AD Password"      -- Azure AD username/password
+# For the full list including connector-specific values, see the REST reference
+# link below or query an existing connection to observe its wire value.
+#
+# SECURITY: datasource_password is a positional CLI argument. For keypair auth
+# it carries the private-key material, which will leak into shell history, ps
+# output, and audit logs on the machine running this script. Prefer supplying
+# the key via an environment variable or stdin, or adapt this sample to read
+# the key from a file that is protected by filesystem permissions.
+#
+# When embed_password=True the server binds the connection to a matching
+# pre-saved credential on the site (looked up by attributes including username
+# and connection class). For keypair-auth conversions this means the Snowflake
+# private key MUST already be saved on the site under Site Settings -> Saved
+# Credentials for Data Sources before running this script. If not, the update
+# writes the new auth type into metadata but subsequent extract refreshes and
+# connection tests fail because no bound credential is found.
+#
+# See:
+#   https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_data_sources.htm#update_data_source_connection
+#   https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#update_workbook_connection
+####
+
 import argparse
 import logging
 import tableauserverclient as TSC