danhuawang opened a new issue, #11716: URL: https://github.com/apache/gravitino/issues/11716
### What would you like to be improved? There are three documentation gaps in the v2 Web UI OIDC setup, confirmed empirically on the OSS build (branch-1.3, 1.3.1-SNAPSHOT) with `oauth` authenticator (`JwksTokenValidator`), `authorization.enable = true`, and Keycloak. The primary page to correct is the security how-to-authenticate guide; a couple also belong on the Web UI v2 page. **Gap 1: Browser OIDC login requires a secure context (HTTPS or localhost)** Affected page: security / how-to-authenticate, Web UI section. The v2 UI OIDC client uses the browser Web Crypto API for PKCE, which the browser only exposes in a secure context. When the UI is served over plain HTTP on a non-localhost host, login fails with the browser console error "Failed to get access token: Error: OIDC login requires the UI to run on HTTPS or localhost. Current origin: http://HOST:PORT,"; surfaced in the page as "Failed to get UserManager from OIDC provider." Reaching the same server over a localhost origin (e.g. through an SSH or SSM tunnel) succeeds, as does serving it over HTTPS. The secure-context requirement is not stated anywhere in the setup. **Gap 2: The UI needs a dedicated public Keycloak client, separate from the confidential machine client** Affected page: security / how-to-authenticate, Keycloak example. The browser cannot hold a client secret, so the UI client must be a public client with client authentication off and the standard flow enabled. The confidential client used by machine flows and engines (e.g. Trino) relies on client-credentials and must stay confidential. The two roles require two separate clients in the same realm. The UI client also needs valid redirect URIs set to `UI_ORIGIN/*` and web origins set to `UI_ORIGIN`. The Keycloak example walks through one client without distinguishing the public UI client from the confidential engine client. **Gap 3: Issuer must be unified when browser and backend reach Keycloak by different hostnames** Affected page: security / how-to-authenticate. Once `gravitino.authenticator.oauth.authority` is set for the UI, the validator requires the token `iss` claim to match that authority. In deployments where the browser reaches Keycloak by one hostname and engines reach it by another, the issuer differs and tokens minted against the other endpoint are rejected with "JWT iss claim value rejected." Setting the realm Frontend URL to a single canonical value makes Keycloak stamp one issuer regardless of the connecting hostname. The interaction between `authority` and the token issuer is not documented, and there is no guidance for split-hostname deployments. ### How should we improve? 1. **Gap 1**: Add a prominent note that Web UI OIDC login requires a secure context (HTTPS or localhost origin). Recommend HTTPS for shared deployments and a localhost tunnel for local testing. 2. **Gap 2**: In the Keycloak setup, call out two clients explicitly — a confidential client for engines/scripts using client-credentials, and a separate public client for the Web UI with client authentication off, standard flow on, PKCE, redirect URIs of `UI_ORIGIN/*`, and web origins of `UI_ORIGIN`. 3. **Gap 3**: Note that `authority` makes the validator enforce the token issuer, and that all token sources must present the same issuer. Recommend setting the Keycloak realm Frontend URL to one canonical hostname and warn that mixing internal/external hostnames without this will reject otherwise valid tokens. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
