NVIDIA · alangou · Jun 11, 2026
@@ -29,6 +29,11 @@ gateway maps the verified certificate subject to a user principal. Kubernetes
 deployments use mTLS for transport only and require OIDC or a trusted access
 proxy for user authentication unless the explicit unsafe local-development
 `allow_unauthenticated_users` switch is enabled.
+OIDC deployments normally enforce RBAC roles for user and admin APIs. Shared
+gateways reject OIDC authentication-only mode unless
+`allow_oidc_auth_only` is set explicitly, and authenticated gRPC methods fail
+closed when no user, sandbox, mTLS, or explicit local-dev principal can be
+derived.
 When that service port is bound to loopback, the listener can also accept
 plaintext HTTP on the same port for sandbox service subdomains only. That local
 browser path is enabled by default and disabled with

@@ -479,6 +479,12 @@ pub struct GatewayAuthConfig {
     /// gateway-minted sandbox JWTs.
     #[serde(default)]
     pub allow_unauthenticated_users: bool,
+
+    /// When true, an OIDC issuer may authenticate users without requiring
+    /// configured RBAC roles. In that mode any valid token from the issuer can
+    /// call user and admin APIs, so shared deployments must opt in explicitly.
+    #[serde(default)]
+    pub allow_oidc_auth_only: bool,
 }
 
 const fn default_jwks_ttl_secs() -> u64 {
@@ -643,6 +649,66 @@ impl Config {
         self.service_routing.enable_loopback_service_http = enabled;
         self
     }
+
+    /// Validate auth settings that depend on the deployment posture.
+    ///
+    /// Local loopback gateways can rely on developer-oriented auth shortcuts,
+    /// but Kubernetes and externally-bound gateways must fail closed unless
+    /// the operator chose an explicit weak mode.
+    pub fn validate_gateway_auth_posture(&self) -> Result<(), String> {
+        let shared = self.is_shared_gateway_deployment();
+
+        if let Some(oidc) = &self.oidc {
+            let admin_set = !oidc.admin_role.is_empty();
+            let user_set = !oidc.user_role.is_empty();
+
+            if admin_set != user_set {
+                return Err(format!(
+                    "OIDC RBAC misconfiguration: admin_role={:?}, user_role={:?}. \
+                     Either set both roles (RBAC mode) or leave both empty (authentication-only mode).",
+                    oidc.admin_role, oidc.user_role,
+                ));
+            }
+
+            if shared && !admin_set && !self.auth.allow_oidc_auth_only {
+                return Err(
+                    "OIDC authentication-only mode is disabled for shared gateway deployments; \
+                     configure admin_role and user_role for RBAC, or set \
+                     auth.allow_oidc_auth_only=true to explicitly accept that any valid issuer token is authorized"
+                        .to_string(),
+                );
+            }
+        }
+
+        let has_authenticator = self.oidc.is_some() || self.gateway_jwt.is_some();
+        if shared
+            && !has_authenticator
+            && !self.mtls_auth.enabled
+            && !self.auth.allow_unauthenticated_users
+        {
+            return Err(
+                "shared gateway deployments require an explicit auth path; configure OIDC, \
+                 mTLS user auth, gateway_jwt sandbox auth, or set auth.allow_unauthenticated_users=true \
+                 only behind a trusted local-dev/fronting-proxy boundary"
+                    .to_string(),
+            );
+        }
+
+        Ok(())
+    }
+
+    /// Whether this gateway serves a shared or remotely reachable gRPC API.
+    #[must_use]
+    pub fn is_shared_gateway_deployment(&self) -> bool {
+        self.compute_drivers
+            .iter()
+            .any(|driver| matches!(driver, ComputeDriverKind::Kubernetes))
+            || !self.bind_address.ip().is_loopback()
+            || self
+                .extra_bind_addresses
+                .iter()
+                .any(|addr| !addr.ip().is_loopback())
+    }
 }
 
 impl Default for ServiceRoutingConfig {
@@ -727,9 +793,9 @@ mod tests {
     #[cfg(unix)]
     use super::is_reachable_unix_socket;
     use super::{
-        ComputeDriverKind, Config, DEFAULT_SERVICE_ROUTING_DOMAIN, GatewayJwtConfig, detect_driver,
-        docker_host_unix_socket_path, is_unix_socket, podman_socket_candidates_from_env,
-        podman_socket_responds,
+        ComputeDriverKind, Config, DEFAULT_SERVICE_ROUTING_DOMAIN, GatewayJwtConfig, OidcConfig,
+        detect_driver, docker_host_unix_socket_path, is_unix_socket,
+        podman_socket_candidates_from_env, podman_socket_responds,
     };
     #[cfg(unix)]
     use std::io::{Read as _, Write as _};
@@ -782,6 +848,70 @@ mod tests {
         assert!(!cfg.auth.allow_unauthenticated_users);
     }
 
+    fn oidc_config(admin_role: &str, user_role: &str) -> OidcConfig {
+        OidcConfig {
+            issuer: "https://issuer.example.com".to_string(),
+            audience: "openshell-cli".to_string(),
+            jwks_ttl_secs: 3600,
+            roles_claim: "realm_access.roles".to_string(),
+            admin_role: admin_role.to_string(),
+            user_role: user_role.to_string(),
+            scopes_claim: String::new(),
+        }
+    }
+
+    #[test]
+    fn gateway_auth_posture_allows_loopback_oidc_auth_only_without_override() {
+        let cfg = Config::new(None).with_oidc(oidc_config("", ""));
+
+        assert!(cfg.validate_gateway_auth_posture().is_ok());
+    }
+
+    #[test]
+    fn gateway_auth_posture_rejects_shared_oidc_auth_only_without_override() {
+        let cfg = Config::new(None)
+            .with_compute_drivers([ComputeDriverKind::Kubernetes])
+            .with_oidc(oidc_config("", ""));
+
+        let err = cfg.validate_gateway_auth_posture().unwrap_err();
+        assert!(err.contains("OIDC authentication-only mode"));
+    }
+
+    #[test]
+    fn gateway_auth_posture_allows_shared_oidc_auth_only_with_override() {
+        let mut cfg = Config::new(None)
+            .with_compute_drivers([ComputeDriverKind::Kubernetes])
+            .with_oidc(oidc_config("", ""));
+        cfg.auth.allow_oidc_auth_only = true;
+
+        assert!(cfg.validate_gateway_auth_posture().is_ok());
+    }
+
+    #[test]
+    fn gateway_auth_posture_allows_shared_oidc_rbac() {
+        let cfg = Config::new(None)
+            .with_compute_drivers([ComputeDriverKind::Kubernetes])
+            .with_oidc(oidc_config("openshell-admin", "openshell-user"));
+
+        assert!(cfg.validate_gateway_auth_posture().is_ok());
+    }
+
+    #[test]
+    fn gateway_auth_posture_rejects_partial_oidc_roles() {
+        let cfg = Config::new(None).with_oidc(oidc_config("openshell-admin", ""));
+
+        let err = cfg.validate_gateway_auth_posture().unwrap_err();
+        assert!(err.contains("OIDC RBAC misconfiguration"));
+    }
+
+    #[test]
+    fn gateway_auth_posture_rejects_shared_gateway_without_auth_path() {
+        let cfg = Config::new(None).with_compute_drivers([ComputeDriverKind::Kubernetes]);
+
+        let err = cfg.validate_gateway_auth_posture().unwrap_err();
+        assert!(err.contains("require an explicit auth path"));
+    }
+
     #[test]
     fn gateway_jwt_ttl_defaults_to_non_expiring() {
         let cfg: GatewayJwtConfig = serde_json::from_value(serde_json::json!({

@@ -423,8 +423,7 @@ async fn run_from_args(mut args: RunArgs, matches: ArgMatches) -> Result<()> {
         && config.gateway_jwt.is_none()
     {
         warn!(
-            "Neither mTLS user auth nor OIDC nor sandbox JWT auth is configured — \
-             the gateway has no authentication mechanism"
+            "No gateway authentication path is configured; non-loopback or shared deployments will fail startup"
         );
     }
 

@@ -385,11 +385,13 @@ grpc_endpoint = "https://openshell-gateway.agents.svc:8080"
         let toml = r"
 [openshell.gateway.auth]
 allow_unauthenticated_users = true
+allow_oidc_auth_only = true
 ";
         let tmp = write_tmp(toml);
         let file = load(tmp.path()).expect("valid auth config parses");
         let auth = file.openshell.gateway.auth.expect("auth config");
         assert!(auth.allow_unauthenticated_users);
+        assert!(auth.allow_oidc_auth_only);
     }
 
     #[test]

@@ -202,6 +202,9 @@ pub async fn run_server(
     if database_url.is_empty() {
         return Err(Error::config("database_url is required"));
     }
+    config
+        .validate_gateway_auth_posture()
+        .map_err(Error::config)?;
 
     let store = Arc::new(Store::connect(database_url).await?);
 

@@ -283,9 +283,9 @@ where
 /// for local single-user gateways, or to an unsafe local developer user when
 /// `auth.allow_unauthenticated_users` is explicitly enabled.
 ///
-/// When neither OIDC nor sandbox credentials are configured (a barebones
-/// dev gateway), the chain is left as `None` so the router short-circuits
-/// to pass-through unless mTLS or local unauthenticated users are enabled.
+/// When neither OIDC nor sandbox credentials are configured, the chain is left
+/// as `None`; authenticated methods still fail closed unless mTLS or local
+/// unauthenticated users are enabled explicitly.
 fn build_authenticator_chain(state: &ServerState) -> Option<AuthenticatorChain> {
     let mut authenticators: Vec<Arc<dyn crate::auth::authenticator::Authenticator>> = Vec::new();
     if let Some(k8s) = state.k8s_sa_authenticator.clone() {
@@ -310,8 +310,8 @@ fn build_authenticator_chain(state: &ServerState) -> Option<AuthenticatorChain>
 /// - Strip any external `x-openshell-auth-source` marker first (so callers
 ///   cannot spoof a sandbox identity).
 /// - Health probes / reflection bypass the chain entirely.
-/// - When no chain is configured (OIDC not configured), forward without
-///   authentication — preserves today's pass-through behavior.
+/// - When no chain is configured, authenticated methods fail closed unless
+///   mTLS user auth or the explicit local unauthenticated user mode applies.
 /// - Otherwise, run the chain. The first match produces a `Principal`.
 ///   `Principal::User` is gated by the RBAC `AuthzPolicy`.
 ///   `Principal::Sandbox` is gated by a supervisor-method allowlist, then
@@ -429,9 +429,9 @@ where
             } else if allow_unauthenticated_users {
                 unauthenticated_dev_user_principal()
             } else {
-                // No auth configured — pass through for dev /
-                // fronting-proxy deployments.
-                return inner.ready().await?.call(req).await;
+                return Ok(status_response(tonic::Status::unauthenticated(
+                    "gateway authentication is not configured",
+                )));
             };
 
             match principal {
@@ -1117,6 +1117,21 @@ mod tests {
             ));
         }
 
+        #[tokio::test]
+        async fn missing_chain_without_explicit_auth_fails_closed() {
+            let (recorder, seen) = PrincipalRecorder::new();
+            let mut router =
+                AuthGrpcRouter::with_peer_identity(recorder, None, None, None, false, false);
+
+            let res = router
+                .call(empty_request("/openshell.v1.OpenShell/ListSandboxes"))
+                .await
+                .unwrap();
+
+            assert!(seen.lock().unwrap().is_none());
+            assert_eq!(grpc_status(&res).as_deref(), Some("16"));
+        }
+
         #[tokio::test]
         async fn user_principal_lands_in_request_extensions() {
             let mock = Arc::new(MockAuthenticator::returning(Ok(Some(user_principal(

@@ -191,6 +191,7 @@ add `ci/values-spire.yaml` to the OpenShell release values files.
 | securityContext.runAsNonRoot | bool | `true` | Require the gateway container to run as a non-root user. |
 | securityContext.runAsUser | int | `1000` | UID assigned to the gateway container. |
 | server.appArmorProfile | string | `"Unconfined"` | Kubernetes AppArmor profile requested for sandbox agent containers. Default Unconfined avoids runtime/default AppArmor blocking the supervisor's network namespace mount setup on AppArmor-enabled nodes. Set to "" to omit the field, "RuntimeDefault" to force the runtime default profile, or "Localhost/profile-name" for an operator-managed localhost profile. |
+| server.auth.allowOidcAuthOnly | bool | `false` | UNSAFE: allow OIDC authentication-only mode when adminRole and userRole are both empty. In this mode any valid token from the issuer can call user and admin APIs. Leave false for shared or production clusters. |
 | server.auth.allowUnauthenticatedUsers | bool | `false` | UNSAFE: accept unauthenticated CLI/user requests as a local developer principal. Intended only for trusted local Skaffold/k3d development or a fully trusted fronting proxy. Leave false for shared or production clusters. |
 | server.dbUrl | string | `"sqlite:/var/openshell/openshell.db"` | Gateway database URL (used for the default SQLite backend). |
 | server.defaultRuntimeClassName | string | `""` | Default Kubernetes runtimeClassName for sandbox pods. Applied when a CreateSandbox request does not specify one. Empty (default) = omit the field, using the cluster's default RuntimeClass. Set to a RuntimeClass name (e.g. "kata-containers", "nvidia") to apply it to all sandboxes that don't explicitly override it. |
@@ -201,14 +202,14 @@ add `ci/values-spire.yaml` to the OpenShell release values files.
 | server.grpcEndpoint | string | `""` | gRPC endpoint sandboxes call back into the gateway. Leave empty to derive it from the chart fullname, release namespace, service port, and disableTls flag, for example https://openshell.openshell.svc.cluster.local:8080. Override only when sandboxes must reach the gateway via a different hostname (e.g. an external ingress or a host alias). |
 | server.hostGatewayIP | string | `""` | Host gateway IP for sandbox pod hostAliases. When set, sandbox pods get hostAliases entries mapping host.docker.internal and host.openshell.internal to this IP, allowing them to reach services running on the Docker host. Auto-detected by the cluster entrypoint script. |
 | server.logLevel | string | `"info"` | Gateway log level. |
-| server.oidc.adminRole | string | `""` | Role name for admin access. Leave empty (with userRole also empty) for authentication-only mode. Both must be set or both empty. |
+| server.oidc.adminRole | string | `""` | Role name for admin access. Set with userRole for RBAC mode. Leaving both empty enables authentication-only mode only when server.auth.allowOidcAuthOnly=true. |
 | server.oidc.audience | string | `"openshell-cli"` | Expected audience claim for the API resource server. This should match the server's --oidc-audience, NOT the CLI client ID. |
 | server.oidc.caConfigMapName | string | `""` | Name of a ConfigMap containing a CA certificate bundle (key: ca.crt) for verifying the OIDC issuer's TLS certificate. Required when the issuer uses a non-public CA (e.g. OpenShift ingress, private PKI). |
 | server.oidc.issuer | string | `""` | OIDC issuer URL (e.g. https://keycloak.example.com/realms/openshell). |
 | server.oidc.jwksTtl | int | `3600` | JWKS key cache TTL in seconds. |
 | server.oidc.rolesClaim | string | `""` | Dot-separated path to the roles array in the JWT claims. Keycloak: "realm_access.roles", Entra ID: "roles", Okta: "groups". |
 | server.oidc.scopesClaim | string | `""` | Dot-separated path to the scopes array in the JWT claims. |
-| server.oidc.userRole | string | `""` | Role name for standard user access. |
+| server.oidc.userRole | string | `""` | Role name for standard user access. Set with adminRole for RBAC mode. |
 | server.providerTokenGrants.spiffe.enabled | bool | `false` | Mount the SPIFFE Workload API socket into sandbox pods for dynamic provider token grants. |
 | server.providerTokenGrants.spiffe.workloadApiSocketPath | string | `"/spiffe-workload-api/spire-agent.sock"` | Path to the SPIFFE Workload API socket mounted into sandbox pods. |
 | server.sandboxImage | string | `"ghcr.io/nvidia/openshell-community/sandboxes/base:latest"` | Default sandbox image used when requests do not specify one. |

@@ -31,6 +31,7 @@ server:
     jwksTtl: 60
     # Keycloak puts realm roles at realm_access.roles in the JWT.
     rolesClaim: "realm_access.roles"
-    # Leave both empty for authentication-only mode (any valid token is accepted).
+    # RBAC mode: both roles must be set. Leave both empty only with
+    # server.auth.allowOidcAuthOnly=true for authentication-only mode.
     adminRole: "openshell-admin"
     userRole: "openshell-user"
@@ -163,9 +163,20 @@ Validate chart values that Helm would otherwise accept silently.
 {{- $workloadKind := include "openshell.workloadKind" . -}}
 {{- $workload := .Values.workload | default dict -}}
 {{- $replicaCount := int (default 1 .Values.replicaCount) -}}
+{{- $oidcIssuer := default "" .Values.server.oidc.issuer -}}
+{{- $oidcAdminRole := default "" .Values.server.oidc.adminRole -}}
+{{- $oidcUserRole := default "" .Values.server.oidc.userRole -}}
+{{- $oidcAdminRoleSet := ne $oidcAdminRole "" -}}
+{{- $oidcUserRoleSet := ne $oidcUserRole "" -}}
 {{- if and (hasKey .Values "postgres") (kindIs "map" .Values.postgres) (hasKey .Values.postgres "enabled") -}}
 {{- fail "postgres.enabled was removed; the OpenShell chart no longer deploys PostgreSQL. Provision PostgreSQL separately and set server.externalDbSecret to a Secret containing a PostgreSQL URI." -}}
 {{- end -}}
+{{- if and $oidcIssuer (ne $oidcAdminRoleSet $oidcUserRoleSet) -}}
+{{- fail "server.oidc.adminRole and server.oidc.userRole must either both be set for OIDC RBAC or both be empty for authentication-only mode." -}}
+{{- end -}}
+{{- if and $oidcIssuer (not $oidcAdminRoleSet) (not .Values.server.auth.allowOidcAuthOnly) -}}
+{{- fail "OIDC authentication-only mode authorizes any valid issuer token. Set server.oidc.adminRole and server.oidc.userRole for RBAC, or set server.auth.allowOidcAuthOnly=true to opt in explicitly." -}}
+{{- end -}}
 {{- if not (or (eq $workloadKind "statefulset") (eq $workloadKind "deployment")) -}}
 {{- fail "workload.kind must be one of: statefulset, deployment." -}}
 {{- end -}}

@@ -65,11 +65,16 @@ data:
     client_ca_path        = "/etc/openshell-tls/client-ca/ca.crt"
     {{- end }}
 
-    {{- if .Values.server.auth.allowUnauthenticatedUsers }}
+    {{- if or .Values.server.auth.allowUnauthenticatedUsers .Values.server.auth.allowOidcAuthOnly }}
 
     [openshell.gateway.auth]
+    {{- if .Values.server.auth.allowUnauthenticatedUsers }}
     allow_unauthenticated_users = true
     {{- end }}
+    {{- if .Values.server.auth.allowOidcAuthOnly }}
+    allow_oidc_auth_only = true
+    {{- end }}
+    {{- end }}
 
     [openshell.gateway.gateway_jwt]
     signing_key_path = "/etc/openshell-jwt/signing.pem"
@@ -87,10 +92,10 @@ data:
     {{- if .Values.server.oidc.rolesClaim }}
     roles_claim   = {{ .Values.server.oidc.rolesClaim | quote }}
     {{- end }}
-    {{- if .Values.server.oidc.adminRole }}
+    {{- if or .Values.server.oidc.adminRole .Values.server.auth.allowOidcAuthOnly }}
     admin_role    = {{ .Values.server.oidc.adminRole | quote }}
     {{- end }}
-    {{- if .Values.server.oidc.userRole }}
+    {{- if or .Values.server.oidc.userRole .Values.server.auth.allowOidcAuthOnly }}
     user_role     = {{ .Values.server.oidc.userRole | quote }}
     {{- end }}
     {{- if .Values.server.oidc.scopesClaim }}