Add limited collaborator role (#9299)

This PR adds a new role, of a "limited collaborator". The role
essentially has restrictions on actions on networking resources while
allowing normal collaborator permissions on compute resources.

The `limited collaborator` role can `read` and `list_children`,
but can _not_ `create_children`, or `modify` (or delete) the following
resources:
- VPC
- Subnet
- Firewall Rule
- Custom Router
- Route
- Internet Gateway (including attach/detach IP pools and IP addresses)

Limited Collaborators will still be allowed full create / modify /
delete permissions on these resources:
- Floating IP
- Instance Network Interfaces
- compute resources

---------

Co-authored-by: David Pacheco <[email protected]>

Author: charliepark

docs/adding-an-endpoint.adoc

@@ -32,7 +32,7 @@ this document should act as a jumping-off point.
 * Add helper functions to `LookupPath` to make it possible to fetch the resource by either UUID or name (https://github.com/oxidecomputer/omicron/blob/1dfe47c1b3122bc4f32a9c517cb31b1600581ea2/nexus/src/db/lookup.rs#L225-L237[Example])
 ** These are often named `pub fn <my_resource>_name`, or `pub fn <my_resource>_id`
 * Use the https://github.com/oxidecomputer/omicron/blob/main/nexus/authz-macros/src/lib.rs[`authz_resource!` macro] to define a new `authz::...` structure, which is returned from the **Lookup** functions (https://github.com/oxidecomputer/omicron/blob/1dfe47c1b3122bc4f32a9c517cb31b1600581ea2/nexus/src/authz/api_resources.rs#L758-L764[Example])
-** If you define `polar_snippet = InProject` (for developer resources) or `polar_snippet = FleetChild` (for operator resources), most of the polar policy is automatically defined for you
+** If you define `polar_snippet = InProjectLimited` or `polar_snippet = InProjectFull` (for developer resources) or `polar_snippet = FleetChild` (for operator resources), most of the polar policy is automatically defined for you
 ** If you define `polar_snippet = Custom`, you should edit the omicron.polar file to describe the authorization policy for your object (https://github.com/oxidecomputer/omicron/blob/1dfe47c1b3122bc4f32a9c517cb31b1600581ea2/nexus/src/authz/omicron.polar#L376-L393[Example])
 * Either way, you should add reference the new resource when https://github.com/oxidecomputer/omicron/blob/1dfe47c1b3122bc4f32a9c517cb31b1600581ea2/nexus/src/authz/oso_generic.rs#L119-L148[constructing the Oso structure]
 

nexus/auth/src/authz/api_resources.rs

@@ -931,6 +931,55 @@ impl AuthorizedResource for SiloUserTokenList {
     }
 }
 
+/// Synthetic resource describing the list of VPCs in a Project
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct VpcList(Project);
+
+impl VpcList {
+    pub fn new(project: Project) -> VpcList {
+        VpcList(project)
+    }
+
+    pub fn project(&self) -> &Project {
+        &self.0
+    }
+}
+
+impl oso::PolarClass for VpcList {
+    fn get_polar_class_builder() -> oso::ClassBuilder<Self> {
+        oso::Class::builder()
+            .with_equality_check()
+            .add_attribute_getter("project", |list: &VpcList| list.0.clone())
+    }
+}
+
+impl AuthorizedResource for VpcList {
+    fn load_roles<'fut>(
+        &'fut self,
+        opctx: &'fut OpContext,
+        authn: &'fut authn::Context,
+        roleset: &'fut mut RoleSet,
+    ) -> futures::future::BoxFuture<'fut, Result<(), Error>> {
+        // There are no roles on this resource, but we still need to load the
+        // Project-related roles.
+        self.project().load_roles(opctx, authn, roleset)
+    }
+
+    fn on_unauthorized(
+        &self,
+        _: &Authz,
+        error: Error,
+        _: AnyActor,
+        _: Action,
+    ) -> Error {
+        error
+    }
+
+    fn polar_class(&self) -> oso::Class {
+        Self::get_polar_class()
+    }
+}
+
 #[derive(Clone, Copy, Debug)]
 pub struct UpdateTrustRootList;
 
@@ -1130,124 +1179,150 @@ impl ApiResourceWithRolesType for Project {
     type AllowedRoles = ProjectRole;
 }
 
