My proposal is intended basic authentication as an optional security
scheme for all the operations.
Agree with your point, basic authentication is less robust than SigV4
and Google Auth.
Basic authentication is also simple compared to other methods. It can
lower the barrier to use.
How about stating scheme is optional or mandatory in the description,
for example
BearerAuth:
description: This authentication method is mandatory for the server.
type: http
scheme: bearer
BasicAuth:
type: http
description: This authentication method is optional for the server.
scheme: basic
Similarly, we can add SigV4 and Google Auth as the optional
authentication method, too.
Alexandre Dutra <[email protected]> 于2026年4月7日周二 17:37写道：
>
> 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
