b/339522351 Add documentation for resource conditions (#402)

README.md

@@ -74,6 +74,9 @@ As an administrator, you can grant a role (to a user or group) and make it _elig
 You can create the binding for a specific project, or for an entire folder. Instead of granting eligible
 access to individual users, you can also use groups.
 
+To limit access to a subset of resources, you can also include a [resource condition](https://googlecloudplatform.github.io/jit-access/resource-conditions/)
+in the IAM binding.
+
 
 <img src='doc/pix.gif' width='100%' height='1'>
 

doc/site/sources/docs/index.md

@@ -69,6 +69,9 @@ As an administrator, you can grant a role (to a user or group) and make it _elig
 You can create the binding for a specific project, or for an entire folder. Instead of granting eligible
 access to individual users, you can also use groups.
 
+To limit access to a subset of resources, you can also include a [resource condition](resource-conditions.md)
+in the IAM binding.
+
 <img src='images/pix.gif' style='width: 100%; height: 1px'>
 
 

doc/site/sources/docs/resource-conditions.md

@@ -0,0 +1,70 @@
+# Resource conditions
+
+JIT Access manages access by modifying the IAM policy of projects. When a user activates a role using
+JIT Access, then, by default, that role applies to all resources in the project.
+
+Resource conditions let you constrain the set of resources within a project that a role should apply to.
+For example, you can use a resource condition to restrict a user's access to certain types of Compute Engine resources,
+or to resources within a certain zone.
+
+To use a resource condition, you add an extra clause to the IAM condition of an eligible role binding:
+
+*   `has({}.jitAccessConstraint) && resource-condition`
+
+*   `has({}.multiPartyApprovalConstraint) && resource-condition`
+
+Where `resource-condition` is a valid [IAM condition :octicons-link-external-16:](https://cloud.google.com/iam/docs/conditions-overview).
+
+
+!!! note
+
+    You can change the order of clauses. For example `has({}.jitAccessConstraint) && [resource condition]`
+    and `[resource condition] && has({}.jitAccessConstraint)` are equivalent.
+
+To use resource conditions, you must the [`AssetInventory` catalog](configure-catalogs.md).
+
+## Examples
+
+The following are examples for role bindings that use a resource condition to constrain access to certain
+resources. 
+
+*   Grant _Secret Accessor_ access for a specific Secret Manager secret, subject to self-approval:
+
+    **Role**: `roles/secretmanager.secretAccessor`
+
+    **Condition**:
+
+        // Require self-approval
+        has({}.jitAccessConstraint) &&
+
+        // Secret
+        resource.name == "projects/sample-project/secrets/sample-secret"
+
+*   Grant _Compute Instance Admin_ access for Compute Engine VMs in `asia-southeast1-a`, subject to multi-party approval:
+
+    **Role**: `roles/compute.instanceAdmin.v1`
+
+    **Condition**:
+
+        // Require multi-party approval
+        has({}.multiPartyApprovalConstraint) &&
+
+        // asia-southeast1-a only
+        resource.name.startsWith("projects/sample-project/zones/asia-southeast1-a/instances/")
+
+
+*   Grant _Compute Admin_ access for Compute Engine disks and images, subject to multi-party approval:
+
+    **Role**: `roles/compute.admin`
+
+    **Condition**:
+
+        // Require multi-party approval
+        has({}.multiPartyApprovalConstraint) &&
+
+        // Disks and images
+        (resource.type == "compute.googleapis.com/Disk" || resource.type == "compute.googleapis.com/Image")
+
+!!! note
+
+    Lines starting with `//` are comments and are ignored by JIT Access.

doc/site/sources/mkdocs.yml

@@ -78,6 +78,8 @@ nav:
       - 'Configure catalogs': configure-catalogs.md
       - 'Access VPC service perimeters': configure-vpcsc.md
       - 'Use health checks': health-checks.md
+    - 'Use JIT Access':
+      - 'Resource conditions': resource-conditions.md
     - 'Customize JIT Access':
       - 'Configuration options': configuration-options.md
     - 'Extend JIT Access':