+// ============================================================================
+// Project Resources - Non-Networking (InProjectLimited)
+//
+// These resources can be created and modified by users with the
+// "limited-collaborator" role and above. These are "regular" project resources
+// that users can work with without needing permission to reconfigure network
+// infrastructure.
+//
+// Examples: Instances, Disks, Snapshots, Images, Floating IPs
+// ============================================================================
+
 authz_resource! {
     name = "Disk",
     parent = "Project",
     primary_key = Uuid,
     roles_allowed = false,
-    polar_snippet = InProject,
+    polar_snippet = InProjectLimited,
 }
 
 authz_resource! {
     name = "ProjectImage",
     parent = "Project",
     primary_key = Uuid,
     roles_allowed = false,
-    polar_snippet = InProject,
+    polar_snippet = InProjectLimited,
 }
 
 authz_resource! {
     name = "Snapshot",
     parent = "Project",
     primary_key = Uuid,
     roles_allowed = false,
-    polar_snippet = InProject,
+    polar_snippet = InProjectLimited,
 }
 
 authz_resource! {
     name = "Instance",
     parent = "Project",
     primary_key = Uuid,
     roles_allowed = false,
-    polar_snippet = InProject,
+    polar_snippet = InProjectLimited,
 }
 
 authz_resource! {
     name = "AffinityGroup",
     parent = "Project",
     primary_key = Uuid,
     roles_allowed = false,
-    polar_snippet = InProject,
+    polar_snippet = InProjectLimited,
 }
 
 authz_resource! {
     name = "AntiAffinityGroup",
     parent = "Project",
     primary_key = Uuid,
     roles_allowed = false,
-    polar_snippet = InProject,
+    polar_snippet = InProjectLimited,
 }
 
 authz_resource! {
     name = "InstanceNetworkInterface",
     parent = "Instance",
     primary_key = Uuid,
     roles_allowed = false,
-    polar_snippet = InProject,
-}
+    polar_snippet = InProjectLimited,
+}
+
+// ============================================================================
+// Project Resources - Networking Infrastructure (InProjectFull)
+//
+// These resources require the full "collaborator" role to create or modify.
+// Users with only the "limited-collaborator" role can *read* these resources
+// (via viewer inheritance) but cannot create or modify them.
+//
+// This distinction allows organizations to restrict who can reconfigure the
+// network topology while still allowing those users to work with compute
+// resources (instances, disks, etc.) within the existing network.
+//
+// Resources in this category: VPCs, Subnets, Routers, Router Routes,
+// Internet Gateways, and their child resources (IP pools, IP addresses)
+// ============================================================================
 
 authz_resource! {
     name = "Vpc",
     parent = "Project",
     primary_key = Uuid,
     roles_allowed = false,
-    polar_snippet = InProject,
+    polar_snippet = InProjectFull,
 }
 
 authz_resource! {
     name = "VpcRouter",
     parent = "Vpc",
     primary_key = Uuid,
     roles_allowed = false,
-    polar_snippet = InProject,
+    polar_snippet = InProjectFull,
 }
 
 authz_resource! {
     name = "RouterRoute",
     parent = "VpcRouter",
     primary_key = Uuid,
     roles_allowed = false,
-    polar_snippet = InProject,
+    polar_snippet = InProjectFull,
 }
 
 authz_resource! {
     name = "VpcSubnet",
     parent = "Vpc",
     primary_key = Uuid,
     roles_allowed = false,
-    polar_snippet = InProject,
+    polar_snippet = InProjectFull,
 }
 
 authz_resource! {
     name = "InternetGateway",
     parent = "Vpc",
     primary_key = Uuid,
     roles_allowed = false,
-    polar_snippet = InProject,
+    polar_snippet = InProjectFull,
 }
 
 authz_resource! {
     name = "InternetGatewayIpPool",
     parent = "InternetGateway",
     primary_key = Uuid,
     roles_allowed = false,
-    polar_snippet = InProject,
+    polar_snippet = InProjectFull,
 }
 
 authz_resource! {
     name = "InternetGatewayIpAddress",
     parent = "InternetGateway",
     primary_key = Uuid,
     roles_allowed = false,
-    polar_snippet = InProject,
+    polar_snippet = InProjectFull,
 }
 
 authz_resource! {
     name = "FloatingIp",
     parent = "Project",
     primary_key = Uuid,
     roles_allowed = false,
-    polar_snippet = InProject,
+    polar_snippet = InProjectLimited,
 }
 
 // Customer network integration resources nested below "Fleet"

nexus/auth/src/authz/omicron.polar

@@ -63,13 +63,15 @@ has_role(actor: AuthenticatedActor, role: String, resource: Resource)
 # - fleet.collaborator    (can manage Silos)
 # - fleet.viewer          (can read most non-siloed resources in the system)
 # - silo.admin            (superuser for the silo)
-# - silo.collaborator     (can create and own Organizations)
-# - silo.viewer           (can read most resources within the Silo)
+# - silo.collaborator     (can create and own Organizations; grants project.admin on all projects)
+# - silo.limited-collaborator (grants project.limited-collaborator on all projects)
+# - silo.viewer           (can read most resources within the Silo; grants project.viewer)
 # - organization.admin    (complete control over an organization)
 # - organization.collaborator (can manage Projects)
 # - organization.viewer   (can read most resources within the Organization)
 # - project.admin         (complete control over a Project)
-# - project.collaborator  (can manage all resources within the Project)
+# - project.collaborator  (can manage all resources within the Project, including networking)
+# - project.limited-collaborator (can manage compute resources, but not networking resources)
 # - project.viewer        (can read most resources within the Project)
 #
 # Outside the Silo/Organization/Project hierarchy, we (currently) treat most
