This section describes how Iceberg clients can authenticate with Foundry's Iceberg catalog. These steps are not required when using Iceberg within Foundry.
Foundry's Iceberg catalog implements the specification ↗ for Iceberg REST catalogs. This means that Iceberg clients that support REST catalogs can use the authentication mechanisms defined in the spec when interacting with Foundry's Iceberg catalog.
When configuring Iceberg clients, the following authentication options are available:
| Method | Description |
|---|---|
OAuth2 client credentials | Authenticate as a service user using a client ID and client secret. Once configured, the Iceberg client will perform any necessary token exchange. |
Bearer | Authenticate as a user using an API token (generally referred to as a bearer token). |
Clients should not be configured with credentials to cloud storage, for example, S3 or Azure Data Lake Storage (ADLS). Storage access is delegated by the Iceberg catalog using the mechanisms described in the spec ↗.
API tokens, also called Bearer Tokens, are the fastest way to authenticate and get started. You can generate an API token for your user by following the User-generated tokens documentation.
The following properties are required when configuring an Iceberg client with a bearer token:
| Key | Example | Required? | Description |
|---|---|---|---|
uri | https://<hostname>/iceberg | Yes | URI identifying the Foundry Iceberg catalog |
token | eyJwb... | Yes | Bearer token value to use for Authorization header |
The example below uses the Python Iceberg client (PyIceberg) and configures a catalog in a
~/.pyiceberg.yaml ↗.
The catalog properties are documented here ↗
and can be adapted for other Iceberg client implementations that support REST catalogs.
catalog:
foundry:
uri: https://your.foundry/iceberg
token: eyJwb...
These generated bearer tokens are long-lived and tied to your user. They should be handled with care. We recommend using OAuth2 for production usage and limiting token-based authentication to development.
You can use OAuth2 with Iceberg clients for increased security over directly providing an API bearer token. You will need to create a third-party OAuth2 application with the client credentials grant as documented here.
The Iceberg client is given the generated client credentials and a URL to the authorization server which exchanges client credentials for an application token. Iceberg clients handle this exchange and subsequent token refresh.
The following properties are used when configuring an Iceberg client for OAuth2:
| Key | Example | Required? | Description |
|---|---|---|---|
uri | https://<hostname>/iceberg | Yes | URI identifying the Foundry Iceberg catalog |
oauth2-server-uri | https://<hostname>/iceberg/v1/oauth/tokens | Yes | URI identifying the authorization server |
credential | client_id:client_secret | Yes | Credential to use for OAuth2 credential flow when initializing the catalog |
scope | api:iceberg-read api:iceberg-write | No | Space-separated scope to limit permissions |
With these properties, you can configure a PyIceberg catalog client for OAuth2 as shown below:
Copied!1 2 3 4 5 6catalog: default: uri: https://your.foundry/iceberg oauth2-server-uri: https://your.foundry/iceberg/v1/oauth/tokens # OAuth2 server URL credential: 17f...:037... # client_id:client_secret scope: api:iceberg-read api:iceberg-write # optional, space-separated scope
The scope configuration is optional. Permissions default to the permissions of the service user
created for the third-party application. You can limit scope to only allow reads by declaring
api:iceberg-read without api:iceberg-write.
Foundry uses an Iceberg-flavored authorization server and thus a different endpoint than the endpoint generally used for OAuth2 clients.