feat(auth): authorize gateway users and admins through Kubernetes RBAC without JWT role/group claims

Start with auth/oidc.rs, auth/authz.rs, and auth/workspace_authz.rs, then compare the existing TokenReview path in auth/k8s_sa.rs. Define the maintainers-approved configuration and authorization boundaries before implementation. Done means the documented RBAC flow, failure cases, compatibility behavior, and real Kubernetes/OpenShift integration tests cover the acceptance criteria.

User Story

As an operator running OpenShell on Kubernetes or OpenShift behind an application broker, I want gateway user/admin authorization to use existing Kubernetes RBAC, so that a designated backend ServiceAccount and approved human administrators can access the gateway without requiring roles/groups to be embedded in JWTs or introducing a second identity provider or authentication proxy.

Problem Statement

The OIDC user authorization path in v0.0.116 expects a configurable roles array in a JWT. Kubernetes service-account issuer discovery/JWKS supports validating SA JWTs, but those tokens do not carry the issuing human's groups or Kubernetes RoleBindings. Native OpenShift login can instead produce an opaque OAuth access token, which cannot be processed as a JWT at all.

These are two distinct authentication cases with the same missing authorization integration: Kubernetes already knows the authenticated identity and its effective RBAC permissions, but the gateway does not delegate user/platform-admin authorization to SubjectAccessReview. A token's audience is an intended recipient, not a role assignment, and must not be used as a substitute for RBAC.

Impact / Why This Matters

Restricted clusters commonly already authorize humans through enterprise group-backed RoleBindings and automation through ServiceAccount bindings. Operators should be able to reuse those policies for OpenShell. Requiring new IdP application-role claims, an additional issuer, or a fronting proxy adds integration and lifecycle work despite Kubernetes already supporting authentication and access-review APIs. Network isolation and mTLS remain useful, but neither supplies this RBAC decision.

Proposed Design

Add an explicit, opt-in Kubernetes-backed authentication/authorization mode, configurable in Helm and gateway configuration. Exact field names and internal implementation are left to maintainers.

Operator workflow:

1. Configure the trusted Kubernetes API endpoint/CA and the gateway's own narrowly scoped review credentials. Do not accept an API endpoint or authorization target from the request.
2. Define the Kubernetes authorization attributes corresponding to gateway use and platform-admin operations: namespace, API group, resource, optional resource name, and distinct verbs. Document a dedicated permission model that can be bound to a backend SA or human group without granting unrelated pod/Secret administration. Whether this uses a virtual authorization resource or another documented resource is a design decision.
3. Bind those permissions using ordinary Roles/RoleBindings (or appropriately scoped ClusterRoles). A Kubernetes namespace administrator is not automatically an OpenShell admin unless the configured authorization check actually permits it.
4. For a caller presenting a cluster-recognized bearer token, authenticate through TokenReview. Support Kubernetes SA JWTs and OpenShift OAuth tokens accepted by that cluster. Derive username, UID, groups, and relevant extra fields only from the authenticated result, never from caller headers or an unverified payload. Preserve token-scope restrictions where the platform expresses them in authenticated identity metadata.
5. Authorize gateway user/admin operations through SubjectAccessReview or LocalSubjectAccessReview using that verified identity. Missing JWT role/group claims must not prevent this workflow. A TokenReview success alone must never confer gateway admin.
6. Preserve existing workspace-membership checks for ordinary users; grant platform-admin behavior only after the configured admin review allows it. Define the stable principal mapping for membership/auditing. Sandbox-supervisor bootstrap and sandbox-scoped gateway JWTs remain separate and unchanged.

Audience handling must be explicit and validated for TokenReview-backed authentication; document supported audiences and behavior for native OpenShift OAuth credentials. This proposal does not assume an arbitrary external OIDC JWT is accepted by the Kubernetes API: that requires the cluster to trust it, otherwise it must be rejected.

Acceptance Criteria

• A correctly bound backend SA can perform the configured gateway operations without roles/groups in its JWT.
• A valid SA token from another namespace is denied when its authenticated identity lacks the configured permission, even if it has the expected gateway audience.
• A token containing an audience string that resembles an admin role does not acquire admin privileges without an allowing RBAC decision.
• An OpenShift human token accepted by TokenReview is authorized through existing group-backed RBAC; a real non-member is denied. Do not emulate this using caller-supplied groups.
• User and admin authorization are distinct and enforced consistently in middleware and workspace/platform handlers, including direct gateway connections and port-forward access.
• Invalid/expired tokens, wrong audiences, denied reviews, review API errors/timeouts, or missing gateway review permissions fail closed. No fallback to auth-only/platform-admin mode.
• Bindings revoked during operation cease authorizing within a documented, bounded interval; any cache has configurable limits and does not preserve expired decisions during failures.
• Gateway review permissions, API availability requirements, token audience configuration, stable identity mapping, and workspace behavior are documented. No token or credential contents appear in logs/audit records.
• Existing OIDC role-based deployments remain compatible unless the operator explicitly selects this mode; ambiguous combinations have documented, safe behavior.
• Real Kubernetes/OpenShift integration tests cover backend SA allow, unrelated SA deny, human group allow/deny, RBAC revocation, and review failures; supervisor operation remains functional.

Alternatives Considered

• Claim-based OIDC roles: suitable when the issuer provides controlled claims; does not reuse Kubernetes RBAC or authenticate opaque OpenShift OAuth tokens.
• A proxy performing TokenReview/SAR: possible, but adds a separate deployment and cannot be assumed transparent to existing client authentication/streaming contracts.
• Certificate roles (#3071): a useful alternative for broker-only admin identity, but does not provide dynamic Kubernetes RBAC/group authorization.
• Explicit OIDC admin subjects (#2613, closed as not planned): static identity grants would not track namespace RoleBindings or enterprise group membership.
• NetworkPolicy/AdminNetworkPolicy: restrict connectivity but do not distinguish user/admin RPCs on the same listener.

Agent Investigation

Reviewed v0.0.116 auth/oidc.rs, auth/authz.rs, and auth/workspace_authz.rs: role extraction and platform-admin checks use JWT-derived roles rather than Kubernetes access reviews. auth/k8s_sa.rs already uses TokenReview for sandbox-supervisor bootstrap, but that is a different credential path and does not authorize human/backend administrative operations. Searched existing issues for SubjectAccessReview and found no duplicate at filing time.

Related issues:

• #3071 — mTLS administrator roles; alternative identity/authorization model, not a prerequisite for this proposal.
• #2590 — importing externally issued OIDC tokens into the CLI; related credential UX, but opaque OAuth token support would need explicit consideration.
• #3043 — separating cluster-scoped chart RBAC from namespace-admin installation; relevant packaging support for platform-provisioned review permissions.
• #2613 — explicit admin subjects, closed as not planned.

References:

• https://docs.redhat.com/en/documentation/openshift_container_platform/4.20/html/authorization_apis/authorization-apis
• https://docs.redhat.com/en/documentation/openshift_container_platform/4.20/html/authentication_and_authorization/configuring-internal-oauth
• https://kubernetes.io/docs/reference/access-authn-authz/service-accounts-admin/

Checklist

• Reviewed existing issues and the relevant authentication/authorization source and documentation.
• This is a design proposal with observable acceptance criteria, not a request to change an existing deployment.