@@ -125,10 +127,11 @@ resource Silo {
 	    "read",
 	    "create_child",
 	];
-	roles = [ "admin", "collaborator", "viewer" ];
+	roles = [ "admin", "collaborator", "limited-collaborator", "viewer" ];
 
 	# Roles implied by other roles on this resource
-	"viewer" if "collaborator";
+	"viewer" if "limited-collaborator";
+	"limited-collaborator" if "collaborator";
 	"collaborator" if "admin";
 
 	# Permissions granted directly by roles on this resource
@@ -184,21 +187,29 @@ resource Project {
 	    "read",
 	    "create_child",
 	];
-	roles = [ "admin", "collaborator", "viewer" ];
+	roles = [ "admin", "collaborator", "limited-collaborator", "viewer" ];
 
 	# Roles implied by other roles on this resource
-	"viewer" if "collaborator";
+	# Role hierarchy: admin > collaborator > limited-collaborator > viewer
+	#
+	# The "limited-collaborator" role can create/modify non-networking
+	# resources (instances, disks, etc.) but cannot create/modify networking
+	# infrastructure (VPCs, subnets, routers, internet gateways).
+	# See nexus/authz-macros for InProjectLimited vs InProjectFull.
+	"viewer" if "limited-collaborator";
+	"limited-collaborator" if "collaborator";
 	"collaborator" if "admin";
 
 	# Permissions granted directly by roles on this resource
 	"list_children" if "viewer";
 	"read" if "viewer";
-	"create_child" if "collaborator";
+	"create_child" if "limited-collaborator";
 	"modify" if "admin";
 
 	# Roles implied by roles on this resource's parent (Silo)
 	relations = { parent_silo: Silo };
 	"admin" if "collaborator" on "parent_silo";
+	"limited-collaborator" if "limited-collaborator" on "parent_silo";
 	"viewer" if "viewer" on "parent_silo";
 }
 has_relation(silo: Silo, "parent_silo", project: Project)
@@ -797,3 +808,20 @@ has_relation(silo: Silo, "parent_silo", scim_client_bearer_token_list: ScimClien
 	if scim_client_bearer_token_list.silo = silo;
 has_relation(fleet: Fleet, "parent_fleet", collection: ScimClientBearerTokenList)
 	if collection.silo.fleet = fleet;
+
+# VpcList is a synthetic resource for controlling VPC creation.
+# Unlike other project resources, VPC creation requires the full "collaborator"
+# role rather than "limited-collaborator", enforcing the networking restriction.
+# This allows organizations to restrict who can reconfigure the network topology
+# while still allowing users with limited-collaborator to work with compute
+# resources (instances, disks, etc.) within the existing network.
+resource VpcList {
+	permissions = [ "list_children", "create_child" ];
+
+	relations = { containing_project: Project };
+
+	"list_children" if "read" on "containing_project";
+	"create_child" if "collaborator" on "containing_project";
+}
+has_relation(project: Project, "containing_project", collection: VpcList)
+	if collection.project = project;

nexus/auth/src/authz/oso_generic.rs

@@ -110,6 +110,7 @@ pub fn make_omicron_oso(log: &slog::Logger) -> Result<OsoInit, anyhow::Error> {
         Fleet::get_polar_class(),
         Inventory::get_polar_class(),
         IpPoolList::get_polar_class(),
+        VpcList::get_polar_class(),
         ConsoleSessionList::get_polar_class(),
         DeviceAuthRequestList::get_polar_class(),
         QuiesceState::get_polar_class(),

nexus/authz-macros/outputs/instance.txt

@@ -41,7 +41,7 @@ impl Instance {
     pub(super) fn init() -> Init {
         use oso::PolarClass;
         Init {
-            polar_snippet: "\n                resource Instance {\n                    permissions = [\n                        \"list_children\",\n                        \"modify\",\n                        \"read\",\n                        \"create_child\",\n                    ];\n\n                    relations = { containing_project: Project };\n                    \"list_children\" if \"viewer\" on \"containing_project\";\n                    \"read\" if \"viewer\" on \"containing_project\";\n                    \"modify\" if \"collaborator\" on \"containing_project\";\n                    \"create_child\" if \"collaborator\" on \"containing_project\";\n                }\n\n                has_relation(parent: Project, \"containing_project\", child: Instance)\n                        if child.project = parent;\n            ",
+            polar_snippet: "\n                resource Instance {\n                    permissions = [\n                        \"list_children\",\n                        \"modify\",\n                        \"read\",\n                        \"create_child\",\n                    ];\n\n                    relations = { containing_project: Project };\n                    \"list_children\" if \"viewer\" on \"containing_project\";\n                    \"read\" if \"viewer\" on \"containing_project\";\n                    \"modify\" if \"limited-collaborator\" on \"containing_project\";\n                    \"create_child\" if \"limited-collaborator\" on \"containing_project\";\n                }\n\n                has_relation(parent: Project, \"containing_project\", child: Instance)\n                        if child.project = parent;\n            ",
             polar_class: Instance::get_polar_class(),
         }
     }