[MINOR] docs: Add OAuth2 token refresh guidance by lasdf1234 · Pull Request #11079 · apache/gravitino

lasdf1234 · 2026-05-14T01:36:42Z

What changes were proposed in this pull request?

Add OAuth 2.0 token refresh guidance to docs/security/how-to-authenticate.md, including Iceberg 1.11.0+ behavior, Spark/Flink token exchange settings, Trino catalog settings, and an alternative Dremio auth manager section for Spark and Flink.

Why are the changes needed?

Users need clear guidance for handling OAuth 2.0 token refresh and token exchange behavior when connecting engines to Gravitino Iceberg REST Catalog.

Fixes #11092

Does this PR introduce any user-facing change?

Yes. Documentation now includes OAuth 2.0 token refresh guidance for Spark, Flink, and Trino.

How was this patch tested?

Documentation update only.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

danhuawang · 2026-05-14T02:56:00Z

+
+| Version | Change |
+| --- | --- |
+| Iceberg 1.11.0+ | Supports disabling token exchange and using client credentials for token renewal, and fixes child `AuthSession` expiration handling so the child session uses its own token lifetime. |


Do the gravitino IRC upgrade to the 1.11.0? If gravitino IRC is still 1.10, can we clarify it here?

No need. This parameter takes effect on the client side.

danhuawang · 2026-05-14T03:00:40Z

