Hi Rory,
Thanks for initiating this discussion!
> The update adds BasicAuth: [] to the global security schemes in the OpenAPI
> spec
I have some reservations regarding that change. Because the top-level
security array governs all operations, this modification defines
BasicAuth as a valid authentication method for *every endpoint in the
specification*.
Making Basic auth a global security scheme could be interpreted as a
requirement for servers to support it across all operations. The lack
of explicit RFC 2119 compliance language (MUST vs SHOULD) in OpenAPI
creates ambiguity for implementors. Furthermore, promoting Basic auth
feels like a regression compared to more robust methods like SigV4 or
OAuth2.
Consider the current implementations:
- Apache Polaris: Basic auth is restricted to the deprecated
/v1/oauth/tokens endpoint and is not accepted for standard catalog
operations like creating tables or listing namespaces.
- Apache Gravitino: while it appears to accept Basic auth globally via
SimpleAuthenticator, this authenticator reportedly does not validate
passwords, suggesting it is intended for development rather than
production.
If the intention is to permit Basic auth specifically for the
/v1/oauth/tokens endpoint, I recommend using an operation-level
override instead:
/v1/oauth/tokens:
post:
security:
- OAuth2: [catalog]
- BearerAuth: []
- BasicAuth: []
It is worth noting, however, that adding a new scheme to an endpoint
slated for removal in Iceberg 2.0 is somewhat unusual.
More generally, we should clarify the intended interpretation of these
security schemes. Explicitly stating which schemes are mandatory
versus optional would be beneficial. For example, SigV4 and Google
Auth are currently omitted, and the OAuth2 scheme contains
requirements—like the "catalog" scope—that some implementations (e.g.
Polaris) do not follow.
Thanks,
Alex
On Tue, Apr 7, 2026 at 5:19 AM roryqi <[email protected]> wrote:
>
> Hello everyone,
>
> I have opened a pull request (#15892) to add support for Basic Authentication
> to the OpenAPI specification for the Iceberg REST Catalog.
>
> Background & Purpose:
>
> The Iceberg RESTCatalog already supports Basic Auth in its implementation.
> This pull request aims to formally document that support within the project's
> OpenAPI specification (rest-catalog-open-api.yaml), ensuring the spec
> accurately reflects the available authentication mechanisms. This improves
> clarity for users and client implementers.
>
> Key Changes in the PR:
>
> The update adds BasicAuth: [] to the global security schemes in the OpenAPI
> spec, alongside the existing OAuth2 and BearerAuthschemes. A definition for
> the Basic Auth security scheme (type: http, scheme: basic) has also been
> added, consistent with OpenAPI 3.0 standards.
>
> Reference & Context:
>
> OpenAPI specification references:
>
> Bearer Authentication
> https://swagger.io/docs/specification/v3_0/authentication/bearer-authentication/
>
> Basic Authentication
> https://swagger.io/docs/specification/v3_0/authentication/basic-authentication/
>
> Iceberg RESTCatalog client already supports
>
> https://github.com/apache/iceberg/blob/main/core/src/main/java/org/apache/iceberg/rest/auth/BasicAuthManager.java
>
> IRC servers such as
>
> Apache Gravitino already supports this
>
> https://github.com/apache/gravitino/blob/main/server-common/src/main/java/org/apache/gravitino/server/authentication/SimpleAuthenticator.java
>
> Apache Polaris already supports this, too.
> https://github.com/apache/polaris/blob/main/runtime/service/src/main/java/org/apache/polaris/service/auth/internal/service/DefaultOAuth2ApiService.java#L84
>
>
> Request for Feedback:
>
> While this is a straightforward documentation update aligning the spec with
> existing functionality, I believe it's valuable to propose this change for
> broader community discussion. I would appreciate your thoughts on:
>
> The approach of adding Basic Auth to the global security schemes.
>
> Any potential considerations or alternative methods for documenting this
> authentication method.
>
> You can view the full pull request and conversation here:
>
> https://github.com/apache/iceberg/pull/15892
>
> Thank you for your time and feedback.
>
> Best regards,
>
> Rory
