临时凭证参考

当 Iceberg 客户端（Spark、Trino、PyIceberg 等）加载表或视图时，Polaris 可以配置为返回作用域受限的短期凭证，供客户端直接访问云存储。这些凭证以键值属性的形式包含在 Iceberg REST API 响应中（参见 Iceberg REST 规范中的 LoadTableResult 和 LoadViewResult）。

类型为 credential 的属性包含敏感信息，位于 API 响应的 credentials 映射中（不会被记录日志）；类型为 config 的属性包含非敏感配置，位于 config 映射中。

目前并没有标准规定临时凭证的通用属性名称。Polaris 所使用的名称与 Iceberg SDK 针对每种存储类型所期望的名称一致。本页记录了 Polaris 实际发出的属性名称，以便客户端开发者和运维人员诊断认证故障并了解客户端兼容性。

AWS S3

Polaris 会调用 AWS STS AssumeRole，并附加一条内联会话策略，将权限限定在调用方被授权执行的特定表位置和操作（读取、列出、写入）范围内。生成的临时凭证随后返回给客户端。

属性	类型	类别	说明
`s3.access-key-id`	`String`	credential	来自 STS 会话的 AWS 访问密钥 ID
`s3.secret-access-key`	`String`	credential	来自 STS 会话的 AWS 秘密访问密钥
`s3.session-token`	`String`	credential	来自 STS 会话的 AWS 会话令牌
`s3.session-token-expires-at-ms`	`String`	credential	会话令牌的过期时间，以自 Unix 纪元起的毫秒数表示
`s3.endpoint`	`String`	config	自定义 S3 端点 URL；面向 MinIO 或 Ozone 等 S3 兼容存储发出，原生 AWS S3 不会发出
`s3.path-style-access`	`Boolean`	config	需要使用路径风格寻址时设为 true；面向 S3 兼容存储发出，原生 AWS S3 不会发出
`client.region`	`String`	config	用于 S3 和 STS 请求的 AWS 区域
`client.refresh-credentials-endpoint`	`String`	config	客户端可在其中调用以在下发凭证过期前进行刷新的 Catalog 端点

Azure ADLS

Polaris 会生成一个用户委托 SAS 令牌，其作用范围限定于调用方有权访问的容器和路径前缀。Azure 将用户委托 SAS 令牌的最长有效期限制为七天。

属性	类型	类别	说明
`adls.sas-token.<account-host>`	`String`	credential	以完整存储 DNS 名称为键的 SAS 令牌（例如 `adls.sas-token.myaccount.dfs.core.windows.net`）；由 Spark 通过 Iceberg 的 ADLSFileIO 使用
`adls.sas-token.<account-name>`	`String`	credential	仅以存储账户名为键的 SAS 令牌（例如 `adls.sas-token.myaccount`）；由 Iceberg 1.7.x 客户端使用
`adls.sas-token`	`String`	credential	不带后缀的原始 SAS 令牌；由 PyIceberg 通过 adlfs/fsspec 使用
`adls.account-name`	`String`	credential	存储账户名；由 PyIceberg 通过 adlfs/fsspec 使用
`adls.refresh-credentials-endpoint`	`String`	config	客户端可在分发的凭据过期前调用以刷新凭据的目录端点
`adls.sas-token-expires-at-ms.<account-host>`	`Long`	credential	以完整存储 DNS 名称为键的 SAS 令牌的过期时间，以 Unix 纪元以来的毫秒数表示

📝 注意

带后缀的键形式（adls.sas-token.<account-host> 和 adls.sas-token.<account-name>）始终携带相同的 SAS 令牌。Polaris 会同时发出所有形式，以便不同的客户端都能找到各自预期的键，而无需进行任何针对特定客户端的配置。

Google Cloud Storage (GCS)

Polaris 通过 Google 的凭据访问边界（Credential Access Boundary）机制获取范围缩减的 OAuth2 访问令牌。该令牌的作用域限定为调用方获授权访问的特定 GCS 存储桶和路径前缀，并支持可选的服务账户模拟。

属性	类型	类别	说明
`gcs.oauth2.token`	`String`	credential	降域（downscoped）OAuth2 访问令牌
`gcs.oauth2.token-expires-at`	`String`	credential	访问令牌的过期时间，以自 Unix 纪元起的毫秒数表示
`gcs.oauth2.refresh-credentials-endpoint`	`String`	config	客户端可调用的 Catalog 端点，用于在下发凭据过期前刷新凭据

凭据刷新

当客户端在加载或创建表的请求中将 X-Iceberg-Access-Delegation 头设置为 vended-credentials 来请求下发凭据时，Polaris 还会在上述属性列表中返回一个凭据刷新端点 URL（每种存储类型一个）。支持 Iceberg REST 凭据刷新协议的 Iceberg 客户端可以调用该端点，在当前凭据过期前获取新凭据，从而避免重新加载表。

客户端兼容性概要

下表汇总了常见客户端所需的属性形式，具体取决于各客户端所使用的 Iceberg SDK。

客户端	存储类型	所需属性
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（通过 `adlfs` / `fsspec`）	ADLS / Blob	`adls.sas-token`、`adls.account-name`
Apache Spark / PyIceberg	GCS	`gcs.oauth2.token`

Polaris 会同时输出所有适用的形式，因此在上述客户端之间切换时，无需进行任何针对特定客户端的 Polaris 配置。

预分配凭据参考