mirror of
https://github.com/NVIDIA/OpenShell.git
synced 2026-10-19 05:50:41 +08:00
Derek Carr
9c019a93f5
* feat(auth): implement RFC 0011 Phase 2 workspace authorization Signed-off-by: Derek Carr <decarr@redhat.com> * fix(auth): address PR review feedback on workspace authorization - Docker e2e: add --health-port and switch readiness probe from `openshell status` to `curl /healthz`, fixing a false-positive readiness check in OIDC mode where the CLI exited 0 without actually contacting the gateway - ListWorkspaces: move membership filtering from post-query N+1 lookups into a SQL EXISTS subquery so pagination applies to the visible set, not the global ordering. Add generic list_with_membership to the persistence layer. - Descriptor validator: reject role/scope fields on unauthenticated and sandbox auth modes, and allow-list workspace_role as user/admin and global_role as platform_admin to catch typos at startup Signed-off-by: Derek Carr <decarr@redhat.com> * fix(server): use authed request in delete telemetry test The workspace authorization added by the Phase 2 auth changes requires a Principal on every delete request. The delete-telemetry test was still using a bare Request::new, so extract_principal failed before the handler could acquire the delete gate, causing a 5-second timeout flake. Signed-off-by: Derek Carr <decarr@redhat.com> * fix(auth): address gator review findings for workspace authorization - Inject unauthenticated-local-dev principal in no-auth gateway mode so handlers that call extract_principal() always find one. - Cap label-selector membership query at MAX_PAGE_SIZE instead of u32::MAX to bound the in-memory read. - Authorize workspace membership before resolving workspace existence in all sandbox RPCs to prevent workspace-name enumeration by non-members. - Remove dead_code allow on AuthorizedWorkspace.workspace now that callers use the normalized name from the authz result. Signed-off-by: Derek Carr <decarr@redhat.com> * fix(auth): close workspace-name oracle and label-selector truncation Swap authorize-before-resolve ordering in 27 handlers across provider.rs, service.rs, policy.rs, and workspace.rs to prevent CWE-203 workspace-name enumeration by non-members. Add combined membership+label SQL query (list_with_membership_and_selector) to both persistence backends so ListWorkspaces with label selectors no longer silently drops results beyond the first page of membership matches. Signed-off-by: Derek Carr <decarr@redhat.com> * test(auth): add non-member rejection and membership+label persistence tests Add comprehensive test coverage for workspace authorization changes: - Non-member rejection tests across all 44 workspace-scoped handlers (sandbox, provider, service, policy, workspace, inference) verifying PERMISSION_DENIED is returned instead of NOT_FOUND to prevent CWE-203 workspace-name oracle - Persistence test for list_with_membership_and_selector verifying SQL-level membership EXISTS + label filtering, multiple predicates, no-match cases, and pagination Signed-off-by: Derek Carr <decarr@redhat.com> * fix(auth): format merged import line in sandbox tests Signed-off-by: Derek Carr <decarr@redhat.com> * fix(auth): address gator re-review findings on workspace authorization - Fix TUI unconditionally setting providers_v2_enabled after provider refresh; read the actual gateway setting via GetGatewayConfig at startup instead - Fix SQLite json_extract with dotted label keys (e.g. example.com/env) by quoting the key in the JSON path - Add authed_request wrappers to upstream OCI identity tests that were missing a principal after rebase - Add test proving GetGatewayConfig is accessible without Platform Admin - Add test for dotted/prefixed Kubernetes-style label key filtering Signed-off-by: Derek Carr <decarr@redhat.com> * fix(auth): address second gator re-review findings - Loosen GetGatewayConfig from platform_admin to scope-only so workspace users can discover providers_v2_enabled during sandbox creation with inferred-provider commands; update proto descriptor, descriptor validation, and RFC 0011 access table - Add validate_label_selector to handle_list_workspaces and escape single quotes in SQLite json_extract interpolation (CWE-89 defense-in-depth) - Re-fetch providers_v2_enabled after TUI gateway switch so the new gateway's capability is reflected - Add e2e test for workspace user with inferred-provider command - Add persistence test for adversarial label keys with SQL injection attempts - Add handler test for invalid label selector rejection in ListWorkspaces Signed-off-by: Derek Carr <decarr@redhat.com> * fix(auth): address third gator review findings - Cap label selector pairs at 64 (CWE-400) to bound SQLite dynamic SQL - Add SCOPE_ONLY_METHODS allowlist for scope-without-role RPCs (CWE-863) - Normalize ID-based data-plane handlers to return NOT_FOUND for unauthorized sandboxes, closing the cross-workspace oracle (CWE-203) - Fix TUI provider profile cache lookup key mismatch for legacy providers with empty profile_workspace - Add whoami to CLI skill reference command tree - Update TUI skill doc with workspace, provider, and settings coverage - Document scope/workspace orthogonality on GetGatewayConfig proto Signed-off-by: Derek Carr <decarr@redhat.com> * fix(auth): extend CWE-203 normalization to policy.rs sandbox handlers GetSandboxConfig and GetSandboxLogs in policy.rs had the same fetch-before-authorize pattern that leaked cross-workspace sandbox existence. Promote fetch_and_authorize_sandbox to pub(super) and use it from both sandbox.rs and policy.rs handlers. Signed-off-by: Derek Carr <decarr@redhat.com> * test(auth): update assertions for CWE-203 sandbox ID normalization Cross-workspace sandbox access via ID-based handlers now returns NOT_FOUND instead of PERMISSION_DENIED to prevent existence inference. Update the unit test and OIDC e2e assertion to match. Signed-off-by: Derek Carr <decarr@redhat.com> * fix(auth): narrow CWE-203 error mapping and correct whoami output formats Only remap PERMISSION_DENIED to NOT_FOUND in fetch_and_authorize_sandbox and RevokeSshSession, letting INTERNAL and UNAUTHENTICATED propagate as-is. Fix whoami --output format values in cli-reference.md to match the actual CLI (table/json/yaml, not text/json). Signed-off-by: Derek Carr <decarr@redhat.com> * fix(ci): share network namespace with Keycloak in containerized CI In GitHub Actions job containers, Docker port publishing lands on the host, not inside the job container. Detect this environment and attach Keycloak to the job container's network namespace instead, with hardened defaults (cap-drop ALL, no-new-privileges, loopback-only listener). Signed-off-by: Derek Carr <decarr@redhat.com> --------- Signed-off-by: Derek Carr <decarr@redhat.com>
197 lines
7.4 KiB
Plaintext
197 lines
7.4 KiB
Plaintext
---
|
|
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
|
|
# SPDX-License-Identifier: Apache-2.0
|
|
title: "Manage Workspaces and Access"
|
|
sidebar-title: "Workspaces and Access"
|
|
description: "Create OpenShell workspaces, assign members, and understand platform and workspace roles."
|
|
keywords: "Generative AI, Cybersecurity, Workspaces, Access Control, RBAC, OIDC, Membership, CLI"
|
|
position: 3
|
|
---
|
|
|
|
An OpenShell workspace is an access and resource isolation boundary. Sandboxes,
|
|
providers, services, policies, settings, and inference routes belong to a
|
|
workspace and are not visible to members of other workspaces.
|
|
|
|
The CLI targets the `default` workspace unless you set `--workspace` or
|
|
`OPENSHELL_WORKSPACE`. The logical OpenShell workspace described here is
|
|
separate from the `/sandbox` filesystem directory inside a sandbox.
|
|
|
|
## Understand the Role Model
|
|
|
|
OpenShell combines an identity-provider role with a membership record for each
|
|
workspace.
|
|
|
|
| Role | Assignment | Access |
|
|
|---|---|---|
|
|
| Platform Admin | The OIDC role configured as `admin_role`. | Manages platform-scoped configuration and every workspace. Platform Admins bypass workspace membership checks. |
|
|
| Workspace Admin | An `admin` membership stored by the gateway for one workspace. | Manages providers, provider profiles, policies, settings, and members in that workspace. |
|
|
| Workspace User | A `user` membership stored by the gateway for one workspace. | Creates and uses sandboxes and services, reads providers, and uses provider attachments in that workspace. |
|
|
|
|
OIDC users also need the role configured as `user_role` for ordinary workspace
|
|
operations. The configured Platform Admin role satisfies this requirement.
|
|
Membership does not grant access to another workspace, and a Workspace Admin
|
|
cannot perform platform-scoped or cross-workspace operations.
|
|
|
|
When the gateway enables scope enforcement through `scopes_claim`, the token
|
|
must also contain the scope required by the operation. Common scopes include
|
|
`workspace:read`, `workspace:write`, `sandbox:read`, `sandbox:write`,
|
|
`provider:read`, `provider:write`, `config:read`, and `config:write`.
|
|
`openshell:all` satisfies every scope requirement. For OIDC and scope
|
|
configuration, refer to [Gateway Authentication](/reference/gateway-auth).
|
|
|
|
The following table summarizes common operations.
|
|
|
|
| Operation | Platform Admin | Workspace Admin | Workspace User |
|
|
|---|---|---|---|
|
|
| Create or delete a workspace | Any workspace | No | No |
|
|
| View a workspace or list workspaces | All workspaces | Assigned workspaces | Assigned workspaces |
|
|
| List workspace members | Any workspace | Assigned workspace | Assigned workspace |
|
|
| Add Workspace Users or remove members | Any workspace | Assigned workspace | No |
|
|
| Assign the Workspace Admin role | Any workspace | No | No |
|
|
| Create, use, or delete sandboxes and services | Any workspace | Assigned workspace | Assigned workspace |
|
|
| Create, update, or delete providers | Any workspace | Assigned workspace | No |
|
|
| Change workspace policy or settings | Any workspace | Assigned workspace | No |
|
|
| Manage platform profiles or global configuration | Yes | No | No |
|
|
| List resources across workspaces | Yes | No | No |
|
|
|
|
<Note>
|
|
Local gateways without OIDC role configuration treat authenticated users as
|
|
Platform Admins. Configure OIDC roles and workspace membership for shared
|
|
gateways.
|
|
</Note>
|
|
|
|
## Inspect Your Identity
|
|
|
|
Use the identity validated by the gateway when an administrator needs your
|
|
membership subject.
|
|
|
|
```shell
|
|
openshell whoami
|
|
openshell whoami --output json
|
|
```
|
|
|
|
The `subject` field is the stable identity used in workspace membership
|
|
records. Each user can run this command even when they do not belong to a
|
|
workspace.
|
|
|
|
## Create a Workspace and Add Members
|
|
|
|
A Platform Admin creates workspaces and assigns the first Workspace Admin.
|
|
The gateway creates the `default` workspace automatically, but it does not add
|
|
OIDC users to that workspace automatically.
|
|
|
|
Create a workspace:
|
|
|
|
```shell
|
|
openshell workspace create --name team-ml
|
|
```
|
|
|
|
Ask the intended Workspace Admin to run `openshell whoami`, then add the
|
|
reported subject:
|
|
|
|
```shell
|
|
openshell workspace member add \
|
|
--workspace team-ml \
|
|
--subject 'oidc-subject-for-admin' \
|
|
--role admin
|
|
```
|
|
|
|
The Workspace Admin can add Workspace Users:
|
|
|
|
```shell
|
|
openshell workspace member add \
|
|
--workspace team-ml \
|
|
--subject 'oidc-subject-for-user' \
|
|
--role user
|
|
```
|
|
|
|
Only a Platform Admin can assign the `admin` membership role. A Workspace
|
|
Admin can add `user` members and remove members in their assigned workspace.
|
|
|
|
## List and Remove Members
|
|
|
|
All members can inspect membership in their workspace. Workspace Admins and
|
|
Platform Admins can remove members.
|
|
|
|
```shell
|
|
openshell workspace member list --workspace team-ml
|
|
|
|
openshell workspace member remove \
|
|
--workspace team-ml \
|
|
--subject 'oidc-subject-for-user'
|
|
```
|
|
|
|
To change a member's role, remove the existing membership and add it again
|
|
with the new role. A Platform Admin must perform any change to `admin`.
|
|
|
|
## Target a Workspace
|
|
|
|
Pass `--workspace` to scope a resource operation. The flag is global, so it
|
|
can appear before or after the subcommand.
|
|
|
|
```shell
|
|
openshell sandbox list --workspace team-ml
|
|
openshell provider list --workspace team-ml
|
|
openshell sandbox create --workspace team-ml --name research -- bash
|
|
```
|
|
|
|
Set a default for the current shell with `OPENSHELL_WORKSPACE`:
|
|
|
|
```shell
|
|
export OPENSHELL_WORKSPACE=team-ml
|
|
openshell sandbox list
|
|
```
|
|
|
|
An empty workspace value resolves to `default`. It never means all
|
|
workspaces.
|
|
|
|
Platform Admins can opt into cross-workspace list operations:
|
|
|
|
```shell
|
|
openshell sandbox list --all-workspaces
|
|
openshell provider list --all-workspaces
|
|
openshell service list --all-workspaces
|
|
```
|
|
|
|
Provider profiles and policy also have explicit `--global` operations. Those
|
|
operations target platform scope and require Platform Admin access. A
|
|
Workspace Admin should use `--workspace` for workspace-scoped profiles and
|
|
configuration.
|
|
|
|
## Diagnose Access Denials
|
|
|
|
If `openshell workspace list` returns no rows, the authenticated subject has no
|
|
workspace memberships. Run `openshell whoami` and send the `subject` value to
|
|
a Platform Admin.
|
|
|
|
Workspace authorization errors include a copyable membership command. A
|
|
non-member denial suggests `--role user`. If an operation requires Workspace
|
|
Admin access, the denial suggests `--role admin`; only a Platform Admin can run
|
|
that assignment successfully.
|
|
|
|
If the membership is correct but the request is still denied, inspect `roles`
|
|
and `scopes` with `openshell whoami --output json`. Confirm that the token has
|
|
the configured OIDC user role and, when scope enforcement is enabled, the
|
|
scope required by the operation.
|
|
|
|
## Delete a Workspace
|
|
|
|
Only a Platform Admin can delete a workspace. The `default` workspace cannot
|
|
be deleted.
|
|
|
|
```shell
|
|
openshell workspace delete team-ml
|
|
```
|
|
|
|
A custom workspace must not contain sandboxes, providers, provider profiles,
|
|
services, SSH sessions, settings, policies, draft policy chunks, or credential
|
|
refresh state. Remove those resources before retrying deletion. OpenShell
|
|
removes membership records and inference routes as part of successful
|
|
workspace deletion.
|
|
|
|
## Next Steps
|
|
|
|
- To configure OIDC roles and scopes, refer to [Gateway Authentication](/reference/gateway-auth).
|
|
- To create resources in a workspace, refer to [Manage Sandboxes](/sandboxes/manage-sandboxes).
|
|
- To manage workspace credentials, refer to [Providers](/sandboxes/manage-providers).
|