Skip to content
OpenShell
These docs are for the development version. Go to the latest released version (0.1.9).

Access Control

Configure OIDC user authentication or reverse-proxy auth termination for a Kubernetes-deployed OpenShell gateway.

The OpenShell gateway supports these access-control models for human callers on Kubernetes:

Model When to use
mTLS Gateways with a configured client CA and no OIDC issuer. The gateway maps a verified client certificate to a user identity.
OIDC (recommended) Production deployments. Integrates with an existing identity provider, supports role-based access control, and gives each user their own identity without distributing certificates.
Reverse-proxy auth termination An access proxy (Cloudflare Access, ngrok, corporate SSO) authenticates callers in front of the gateway. The gateway trusts the proxy and skips its own client-cert check.

The Helm chart generates a gateway TLS certificate and a user client certificate at install time. Supervisor Pods project only ca.crt from the client Secret so they can authenticate the gateway; the client certificate and private key are not exposed to sandboxes. Supervisors authenticate their RPCs with gateway-minted sandbox JWTs.

For how the CLI resolves gateways and stores credentials, refer to Gateway Authentication.

Kubernetes sandbox supervisors use gateway-issued session JWTs for sandbox-specific RPCs. A dedicated supervisor reads its preissued credential bundle from a mounted Secret. A shared supervisor receives each sandbox’s bundle through its assignment stream, authenticated with a separate supervisor-host JWT. See Getting the first credential.

The separate IssueSandboxToken bootstrap exchange remains available. When used, the Kubernetes driver validates the projected ServiceAccount token and returns the authenticated sandbox ID and runtime identity. The gateway requires the driver and runtime identity to match its stored sandbox record before issuing a gateway JWT.

Dynamic provider token grants use SPIFFE while keeping gateway-issued session JWTs for sandbox-specific RPCs. Dedicated supervisors use gatewayConfig.openshell.drivers.kubernetes.provider_spiffe_workload_api_socket_path to mount the CSI Workload API socket into gateway and sandbox pods. Shared supervisors instead use the gateway’s SPIFFE Broker API integration; only the gateway mounts the socket.

Provider token grants require a SPIFFE implementation such as SPIRE. Dedicated supervisors obtain Pod identities in the gateway’s trust domain. For shared supervisors, the gateway obtains the stable sandbox identity from the attested Sandbox CR UID, authorizes the session and attached provider, and performs the exchanges. SPIRE enforces the gateway SPIFFE ID’s permission to access that Sandbox resource. Token-exchange profiles also use the gateway’s own SPIFFE identity for the intermediate exchange.

The gateway verifies supervisor JWT-SVIDs with JWT bundles fetched from the SPIFFE Workload API, so intermediate token exchange does not require gateway access to the SPIRE OIDC discovery endpoint or its TLS CA.

Set gatewayConfig.openshell.gateway.oidc.issuer to enable OIDC. The gateway validates the Authorization: Bearer <token> header on every request against the issuer’s JWKS endpoint. It accepts JWTs signed with RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, or EdDSA (Ed25519) keys published in the issuer JWKS. Okta tenants that sign access tokens with ES256 work without additional gateway configuration.

Terminal window
helm upgrade openshell \
oci://ghcr.io/nvidia/openshell/helm-chart \
--version <version> \
--namespace openshell \
--set 'gatewayConfig.openshell\.gateway\.oidc.issuer=https://your-idp.example.com/realms/openshell' \
--set 'gatewayConfig.openshell\.gateway\.oidc.audience=openshell-cli' \
--set server.tls.clientCaSecretName=""

Client certificates are optional at the TLS handshake, so OIDC callers can connect without them. Set server.tls.clientCaSecretName="" to disable client-certificate verification entirely. The chart omits client_ca_path from gateway.toml and does not mount the client-CA volume, leaving HTTPS-only transport with OIDC for user authentication. Do not set the value to null; omit the key to use the chart default, or set it to "" to disable client certificate verification.

The audience value must match the client ID configured in your identity provider for the OpenShell resource server.

