This is an automated email from the ASF dual-hosted git repository.
roryqi pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/gravitino.git
The following commit(s) were added to refs/heads/main by this push:
new 89c9088f19 [#11092][#10899] docs: Add OAuth2 token refresh guidance
(#11079)
89c9088f19 is described below
commit 89c9088f19c720ce25f06b5825dae4bc49d16be9
Author: MaSai <[email protected]>
AuthorDate: Thu May 21 17:49:07 2026 +0800
[#11092][#10899] docs: Add OAuth2 token refresh guidance (#11079)
### What changes were proposed in this pull request?
This PR adds OAuth 2.0 token refresh guidance to
`docs/iceberg-rest-service.md` for Gravitino Iceberg REST clients. The
documentation explains the relevant Apache Iceberg 1.11.0+ OAuth 2.0
behavior and adds engine-specific guidance for Spark, Flink, and Trino,
including how to disable token exchange and the Trino version and
catalog settings required for better compatibility.
### Why are the changes needed?
Users may hit OAuth 2.0 token refresh and token exchange issues when
connecting query engines to the Gravitino Iceberg REST Catalog. This
update makes the behavior and required configuration clearer, especially
for Trino scenarios that can surface unsupported `grant_type` refresh
errors.
Fixes #11092
Fixes #10899
### Does this PR introduce _any_ user-facing change?
Yes. The Iceberg REST service documentation now includes OAuth 2.0 token
refresh guidance and engine-specific configuration recommendations for
Spark, Flink, and Trino.
### How was this patch tested?
Documentation update only.
---
docs/iceberg-rest-service.md | 40 ++++++++++++++++++++++++++++++++++++++++
1 file changed, 40 insertions(+)
diff --git a/docs/iceberg-rest-service.md b/docs/iceberg-rest-service.md
index d1da579c27..c89b927e71 100644
--- a/docs/iceberg-rest-service.md
+++ b/docs/iceberg-rest-service.md
@@ -321,6 +321,46 @@ Please refer the following configuration If you are using
Spark to access Iceber
--conf
spark.sql.catalog.rest.oauth2-server-uri=http://localhost:8177/oauth2/token
```
+##### OAuth 2.0 token refresh for Iceberg REST clients
+
+OAuth 2.0 token refresh challenges may arise in certain query engines when
accessing the Gravitino Iceberg REST Catalog (IRC).
+These are often linked to identity providers without full token exchange
support, or to authentication models in which child sessions inherit the
expiration policies of their parent sessions.
+
+The following Apache Iceberg change is relevant to this behavior:
+
+| Version | Change
|
+|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Iceberg 1.11.0+ | Supports disabling token exchange, renewing tokens with
client credentials, and ensuring that child `AuthSession` instances use their
own expiration instead of inheriting the parent session expiration. |
+
+###### Apache Iceberg OAuth 2.0 configuration
+
+**Spark**
+
+Set the following catalog property to disable token exchange:
+
+```text
+spark.sql.catalog.${catalog_name}.token-exchange-enabled=false
+```
+
+**Flink**
+
+Set the following catalog property to disable token exchange:
+
+```sql
+ 'token-exchange-enable' = 'false'
+```
+
+**Trino**
+
+Use Trino 479 or later, and set the following properties in the catalog
configuration:
+
+```properties
+iceberg.rest-catalog.session=NONE
+iceberg.rest-catalog.oauth2.token-exchange-enabled=false
+```
+
+You can omit `iceberg.rest-catalog.session=NONE` because `NONE` is the default
value.
+
#### HTTPS
Please refer to [HTTPS
Configuration](./security/how-to-use-https/#apache-iceberg-rest-services-configuration)
for how to enable HTTPS for Gravitino Iceberg REST server.
