Use OAuth client credentials

How-to guideApplies to: Unified engine deployments

Give the engine a client ID and a client-secret reference. It exchanges them for an access token when the catalog needs one. This recipe uses Polaris.

Prepare the OAuth client

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. Create the OAuth client and obtain its client secret outside SQL. Ensure the engine can reach both the token endpoint and catalog API over HTTPS. The local encrypted secret store must be available.

Create the OAuth credential

CREATE SECRET recipe_oauth_secret AS '<client-secret>';

CREATE CREDENTIAL recipe_oauth_auth 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_oauth_secret');

The secret is the client’s password, not an access token. The fixed token endpoint must match the endpoint configured by its consuming catalog.

Connect and read

CREATE CATALOG recipe_oauth_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_oauth_auth'
);

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

The catalog supplies the token scope for this connection. A credential can also have scopes, audience, and resource options when required by its token service. Acquired OAuth tokens can be renewed while the client secret and remote permissions remain valid. When finished:

DROP CATALOG recipe_oauth_retail;
DROP CREDENTIAL recipe_oauth_auth;
DROP SECRET recipe_oauth_secret;

Transformation Engine

Learn Laminar

Workloads

SQL reference

HTTP API

Recipes

Operations

Use OAuth client credentials

Prepare the OAuth client

Create the OAuth credential

Connect and read

​Prepare the OAuth client

​Create the OAuth credential

​Connect and read

Prepare the OAuth client

Create the OAuth credential

Connect and read