Iceberg REST Catalog Overview #3 — OAuth Authentication

Free Copy of Apache Iceberg: The Definitive Guide

Free Apache Iceberg Course

2025 Apache Iceberg Architecture Guide

Ultimate Iceberg Resource Guide

Security is critical to any modern data platform, and Apache Iceberg is continuously evolving to enhance its authentication and authorization mechanisms. As part of this evolution, the OAuth2 token exchange endpoint (/v1/oauth/tokens) has been deprecated and is set for removal in future versions.

In this post, we will explore:

• The purpose of the /v1/oauth/tokens endpoint
• Why is it being deprecated
• Best practices for authentication in Iceberg catalogs as we advance

What Was the Purpose of /v1/oauth/tokens?

The /v1/oauth/tokens endpoint was designed to facilitate authentication by issuing OAuth2 access tokens using one of the following flows:

1. Client Credentials Flow — Exchanging a client ID and secret for an access token.
2. Token Exchange Flow (User Context) — Exchanging an identity token for a more specific access token.
3. Token Refresh Flow — Exchanging an expiring access token for a new one.

For example, an Iceberg catalog client could authenticate by:

• Sending client credentials to this endpoint to receive an access token.
• Using this token for subsequent catalog requests.
• Refreshing the token before it expires.

This approach provided centralized authentication but introduced security concerns, leading to deprecation.

Why Is It Being Deprecated?

The OAuth2 token endpoint is deprecated as of Iceberg (Java) 1.6.0 and will be removed entirely in Iceberg 2.0. The primary reasons for this decision include:

1. Security Risks — Hosting an OAuth2 token endpoint within an Iceberg catalog increases attack vectors for unauthorized access and token misuse.
2. Separation of Concerns — Authentication should be handled by a dedicated OAuth2 provider (e.g., AWS Cognito, Azure AD, Okta) rather than the catalog itself.
3. Improved Flexibility — Clients should be able to use external OAuth2 identity providers without depending on the Iceberg REST catalog for token management.

What Should You Do Instead?

Instead of relying on /v1/oauth/tokens, clients should:

? Use an external OAuth2 provider — Set the oauth2-server-uri configuration to specify the correct OAuth token endpoint managed by a dedicated identity provider.

? Authenticate before making API calls — Clients should obtain an access token before interacting with the Iceberg catalog, rather than requesting one from the catalog itself.

? Pass the access token via the Authorization header — Iceberg REST API requests should include the token in the request headers:

GET /v1/config HTTP/1.1  
Host: iceberg.catalog.com  
Authorization: Bearer <your-access-token>        

? Use secure storage for client credentials — Avoid hardcoding client IDs and secrets. Use environment variables, secrets managers, or OAuth libraries that handle credential exchange securely.

Key Takeaways

• The /v1/oauth/tokens endpoint is deprecated and will be removed in Iceberg 2.0.
• It was initially designed for client authentication and token exchange, but security concerns led to its deprecation.
• Clients should authenticate with an external OAuth2 provider and configure oauth2-server-uri instead of relying on this endpoint.
• Future Iceberg versions will not include built-in OAuth2 token exchange, requiring a shift to industry-standard authentication best practices.

What’s Next?

In the next post, we will explore how Iceberg handles namespace management, including how to create, list, and modify namespaces using the REST API. Stay tuned.