Access Control

Oxide’s access control system uses predefined role-based permissions organized across three scopes: fleet, silo, and project. This guide is an overview of how authorization works in the Oxide system. Authorization is complex: while there are details that aren’t captured here, this guide should suffice to make sense of nearly everything you see in practice.

Key Terms

Role — A named set of permissions (admin, collaborator, limited_collaborator, viewer)

Actor — A user or group. Roles can be assigned to either.

Resource — An entity with a role policy (fleet, silo, or project)

Role assignment — An entry in a policy giving an actor a role on a resource

Policy — The list of all role assignments for a given resource

Policy Scopes

Users and groups can be assigned roles on three kinds of resource: fleet, silo, or project. Each of those has its own role policy that can be viewed and modified through the API. Viewing a policy typically requires the viewer role on the resource, while updating a policy requires the admin role.

Fleet

The fleet is the entire system managed by the control plane. We do not yet support multiple racks operating as one system ("multirack"), so racks are not aware of each other; each rack is a separate fleet.

Fleet roles govern access to system-level infrastructure and operations. Fleet-scoped API endpoints typically use the /system/* prefix and include things like silo management, hardware, and system updates. Fleet roles do not cascade to resources inside silos, except that fleet admins can view and modify all silos and silo policies. Only fleet administrators can assign fleet roles.

Fleet roles
Role	Description
`admin`	Control of all system resources, including silo management
`collaborator`	Can create and manage silos
`viewer`	Read-only access to system resources

The fleet has no limited_collaborator role. Separating compute from networking only makes sense in the project scope where those resources live, and by extension in the silo scope that governs permissions across all projects.

system_policy_view — View fleet-level role assignments (requires fleet viewer)
system_policy_update — Modify fleet-level role assignments (requires fleet admin)

Silo

The silo is where developer (non-operator) activity happens. This includes projects, instances, networking, storage, and images. Silo roles cascade to all projects in that silo, but note that the silo collaborator role grants the admin role on all projects, not collaborator. This means silo collaborators have complete control over projects, including the ability to manage project-level permissions. Silo administrators can assign silo roles.

Typically all users in a silo will have the viewer role on the silo (e.g., via an everyone group in the IdP). This lets users see all projects in the silo and locate individual projects in the project list. Without the silo viewer role, users can still access projects by referencing them directly using the project name or UUID, but this does not work well because they cannot perform necessary silo-level operations like listing available IP pools.

Silo roles
Role	Description
`admin`	Control over the silo, including all projects and resources
`collaborator`	Create and manage projects. Grants the `admin` role on all projects.
`limited_collaborator`	Grants the `limited_collaborator` role on all projects in the silo
`viewer`	Grants the `viewer` role on all projects; allows users to discover and view projects

Within your own silo, use these endpoints:

policy_view — View silo-level role assignments (requires silo viewer)
policy_update — Modify silo-level role assignments (requires silo admin)

Fleet administrators can view and modify policies for any silo (including silos they don’t belong to) using:

silo_policy_view — View any silo’s role assignments (requires fleet admin)
silo_policy_update — Modify any silo’s role assignments (requires fleet admin)

Project

Projects segment silo resources for finer-grained access control. Different teams might work in different projects within the same silo. Both silo admins and project admins can assign project roles.

Project roles
Role	Description
`admin`	Complete control over the project and all its resources
`collaborator`	Can create and manage all project resources, including networking infrastructure (VPCs, subnets, routers, internet gateways, firewall rules)
`limited_collaborator`	Can manage instances, disks, snapshots, and images and instance-level networking like floating IPs. Cannot change project networking configuration within VPCs (subnets, routers, internet gateways, firewall rules).
`viewer`	Read-only access to project resources

The limited_collaborator role lets operators retain control over network topology and security boundaries while delegating day-to-day instance and storage management to developers.

project_policy_view — View project-level role assignments (requires project viewer)
project_policy_update — Modify project-level role assignments (requires project admin)

How Roles Cascade

To determine a user’s effective role on a resource, the system considers all roles assigned at that level and all ancestor levels, whether assigned directly to the user or to groups they belong to. The effective role is the strongest (most privileged) role from this combined set. Role strength is in the order given in the tables above: admin > collaborator > limited_collaborator > viewer.

For example, if a user has:

Silo viewer role
Project collaborator role on project my-proj

The effective role on project my-proj is collaborator. The effective role on all other projects (assuming there are no other direct role assignments) is viewer.

Role assignments can only add permissions, not reduce them. A collaborator on the silo cannot be downgraded to viewer on a given project by assigning the latter role directly on the project.

Note

In order to maintain tenancy separation between silos, fleet roles do not cascade into silos. A fleets viewer role does not grant viewer access to all silos—fleet roles apply only to fleet-level resources. Fleet admin is the only fleet role that provides cross-silo access, allowing administrators to view and modify any silo’s policy. And even fleet admins cannot access silo-level resources like projects in silos outside their own.

Managing Users and Groups

Users and groups are managed through your identity provider. See the Identity Providers guide for details on:

How users and groups are imported from your IdP (via JIT or SCIM)
Managing local users in silos configured for local authentication
How group memberships affect role assignments

The key point for access control: roles can be assigned to both individual users and groups. Assigning roles to groups is particularly useful because users automatically inherit the appropriate permissions from their groups.

To list users and groups in the current silo, use user_list and group_list. There is no system-level endpoint to list all users in a silo.

Silo Admin Group and Mapped Fleet Roles

When creating a silo with SAML, you can specify an admin_group_name designating a group to automatically receive the silo admin role. Silos can also be configured with mapped_fleet_roles, which grant fleet-level roles to users based on their silo-level roles. These two settings are typically used together to bootstrap fleet access: by setting admin_group_name to an operator group and mapping the silo admin role to the fleet admin role, members of that group automatically become both silo and fleet administrators.

Access Control

Table of Contents