Rotate a secret

How-to guideApplies to: Unified engine deployments

Replace an OAuth client secret while keeping the credential and catalog names used by queries.

Arrange the remote rotation

Use an existing Polaris catalog with a retail warehouse and the SF1 item table in namespace tpcds_sf1. Replace the example URLs, client ID, warehouse, namespace, and Region with your values. The Polaris client needs access to the warehouse and table. These examples request PRINCIPAL_ROLE:ALL; use the scope granted to your client. For the final SELECT, Polaris must supply usable temporary S3 credentials for the table. Otherwise attach a separate storage credential as shown in Separate catalog and storage credentials. A successful login or table listing alone does not prove S3 access. Obtain the current client secret and a replacement from the identity provider. SQL does not create or revoke Polaris client secrets. Where supported, keep the old secret active until a query succeeds using the replacement.

Establish the existing connection

CREATE SECRET recipe_rotating_secret AS '<current-client-secret>';

CREATE CREDENTIAL recipe_rotating_oauth USING oauth2
OPTIONS (
  'authentication' = 'client_credentials',
  'client_id' = '<client-id>',
  'token_endpoint' = 'https://polaris.example.com/api/catalog/v1/oauth/tokens'
)
SECRETS ('client_secret' = 'recipe_rotating_secret');

CREATE CATALOG recipe_rotating_retail USING `iceberg-rest`
OPTIONS (
  'catalog.type' = 'polaris',
  'uri' = 'https://polaris.example.com/api/catalog',
  'warehouse' = 'retail',
  'auth.type' = 'oauth2',
  'oauth2-server-uri' = 'https://polaris.example.com/api/catalog/v1/oauth/tokens',
  'scope' = 'PRINCIPAL_ROLE:ALL',
  's3.region' = 'us-east-2',
  's3.endpoint' = 'https://s3.us-east-2.amazonaws.com',
  's3.allow-http' = 'false'
)
CREDENTIALS (
  'auth' = 'recipe_rotating_oauth'
);

SELECT i_item_sk, i_item_id
FROM recipe_rotating_retail.tpcds_sf1.item
ORDER BY i_item_sk
LIMIT 5;

Replace the value and check a fresh query

ALTER SECRET recipe_rotating_secret SET VALUE '<replacement-client-secret>';
DESCRIBE SECRET recipe_rotating_secret;

SELECT i_item_sk, i_item_id
FROM recipe_rotating_retail.tpcds_sf1.item
ORDER BY i_item_sk
LIMIT 5;

The credential resolves the replacement value when it acquires fresh access. The credential and catalog names stay unchanged. Already running work can retain access tokens acquired before the change. Revoke the old remote client secret through its identity provider once you have confirmed the replacement works. For an external secret, update its remote value outside SQL. If the local reference pins a version, also change its version. When finished:

DROP CATALOG recipe_rotating_retail;
DROP CREDENTIAL recipe_rotating_oauth;
DROP SECRET recipe_rotating_secret;

Transformation Engine

Learn Laminar

Workloads

SQL reference

HTTP API

Recipes

Operations

Arrange the remote rotation

Establish the existing connection

Replace the value and check a fresh query

​Arrange the remote rotation

​Establish the existing connection

​Replace the value and check a fresh query

Arrange the remote rotation

Establish the existing connection

Replace the value and check a fresh query