KnowForgeVended Credentials Reference
师成· 更新于 2026-09-29· 阅读 14 分钟· 0 次阅读Vended Credentials Reference
When an Iceberg client (Spark, Trino, PyIceberg, etc.) loads a table or view, Polaris can be configured to return short-lived, scoped credentials that the client uses to access cloud storage directly. These credentials are returned as key-value properties in the Iceberg REST API response (see LoadTableResult and LoadViewResult in the Iceberg REST spec).
Properties with kind credential carry sensitive material and are returned in the credentials map of the API response (never logged). Properties with kind config carry non-sensitive configuration and are returned in the config map.
There is no standard that defines common property names for vended credentials. The names Polaris uses match what the Iceberg SDK expects for each storage type. This page documents the exact property names Polaris emits so that client authors and operators can diagnose authentication failures and understand client compatibility.
AWS S3
Polaris calls AWS STS AssumeRole with an inline session policy scoped to the specific table locations and operations (read, list, write) the caller is authorized to perform. The resulting temporary credentials are returned to the client.
| Property | Type | Kind | Description |
|---|---|---|---|
s3.access-key-id | String | credential | AWS access key ID from the STS session |
s3.secret-access-key | String | credential | AWS secret access key from the STS session |
s3.session-token | String | credential | AWS session token from the STS session |
s3.session-token-expires-at-ms | String | credential | Expiration time of the session token, in milliseconds since the Unix epoch |
s3.endpoint | String | config | Custom S3 endpoint URL; emitted for S3-compatible stores such as MinIO or Ozone, absent for native AWS S3 |
s3.path-style-access | Boolean | config | Set to true when path-style addressing is required; emitted for S3-compatible stores, absent for native AWS S3 |
client.region | String | config | AWS region to use for S3 and STS requests |
client.refresh-credentials-endpoint | String | config | Catalog endpoint the client can call to refresh vended credentials before they expire |
Azure ADLS
Polaris generates a User Delegation SAS token scoped to the container and path prefix the caller is authorized to access. Azure limits the maximum validity of a User Delegation SAS token to seven days.
| Property | Type | Kind | Description |
|---|---|---|---|
adls.sas-token.<account-host> | String | credential | SAS token keyed by the full storage DNS name (e.g. adls.sas-token.myaccount.dfs.core.windows.net); consumed by Spark via Iceberg’s ADLSFileIO |
adls.sas-token.<account-name> | String | credential | SAS token keyed by the storage account name only (e.g. adls.sas-token.myaccount); consumed by Iceberg 1.7.x clients |
adls.sas-token | String | credential | Bare SAS token (no suffix); consumed by PyIceberg via adlfs/fsspec |
adls.account-name | String | credential | Storage account name; consumed by PyIceberg via adlfs/fsspec |
adls.refresh-credentials-endpoint | String | config | Catalog endpoint the client can call to refresh vended credentials before they expire |
adls.sas-token-expires-at-ms.<account-host> | Long | credential | Expiration time of the SAS token keyed by the full storage DNS name, in milliseconds since the Unix epoch |
📝 Note
The suffixed key forms (adls.sas-token.<account-host> and adls.sas-token.<account-name>) always carry the same SAS token. Polaris emits all forms simultaneously so that different clients can each find the key they expect without any client-specific configuration.
Google Cloud Storage (GCS)
Polaris obtains a downscoped OAuth2 access token via Google’s Credential Access Boundary mechanism. The token is scoped to the specific GCS buckets and path prefixes the caller is authorized to access and supports optional service account impersonation.
| Property | Type | Kind | Description |
|---|---|---|---|
gcs.oauth2.token | String | credential | Downscoped OAuth2 access token |
gcs.oauth2.token-expires-at | String | credential | Expiration time of the access token, in milliseconds since the Unix epoch |
gcs.oauth2.refresh-credentials-endpoint | String | config | Catalog endpoint the client can call to refresh vended credentials before they expire |
Credential refresh
When a client requests vended credentials by setting the X-Iceberg-Access-Delegation header to vended-credentials on a table load or create request, Polaris also returns a credential-refresh endpoint URL in the properties listed above (one per storage type). Iceberg clients that support the Iceberg REST credential-refresh protocol can call this endpoint to obtain fresh credentials before the current ones expire, avoiding the need to re-load the table.
Client compatibility summary
The table below summarizes which property forms are required by common clients, based on the Iceberg SDK each client uses.
| Client | Storage type | Required properties |
|---|---|---|
| Apache Spark (Iceberg ≥ 1.8) | S3 | s3.access-key-id, s3.secret-access-key, s3.session-token |
| Apache Spark (Iceberg ≥ 1.8) | ADLS / Blob | adls.sas-token.<account-host> |
| Apache Spark (Iceberg 1.7.x) | ADLS / Blob | adls.sas-token.<account-name> |
PyIceberg (via adlfs / fsspec) | ADLS / Blob | adls.sas-token, adls.account-name |
| Apache Spark / PyIceberg | GCS | gcs.oauth2.token |
Polaris emits all applicable forms simultaneously, so no client-specific Polaris configuration is required to switch between the clients listed above.
评论
登录后参与评论