mirror of
https://github.com/NVIDIA/OpenShell.git
synced 2026-10-02 07:34:45 +08:00
docs(website): sync dev docs from e21b7fd8cf
This commit is contained in:
github-actions[bot]
@@ -1,8 +1,8 @@
|
||||
snapshots:
|
||||
dev:
|
||||
source-ref: 2935e9731b97e89ae78aa7bc66867bc2281444ef
|
||||
source-sha: 2935e9731b97e89ae78aa7bc66867bc2281444ef
|
||||
version: 0.1.3.dev41
|
||||
source-ref: e21b7fd8cfc170385c822566176dbd31e1462c0e
|
||||
source-sha: e21b7fd8cfc170385c822566176dbd31e1462c0e
|
||||
version: 0.1.3.dev43
|
||||
latest:
|
||||
source-ref: 6648bd0c290efbc41ba131ee9831ee45cd431f94
|
||||
source-sha: 6648bd0c290efbc41ba131ee9831ee45cd431f94
|
||||
|
||||
@@ -126,6 +126,10 @@ that signs credentials, and every credential names exactly one sandbox.
|
||||
| **Supervisor** to **sandbox** | The **supervisor** dials into the workload over the driver's private channel. | Mutual TLS, plus a sandbox JWT. |
|
||||
| Agent to **supervisor** | The agent never connects directly. The **sandbox** relays its traffic over the connection above. | Covered by the supervisor-to-sandbox channel. |
|
||||
|
||||
The **supervisor** verifies the gateway's TLS certificate with its CA. User
|
||||
client certificates and private keys stay outside both the **supervisor** and
|
||||
workload; the gateway JWT authenticates supervisor RPCs.
|
||||
|
||||
### Getting the first credential
|
||||
|
||||
The **supervisor** needs a starting credential to prove which sandbox it belongs
|
||||
|
||||
@@ -33,9 +33,9 @@ The CLI uses one of these authentication modes depending on the gateway's config
|
||||
|
||||
### mTLS
|
||||
|
||||
The default mode for local Docker, Podman, and VM gateways without OIDC. The CLI presents a client certificate during the TLS handshake, and the gateway can map the verified certificate subject to a local user principal when mTLS user authentication is enabled.
|
||||
The default mode for gateways with a client CA and no OIDC issuer. The CLI presents a client certificate during the TLS handshake, and the gateway can map the verified certificate subject to a local user principal when mTLS user authentication is enabled.
|
||||
|
||||
mTLS user authentication is for local single-user gateways. Kubernetes deployments must use OIDC or a trusted access proxy for user authentication; the Helm chart does not render `mtls_auth`.
|
||||
mTLS user authentication is gateway policy and is independent of the compute driver. Shared deployments can prefer OIDC or a trusted access proxy for user identity and lifecycle management.
|
||||
|
||||
Set these environment variables before starting the gateway:
|
||||
|
||||
@@ -44,13 +44,13 @@ Set these environment variables before starting the gateway:
|
||||
| `OPENSHELL_TLS_CERT` | Path to the gateway server certificate. |
|
||||
| `OPENSHELL_TLS_KEY` | Path to the gateway server private key. |
|
||||
| `OPENSHELL_TLS_CLIENT_CA` | Path to the CA certificate that verifies CLI client certificates. |
|
||||
| `OPENSHELL_ENABLE_MTLS_AUTH` | Set to `true` to authenticate CLI callers from verified client certificates. Defaults on for local Docker, Podman, and VM gateways with no OIDC issuer. |
|
||||
| `OPENSHELL_ENABLE_MTLS_AUTH` | Set to `true` to authenticate CLI callers from verified client certificates. Defaults on when a client CA is configured and no OIDC issuer is present. |
|
||||
|
||||
For local access, the server certificate must be valid for the endpoint the CLI uses. Include `localhost`, `127.0.0.1`, and `::1` in the certificate SANs when users connect to a local gateway through loopback.
|
||||
|
||||
Package-managed local gateways generate this bundle automatically for the `openshell` gateway name. Homebrew registers `https://localhost:17670`; Debian and RPM use `https://127.0.0.1:17670`.
|
||||
When you register a package-managed local gateway with `openshell gateway add <endpoint> --local --name openshell`, the CLI refreshes its mTLS bundle from the package-managed TLS directory.
|
||||
On Homebrew, the gateway service also mirrors the Docker sandbox client bundle into `$HOME/.local/state/openshell/homebrew/tls` before startup so Docker Desktop can bind-mount the files into sandbox containers.
|
||||
On Homebrew, the gateway service also mirrors the gateway CA into `$HOME/.local/state/openshell/homebrew/tls` before startup so Docker Desktop can bind-mount gateway trust into supervisor containers. The driver does not mount the user client certificate or private key.
|
||||
|
||||
The CLI loads its mTLS bundle from `~/.config/openshell/gateways/<name>/mtls/`:
|
||||
|
||||
@@ -73,7 +73,7 @@ The connection flow:
|
||||
|
||||
Gateways can validate OpenID Connect access tokens on gRPC requests. Configure OIDC when you want users, operators, or automation to authenticate with an identity provider such as Keycloak, Entra ID, or Okta.
|
||||
|
||||
OIDC is application-layer authentication. TLS still controls the transport. If TLS client certificates remain required, the CLI must also have an mTLS bundle for the gateway.
|
||||
OIDC is application-layer authentication. TLS authenticates the gateway and protects the transport; OIDC clients do not need a TLS client certificate. The gateway validates any client certificate they present against the configured client CA.
|
||||
|
||||
Configure the gateway with an issuer and audience:
|
||||
|
||||
@@ -223,7 +223,7 @@ Common identity providers such as Keycloak (RS256), Microsoft Entra ID (RSA), an
|
||||
|
||||
If `OPENSHELL_OIDC_SCOPES_CLAIM` is set, the gateway also enforces scopes. It accepts space-delimited scope strings such as `scope: "openid sandbox:read"` and JSON arrays such as `scp: ["sandbox:read"]`. Standard OIDC scopes such as `openid`, `profile`, `email`, and `offline_access` are ignored for authorization. `openshell:all` grants access to all scoped methods.
|
||||
|
||||
Supervisor-to-gateway RPCs do not use user OIDC tokens or mTLS user identity. Each sandbox supervisor presents a gateway-minted `Authorization: Bearer` token scoped to its sandbox ID. On Kubernetes, the Kubernetes compute driver validates the projected ServiceAccount token with TokenReview, verifies the live pod UID and controlling `Sandbox` ownerReference, and returns the authenticated sandbox ID plus a stable runtime identity. The gateway requires that runtime identity to match the value recorded when it provisioned the sandbox before minting a JWT. Log upload, policy status, provider environment lookup, and sandbox config sync run with sandbox-restricted scope, while CLI users authenticate with OIDC, edge auth, local mTLS user authentication, or an explicitly enabled unauthenticated local developer mode. Provider environment responses expose only the credentials and configuration attached to that sandbox, subject to endpoint binding and credential expiry checks.
|
||||
Supervisor-to-gateway RPCs do not use user OIDC tokens or mTLS user identity. TLS authenticates the gateway using the configured CA; user client certificates and private keys are not mounted into supervisor or workload containers. Each sandbox supervisor presents a gateway-minted `Authorization: Bearer` token scoped to its sandbox ID. On Kubernetes, the Kubernetes compute driver validates the projected ServiceAccount token with TokenReview, verifies the live pod UID and controlling `Sandbox` ownerReference, and returns the authenticated sandbox ID plus a stable runtime identity. The gateway requires that runtime identity to match the value recorded when it provisioned the sandbox before minting a JWT. Log upload, policy status, provider environment lookup, and sandbox config sync run with sandbox-restricted scope, while CLI users authenticate with OIDC, edge auth, local mTLS user authentication, or an explicitly enabled unauthenticated local developer mode. Provider environment responses expose only the credentials and configuration attached to that sandbox, subject to endpoint binding and credential expiry checks.
|
||||
|
||||
Re-authenticate an OIDC gateway with:
|
||||
|
||||
|
||||
@@ -81,11 +81,11 @@ future version. To migrate an existing file:
|
||||
removed `--driver` and `--drivers` flags remain unsupported.
|
||||
3. Move every compute-driver option into `[openshell.drivers.<name>]`. Schema
|
||||
version 2 does not inherit driver defaults from `[openshell.gateway]`.
|
||||
Keep only `guest_tls_ca`, `guest_tls_cert`, and `guest_tls_key` at gateway
|
||||
scope. A TLS-enabled Docker, Podman, or VM gateway requires one complete
|
||||
guest bundle. Set all three paths unless the package-managed local TLS
|
||||
bundle supplies them. When TLS is disabled, omit all three. Kubernetes
|
||||
projects sandbox TLS through `client_tls_secret_name` instead.
|
||||
Keep `guest_tls_ca` at gateway scope and remove `guest_tls_cert` and
|
||||
`guest_tls_key`. A TLS-enabled Docker, Podman, or VM gateway requires the
|
||||
gateway CA unless package-managed local TLS supplies it. When TLS is
|
||||
disabled, omit it. Kubernetes projects the gateway CA into supervisor Pods
|
||||
through `client_tls_secret_name` instead.
|
||||
4. Rename Docker `sandbox_namespace` to `sandbox_label`, Podman
|
||||
`sandbox_ssh_socket_path` to `ssh_socket_path`, and VM
|
||||
`openshell_endpoint` to `grpc_endpoint`.
|
||||
@@ -155,14 +155,11 @@ enable_websocket_tunnel = false
|
||||
# Set true only for local plaintext gateways or trusted TLS termination.
|
||||
disable_tls = false
|
||||
|
||||
# Guest TLS paths remain gateway settings. TLS-enabled Docker, Podman, and VM
|
||||
# gateways require a complete bundle unless package-managed local TLS supplies
|
||||
# it automatically. Omit all three when TLS is disabled. Kubernetes projects
|
||||
# sandbox TLS from client_tls_secret_name instead. Driver tables must not repeat
|
||||
# these fields.
|
||||
# The supervisor gateway CA remains a gateway setting. TLS-enabled Docker,
|
||||
# Podman, and VM gateways require it unless package-managed local TLS supplies
|
||||
# it automatically. Omit it when TLS is disabled. Kubernetes projects the CA
|
||||
# from client_tls_secret_name instead. Driver tables must not repeat this field.
|
||||
guest_tls_ca = "/etc/openshell/certs/ca.pem"
|
||||
guest_tls_cert = "/etc/openshell/certs/client.pem"
|
||||
guest_tls_key = "/etc/openshell/certs/client-key.pem"
|
||||
|
||||
# Optional gRPC rate limit. Both values must be positive to enable the limit.
|
||||
# Set either value to 0, or omit both, to disable rate limiting.
|
||||
@@ -185,7 +182,7 @@ audience = "urn:openshell:middleware:local-content-guard"
|
||||
max_payload_bytes = 262144
|
||||
timeout = "500ms"
|
||||
|
||||
# Gateway listener TLS (distinct from the per-driver guest_tls_*).
|
||||
# Gateway listener TLS (distinct from the supervisor gateway CA).
|
||||
# client_ca_path is optional; omit it for HTTPS-only listeners that do not
|
||||
# verify client certificates.
|
||||
[openshell.gateway.tls]
|
||||
@@ -264,9 +261,9 @@ sa_token_ttl_secs = 3600
|
||||
namespace = "openshell"
|
||||
```
|
||||
|
||||
Local Docker, Podman, and VM gateways can also set `[openshell.gateway.mtls_auth] enabled = true` to map a verified client certificate to a CLI user identity. This application-layer identity switch does not control the TLS handshake. When `client_ca_path` is set without OIDC, the listener requires a valid client certificate. When OIDC is configured, bearer-only clients may connect; the listener still validates any client certificate they present against the configured CA. Kubernetes deployments must leave `mtls_auth.enabled` unset and use OIDC or a trusted access proxy; the Helm chart does not render this table.
|
||||
Set `[openshell.gateway.mtls_auth] enabled = true` to map a verified client certificate to a CLI user identity. This gateway policy is independent of the compute driver and defaults on when a client CA is configured without OIDC. The listener allows bearer-only clients and validates any client certificate presented against the configured CA. Supervisors use `guest_tls_ca` to authenticate the gateway and sandbox bearer tokens to authenticate their RPCs.
|
||||
|
||||
The client-certificate handshake policy is derived and has no `require_client_auth` TOML field. This preserves bearer-only OIDC clients and prevents a file setting from silently weakening CA-only gateways.
|
||||
The client-certificate handshake policy has no `require_client_auth` TOML field. Client certificates are optional at the transport layer; gateway RPC authorization enforces the configured user or sandbox identity.
|
||||
|
||||
`[openshell.gateway.tls]` supports optional SNI-based dual-certificate mode for deployments that need separate internal and external server certificates. Set `external_cert_path` and `external_key_path` to point at the external (e.g. ACME/publicly-trusted) certificate and key. List the hostnames that should be served with the external certificate in `external_server_names`. Connections whose TLS SNI hostname matches one of those names receive the external certificate; all other connections (including those with no SNI) receive the primary internal certificate from `cert_path`/`key_path`. Both fields must be set together — providing only one is a configuration error. On Kubernetes with the Helm chart, the external certificate is managed automatically when `certManager.serverIssuerRef.name` is set; the chart populates these fields from the cert-manager-issued external server certificate.
|
||||
|
||||
@@ -703,7 +700,7 @@ Kubernetes configurations set `namespace`, `service_account_name`, and `enable_u
|
||||
|
||||
### Kubernetes
|
||||
|
||||
The gateway runs as a Pod and creates sandbox Pods in another namespace. mTLS material for sandboxes is delivered through a Kubernetes Secret rather than host-side file paths.
|
||||
The gateway runs as a Pod and creates paired workload and supervisor Pods in another namespace. The gateway CA is projected from a Kubernetes Secret into supervisor Pods; user client certificate and key entries in that Secret are not exposed to either Pod.
|
||||
|
||||
```toml
|
||||
[openshell]
|
||||
@@ -888,7 +885,7 @@ output.
|
||||
|
||||
### Docker
|
||||
|
||||
Sandboxes run as containers on a local bridge network. The supervisor binary is bind-mounted from the host (no in-cluster image pull required). Configure guest mTLS paths once under `[openshell.gateway]`; the gateway validates and injects the bundle into the selected local driver.
|
||||
Each Docker sandbox uses a workload container with networking disabled and a host-networked supervisor container. Configure the supervisor gateway CA once under `[openshell.gateway]`; the gateway validates and injects it into the selected local driver. The supervisor authenticates RPCs with a sandbox bearer token.
|
||||
|
||||
```toml
|
||||
[openshell]
|
||||
@@ -898,10 +895,8 @@ version = 2
|
||||
bind_address = "127.0.0.1:17670"
|
||||
log_level = "info"
|
||||
compute_driver = "docker"
|
||||
# Gateway-owned bundle injected into the selected local driver.
|
||||
# Gateway-owned CA injected into the selected local driver.
|
||||
guest_tls_ca = "/etc/openshell/certs/ca.pem"
|
||||
guest_tls_cert = "/etc/openshell/certs/client.pem"
|
||||
guest_tls_key = "/etc/openshell/certs/client-key.pem"
|
||||
|
||||
[openshell.drivers.docker]
|
||||
socket_path = "/var/run/docker.sock"
|
||||
@@ -974,7 +969,7 @@ path is never mounted into or exposed to the workload container.
|
||||
|
||||
### Podman
|
||||
|
||||
Each Podman sandbox uses two containers. The workload container runs `openshell-sandbox` with `network=none`; the supervisor container runs on the host network and initiates policy-approved upstream connections. A private volume carries their authenticated Unix-domain socket. Configure guest mTLS paths once under `[openshell.gateway]`; the gateway validates and injects the bundle into the selected local driver.
|
||||
Each Podman sandbox uses two containers. The workload container runs `openshell-sandbox` with `network=none`; the supervisor container runs on the host network and initiates policy-approved upstream connections. A private volume carries their authenticated Unix-domain socket. Configure the supervisor gateway CA once under `[openshell.gateway]`; the gateway validates and injects it into the selected local driver. The supervisor authenticates RPCs with a sandbox bearer token.
|
||||
|
||||
```toml
|
||||
[openshell]
|
||||
@@ -984,10 +979,8 @@ version = 2
|
||||
bind_address = "127.0.0.1:17670"
|
||||
log_level = "info"
|
||||
compute_driver = "podman"
|
||||
# Gateway-owned bundle injected into the selected local driver.
|
||||
# Gateway-owned CA injected into the selected local driver.
|
||||
guest_tls_ca = "/etc/openshell/certs/ca.pem"
|
||||
guest_tls_cert = "/etc/openshell/certs/client.pem"
|
||||
guest_tls_key = "/etc/openshell/certs/client-key.pem"
|
||||
|
||||
[openshell.drivers.podman]
|
||||
network_name = "openshell"
|
||||
@@ -1139,10 +1132,8 @@ bind_address = "127.0.0.1:17670"
|
||||
log_level = "info"
|
||||
# VM is never auto-detected; an explicit entry here is required.
|
||||
compute_driver = "vm"
|
||||
# Gateway-owned bundle injected into the selected local driver.
|
||||
# Gateway-owned CA injected into the selected local driver.
|
||||
guest_tls_ca = "/var/lib/openshell/guest-tls/ca.pem"
|
||||
guest_tls_cert = "/var/lib/openshell/guest-tls/client.pem"
|
||||
guest_tls_key = "/var/lib/openshell/guest-tls/client-key.pem"
|
||||
|
||||
[openshell.drivers.vm]
|
||||
state_dir = "/var/lib/openshell/vm"
|
||||
|
||||
@@ -36,6 +36,13 @@ When `compute_driver` is unset, the gateway auto-detects Kubernetes, then Podman
|
||||
|
||||
Configure driver-specific values, such as images, endpoints, and sizing, under `[openshell.drivers.<name>]`. See the [Gateway Configuration File](/how-it-works/gateways/configuration) reference for every option.
|
||||
|
||||
For TLS-enabled Docker, Podman, and MicroVM gateways, set `guest_tls_ca` in
|
||||
`[openshell.gateway]` or use the package-managed local CA. Remove the retired
|
||||
`guest_tls_cert` and `guest_tls_key` fields. Supervisors receive only the
|
||||
CA and authenticate gateway RPCs with sandbox bearer tokens. Kubernetes
|
||||
projects or stages only the gateway CA from its configured TLS Secret; user
|
||||
client certificates and private keys stay outside the sandbox boundary.
|
||||
|
||||
### Extension Drivers
|
||||
|
||||
Any name other than a built-in driver selects an extension driver. Point the gateway at the Unix socket where the driver listens:
|
||||
@@ -221,7 +228,7 @@ Only the OpenShell gateway and the Agent Sandbox controller should be able to ma
|
||||
| `image_pull_policy` | `sandbox.image.pullPolicy` | `always`, `if_not_present`, or `never`. |
|
||||
| `image_pull_secrets` | `server.sandboxImagePullSecrets` | Image-pull Secrets for sandbox pods. |
|
||||
| `grpc_endpoint` | `server.grpcEndpoint` | Gateway endpoint reachable from sandbox pods. |
|
||||
| `client_tls_secret_name` | `server.tls.clientTlsSecretName` | Secret with sandbox client TLS material. |
|
||||
| `client_tls_secret_name` | `server.tls.clientTlsSecretName` | Project or stage only `ca.crt` into supervisor Pods to authenticate the gateway. |
|
||||
| `sandbox_runtime_image` | `sandboxRuntime.image.*` | Override the sandbox runtime image. |
|
||||
| `supervisor_image` | `supervisor.image.*` | Override the supervisor image. |
|
||||
| `workspace_default_storage_size` | `server.workspaceDefaultStorageSize` | Default workspace PVC size. |
|
||||
|
||||
@@ -8,14 +8,15 @@ keywords: "Generative AI, Cybersecurity, Kubernetes, Authentication, mTLS, OIDC,
|
||||
position: 6
|
||||
---
|
||||
|
||||
The OpenShell gateway supports two access-control models for human callers on Kubernetes:
|
||||
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 always generates mTLS certificates at install time. The gateway uses them for transport-layer security regardless of which access-control model you choose. The client bundle in the `openshell-client-tls` secret is used internally by sandbox supervisors, not for granting access to individual users.
|
||||
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](/how-it-works/gateways/authentication).
|
||||
|
||||
@@ -43,7 +44,7 @@ helm upgrade openshell \
|
||||
--set server.tls.clientCaSecretName=""
|
||||
```
|
||||
|
||||
Set `server.tls.clientCaSecretName=""` when the gateway terminates TLS directly and browsers or CLI clients connect without client certificates. 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.
|
||||
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.
|
||||
|
||||
@@ -112,7 +113,7 @@ helm upgrade openshell \
|
||||
|
||||
The gateway still serves TLS and 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.
|
||||
|
||||
When the gateway terminates TLS directly and callers connect without client certificates, also set `server.tls.clientCaSecretName=""` as described in the OIDC section above.
|
||||
To disable client-certificate verification entirely, set `server.tls.clientCaSecretName=""` as described in the OIDC section above.
|
||||
|
||||
To also disable TLS entirely (when the proxy terminates TLS before the request reaches the gateway):
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@ keywords: "Generative AI, Cybersecurity, Kubernetes, cert-manager, PKI, TLS, mTL
|
||||
position: 4
|
||||
---
|
||||
|
||||
The OpenShell gateway uses mTLS certificates for transport between the gateway and sandbox supervisors. These certificates are not Kubernetes user authentication; configure OIDC or a trusted access proxy for user access. The Helm chart supports two ways to provision and manage the certificate bundle:
|
||||
The OpenShell gateway uses TLS for transport to sandbox supervisors. Supervisor Pods receive the gateway CA, not a client certificate or private key, and authenticate RPCs with sandbox JWTs. The generated client certificate can authenticate user clients when gateway mTLS user authentication is enabled; shared deployments can instead configure OIDC or a trusted access proxy. The Helm chart supports two ways to provision and manage the certificate bundle:
|
||||
|
||||
| Mode | When to use |
|
||||
|---|---|
|
||||
|
||||
@@ -46,8 +46,8 @@ cargo build --release -p openshell-gateway --no-default-features --features tele
|
||||
# Docker and VM only, with telemetry compiled out.
|
||||
cargo build --release -p openshell-gateway --no-default-features --features compute-driver-docker,compute-driver-vm
|
||||
|
||||
# Windows MXC only, with telemetry support and bundled Z3.
|
||||
cargo build --release -p openshell-gateway --no-default-features --features telemetry,compute-driver-mxc,bundled-z3
|
||||
# Windows MXC only, with telemetry support and prebuilt Z3.
|
||||
cargo build --release -p openshell-gateway --no-default-features --features telemetry,compute-driver-mxc,openshell-server/prebuilt-z3
|
||||
```
|
||||
|
||||
Regular builds keep their platform driver set through the default `in-tree-compute-drivers` compatibility feature. On Windows, `compute-driver-mxc` selects MXC and the other four features install unsupported-driver stubs. On other platforms, MXC is excluded.
|
||||
|
||||
@@ -260,14 +260,14 @@ The gateway secures communication between the CLI, sandbox workloads, and extern
|
||||
|
||||
### mTLS
|
||||
|
||||
Gateway transport uses TLS, with client certificate checks available where the deployment provides a client CA. Local single-user Docker, Podman, and VM gateways can use the verified client certificate as user authentication. Kubernetes deployments use the certificate bundle for transport and sandbox supervisor connectivity only; configure OIDC or a trusted access proxy for user authentication.
|
||||
Gateway transport uses TLS, with client certificate checks available where the deployment provides a client CA. mTLS user authentication is gateway policy and does not depend on the compute driver. Sandbox supervisors receive only the gateway CA and authenticate API calls with gateway-minted sandbox JWTs.
|
||||
|
||||
| Aspect | Detail |
|
||||
|---|---|
|
||||
| Default | Local TLS bundles enable mTLS user authentication for single-user local gateways. Helm deployments generate mTLS certificates for transport, while sandbox supervisors authenticate API calls with gateway-minted sandbox JWTs. TLS-enabled loopback gateways also accept plaintext HTTP for sandbox service hostnames by default. |
|
||||
| What you can change | Configure OIDC or a trusted access proxy for multi-user gateways, set `OPENSHELL_ENABLE_MTLS_AUTH=true` for local single-user gateways, enable `server.auth.allowUnauthenticatedUsers=true` only for trusted local Kubernetes development or a fully trusted proxy, disable TLS only for trusted reverse-proxy setups, or disable loopback service HTTP with `--enable-loopback-service-http=false`. |
|
||||
| Risk if relaxed | Disabling TLS removes transport-level protection entirely. Allowing unauthenticated users removes the gateway user-auth boundary and must not be exposed to shared or public networks. Treating transport certificates as shared user identity in Kubernetes would collapse user and sandbox trust boundaries. Loopback service HTTP is local-only and rejects cross-origin browser requests, but any local process can still reach exposed service URLs directly. |
|
||||
| Recommendation | Use local mTLS user authentication only for single-user Docker, Podman, and VM gateways. Use OIDC or a trusted access proxy for Kubernetes and shared deployments. |
|
||||
| Default | A configured client CA without OIDC enables mTLS user authentication. Sandbox supervisors use CA-only TLS plus gateway-minted sandbox JWTs. TLS-enabled loopback gateways also accept plaintext HTTP for sandbox service hostnames by default. |
|
||||
| What you can change | Configure mTLS user authentication, OIDC, or a trusted access proxy at the gateway; enable `server.auth.allowUnauthenticatedUsers=true` only for trusted local Kubernetes development or a fully trusted proxy; disable TLS only for trusted reverse-proxy setups; or disable loopback service HTTP with `--enable-loopback-service-http=false`. |
|
||||
| Risk if relaxed | Disabling TLS removes transport-level protection entirely. Allowing unauthenticated users removes the gateway user-auth boundary and must not be exposed to shared or public networks. Mounting a user client certificate into a sandbox would collapse user and sandbox trust boundaries. Loopback service HTTP is local-only and rejects cross-origin browser requests, but any local process can still reach exposed service URLs directly. |
|
||||
| Recommendation | Keep sandbox identity separate from user identity: expose only the gateway CA to sandboxes and require sandbox JWTs. Use managed OIDC or a trusted access proxy when certificate distribution is unsuitable for shared users. |
|
||||
|
||||
### SSH Tunnel Authentication
|
||||
|
||||
|
||||
Reference in New Issue
Block a user