Value Default Purpose
gatewayConfig.openshell.gateway.oidc.issuer "" OIDC issuer URL. Empty disables OIDC.
server.oidc.caConfigMapName "" ConfigMap containing the private issuer CA in ca.crt; it augments platform roots for OIDC requests only.
gatewayConfig.openshell.gateway.oidc.audience openshell-cli Expected aud claim in the JWT.
gatewayConfig.openshell.gateway.oidc.jwks_ttl_secs 3600 JWKS key cache TTL in seconds. Must be greater than zero.
gatewayConfig.openshell.gateway.oidc.roles_claim realm_access.roles Dot-separated path to the roles array in JWT claims.
gatewayConfig.openshell.gateway.oidc.admin_role openshell-admin Role name that grants admin access.
gatewayConfig.openshell.gateway.oidc.user_role openshell-user Role name that grants standard user access.
gatewayConfig.openshell.gateway.oidc.scopes_claim "" Dot-separated path to the scopes array in JWT claims.

The issuer must use HTTPS. The gateway rejects discovery and JWKS redirects, limits response sizes, requires a JSON media type, and rejects a jwks_uri on a different origin unless that origin appears in jwks_allowed_origins. Use server.oidc.caConfigMapName for issuers signed by a private CA. The mounted CA augments platform roots for OIDC requests only; unrelated HTTPS clients continue to trust public services.

When OIDC is enabled, omitting the role fields uses the defaults above and enables RBAC. To use auth-only mode, explicitly set both admin_role and user_role to empty strings ("") under gatewayConfig.openshell.gateway.oidc. Authenticated users are treated as Platform Admins and bypass workspace membership checks. Configured OAuth scope checks still apply.

Keep the default role names, or configure both names for your identity provider, to use RBAC mode. The gateway checks the role claim and enforces access based on the assigned role:

Terminal window
helm upgrade openshell \
oci://ghcr.io/nvidia/openshell/helm-chart \
--version <version> \
--namespace openshell \
--set 'gatewayConfig.openshell\.gateway\.oidc.issuer=https://your-idp.example.com/realms/openshell' \
--set 'gatewayConfig.openshell\.gateway\.oidc.audience=openshell-cli' \
--set server.tls.clientCaSecretName="" \
--set 'gatewayConfig.openshell\.gateway\.oidc.roles_claim=realm_access.roles' \
--set 'gatewayConfig.openshell\.gateway\.oidc.admin_role=openshell-admin' \
--set 'gatewayConfig.openshell\.gateway\.oidc.user_role=openshell-user'

The effective role names must either both be non-empty or both be empty. The gateway rejects a configuration with exactly one empty role name.

OIDC RBAC combines method-level role and optional scope checks with workspace membership and role checks. Sandboxes and providers belong to a workspace, rather than to individual OIDC subjects. Workspace Users can use sandboxes and attach providers within their assigned workspaces; Workspace Admins manage resources in those workspaces. Platform Admins bypass workspace membership checks. Configure OIDC roles and separate workspace memberships when users must not access each other’s resources. See Workspaces.

Provider rolesClaim value
Keycloak realm_access.roles
Microsoft Entra ID roles
Okta groups

When an access proxy, such as Cloudflare Access, ngrok, or a corporate SSO gateway, terminates TLS and handles authentication in front of the OpenShell gateway, configure the gateway for plaintext traffic from that trusted proxy and explicitly allow unauthenticated user calls:

Terminal window
helm upgrade openshell \
oci://ghcr.io/nvidia/openshell/helm-chart \
--version <version> \
--namespace openshell \
--set server.disableTls=true \
--set 'gatewayConfig.openshell\.gateway\.auth.allow_unauthenticated_users=true'

The gateway listens on plaintext HTTP behind the trusted proxy, while sandbox supervisors still authenticate with gateway-minted sandbox JWTs. User-facing CLI/API calls without OIDC or mTLS credentials are accepted as an unauthenticated local developer principal. The proxy is responsible for authenticating callers and forwarding only authorized traffic.

Register the gateway with the CLI using the proxy’s public URL. The browser-based login flow runs automatically on first use:

Terminal window
openshell gateway add https://gateway.example.com --name production

We are a Cloud Native Computing Foundation sandbox project.