+spark.executor.extraClassPath=${SPARK_HOME}/jars/authmgr-oauth2-runtime-<version>.jar
+```
+
+Example Spark configuration using client credentials token refresh:


I think we also add an example for spark.sql.catalog.remote_irc_b.rest.auth.oauth2.grant-type password, this type make more sense.

Got spark and flink have both added usage examples

danhuawang · 2026-05-14T03:02:45Z

+spark.sql.catalog.irc=org.apache.iceberg.spark.SparkCatalog
+spark.sql.catalog.irc.type=rest
+spark.sql.catalog.irc.uri=http://localhost:9001/iceberg/
+spark.sql.catalog.irc.warehouse=<catalog_name>


Is spark.sql.catalog.gravitino_irc_b_mysql_backend.prefix <catalog_name> required?

Got, this configuration is not related to the main theme of this document.I have removed this config.

danhuawang · 2026-05-14T03:07:21Z


+#### OAuth 2.0 token refresh for Iceberg REST clients
+
+When Gravitino is used as an Iceberg REST Catalog (IRC), some query engines may hit OAuth 2.0 token refresh issues during long-running sessions.


during long-running sessions, if the token expiration time is 5s , then it happens in short time. So propose remove long-running .

Got I already revised the document.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

roryqi

You should add the document to iceberg-rest-service.md instead of security.md.

roryqi · 2026-05-14T09:39:26Z

+For the native Apache Iceberg OAuth 2.0 implementation, the following upstream improvement is relevant:
+
+| Version | Change |
+| --- | --- |


Could u fix the format?

Got resolved

roryqi · 2026-05-14T09:41:21Z

+
+##### Alternative OAuth 2.0 auth manager
+
+If the native Apache Iceberg OAuth 2.0 implementation does not meet your requirements, you can use the Dremio Iceberg OAuth 2.0 auth manager.


I can't get your point. When will we need to use Dremio library?

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

roryqi · 2026-05-14T09:56:27Z

+
+##### Alternative Dremio Iceberg OAuth 2.0 auth manager
+
+If version of iceberg on the client side can't be upgraded, you can use the Dremio Iceberg OAuth 2.0 auth manager as an alternative.


Iceberg library is usually compatible. I don't think this is a good reason.

The content of Dermio has been deleted.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

yuqi1129 · 2026-05-14T09:37:10Z

+For the native Apache Iceberg OAuth 2.0 implementation, the following upstream improvement is relevant:
+
+| Version | Change |
+| --- | --- |


Format the table.

Got resolved

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

roryqi · 2026-05-14T10:49:04Z

+|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Iceberg 1.11.0+ | Supports disabling token exchange, using client credentials for token renewal, and fixing child `AuthSession` expiration handling so that child sessions use their own token lifetime. |
+
+###### Native Apache Iceberg OAuth 2.0 implementation


Could u remove native?

Got resolved

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-05-14T11:02:08Z

Code Coverage Report

Overall Project	66.07%	🟢
Files changed	No Java source files changed	-

Module	Coverage
aliyun	1.72%	🔴
api	47.13%	🟢
authorization-common	85.96%	🟢
aws	1.08%	🔴
azure	2.47%	🔴
catalog-common	10.2%	🔴
catalog-fileset	80.02%	🟢
catalog-glue	83.41%	🟢
catalog-hive	81.83%	🟢
catalog-jdbc-clickhouse	79.18%	🟢
catalog-jdbc-common	43.93%	🟢
catalog-jdbc-doris	80.28%	🟢
catalog-jdbc-hologres	54.03%	🟢
catalog-jdbc-mysql	79.23%	🟢
catalog-jdbc-oceanbase	78.38%	🟢
catalog-jdbc-postgresql	82.05%	🟢
catalog-jdbc-starrocks	78.27%	🟢
catalog-kafka	77.01%	🟢
catalog-lakehouse-generic	45.14%	🟢
catalog-lakehouse-hudi	79.1%	🟢
catalog-lakehouse-iceberg	86.98%	🟢
catalog-lakehouse-paimon	76.85%	🟢
catalog-model	77.72%	🟢
cli	44.51%	🟢
client-java	77.96%	🟢
common	50.0%	🟢
core	82.29%	🟢
filesystem-hadoop3	76.97%	🟢
flink	0.0%	🔴
flink-common	43.17%	🟢
flink-runtime	0.0%	🔴
gcp	14.12%	🔴
hadoop-common	10.39%	🔴
hive-metastore-common	46.83%	🟢
iceberg-common	55.46%	🟢
iceberg-rest-server	69.61%	🟢
idp-basic	94.68%	🟢
integration-test-common	0.0%	🔴
jobs	66.17%	🟢
lance-common	19.95%	🔴
lance-rest-server	62.78%	🟢
lineage	53.02%	🟢
optimizer	82.95%	🟢
optimizer-api	21.95%	🔴
server	85.83%	🟢
server-common	71.23%	🟢
spark	32.79%	🔴
spark-common	39.09%	🔴
trino-connector	35.14%	🔴

roryqi · 2026-05-14T11:16:04Z

+Some query engines may encounter OAuth 2.0 token refresh issues when connecting to Gravitino as an Iceberg REST Catalog (IRC).
+This usually occurs when the identity provider does not support token exchange, or when a child authentication session inherits the parent session's expiration time.
+
+For the native Apache Iceberg OAuth 2.0 implementation, the following upstream improvement is relevant:


roryqi · 2026-05-14T11:16:26Z

+##### OAuth 2.0 token refresh for Iceberg REST clients
+
+Some query engines may encounter OAuth 2.0 token refresh issues when connecting to Gravitino as an Iceberg REST Catalog (IRC).
+This usually occurs when the identity provider does not support token exchange, or when a child authentication session inherits the parent session's expiration time.


It usually occurs.

Got resolved

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

roryqi

LGTM.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

[MINOR] docs: Add OAuth2 token refresh guidance

78ebee6

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings May 14, 2026 01:36

[MINOR] docs: Clarify Trino OAuth2 config

0c453ca

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

danhuawang reviewed May 14, 2026

View reviewed changes

lasdf1234 and others added 4 commits May 14, 2026 17:01

[MINOR] docs: address OAuth2 review comments

ebec6b3

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

[MINOR] docs: remove Iceberg version note

30303ed

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

[MINOR] docs: refine OAuth2 wording

944a9bc

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

[MINOR] docs: reorganize Dremio auth manager section

3910b94

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

roryqi reviewed May 14, 2026

View reviewed changes

lasdf1234 and others added 2 commits May 14, 2026 17:48

[MINOR] docs: address Rory review comments

f084e12

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

[MINOR] docs: tweak Dremio alternative wording

ac417e1

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

roryqi reviewed May 14, 2026

View reviewed changes

[MINOR] docs: tweak Trino fallback wording

7957553

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

yuqi1129 reviewed May 14, 2026

View reviewed changes

lasdf1234 and others added 4 commits May 14, 2026 18:06

[MINOR] docs: align OAuth2 table formatting

492a660

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

[MINOR] docs: revert OAuth2 table alignment

3fbfd77

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Modify format

e66b8be

Modify format

5f72d9d

roryqi reviewed May 14, 2026

View reviewed changes

[MINOR] docs: simplify Iceberg REST OAuth2 section title

4a11a8e

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

roryqi reviewed May 14, 2026

View reviewed changes

lasdf1234 and others added 5 commits May 14, 2026 19:19

[MINOR] docs: polish Iceberg REST OAuth2 wording

ff4d373

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

[MINOR] docs: refine Iceberg REST OAuth2 prose

40a6466

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

[MINOR] docs: revise OAuth2 intro paragraph

b5464f4

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

[MINOR] docs: make OAuth2 guidance more explanatory

b2f53f1

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

[MINOR] docs: rewrite Iceberg REST OAuth2 section

636e1cf

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

lasdf1234 and others added 2 commits May 14, 2026 20:53

[MINOR] docs: align OAuth2 config style

70456da

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

[MINOR] docs: update Flink OAuth2 example

d4c8fc9

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

roryqi previously approved these changes May 14, 2026

View reviewed changes

[MINOR] docs: replace Flink credential example

c364f5d

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

lasdf1234 dismissed roryqi’s stale review via c364f5d May 14, 2026 13:22


		#### OAuth 2.0 token refresh for Iceberg REST clients

		When Gravitino is used as an Iceberg REST Catalog (IRC), some query engines may hit OAuth 2.0 token refresh issues during long-running sessions.


		##### Alternative OAuth 2.0 auth manager

		If the native Apache Iceberg OAuth 2.0 implementation does not meet your requirements, you can use the Dremio Iceberg OAuth 2.0 auth manager.


		##### Alternative Dremio Iceberg OAuth 2.0 auth manager

		If version of iceberg on the client side can't be upgraded, you can use the Dremio Iceberg OAuth 2.0 auth manager as an alternative.

Conversation

lasdf1234 commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changes were proposed in this pull request?

Why are the changes needed?

Does this PR introduce any user-facing change?

How was this patch tested?

Uh oh!

danhuawang May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

danhuawang May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

roryqi left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Coverage Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

roryqi left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

lasdf1234 commented May 14, 2026 •

edited

Loading

danhuawang May 14, 2026 •

edited

Loading

danhuawang May 14, 2026 •

edited

Loading

github-actions Bot commented May 14, 2026 •

edited

Loading