From b0031b71e003ea99bb36ac44562566e7cfae27ed Mon Sep 17 00:00:00 2001 From: Sheen Capadngan Date: Tue, 5 Nov 2024 01:21:35 +0800 Subject: [PATCH 1/3] doc: updated internal permission docs --- docs/internals/permissions.mdx | 173 ++++++++++++++++++++++----------- 1 file changed, 116 insertions(+), 57 deletions(-) diff --git a/docs/internals/permissions.mdx b/docs/internals/permissions.mdx index 3eb7059d2..691e739ef 100644 --- a/docs/internals/permissions.mdx +++ b/docs/internals/permissions.mdx @@ -7,77 +7,136 @@ description: "Infisical's permissions system provides granular access control." The Infisical permissions system is based on a role-based access control (RBAC) model. The system allows you to define roles and assign them to users and machines. Each role has a set of permissions that define what actions a user can perform. -Permissions are built on a subject-action-object model. The subject is the resource permission is being applied to, the action is what the permission allows. +Permissions are built on a subject-action-object model. The subject is the resource the permission is being applied to, the action is what the permission allows. An example of a subject/action combination would be `secrets/read`. This permission allows the subject to read secrets. -Currently Infisical supports 4 actions: -1. `read`, allows the subject to read the object. -2. `create`, allows the subject to create the object. -3. `edit`, allows the subject to edit the object. -4. `delete`, allows the subject to delete the object. - -Most subjects support all 4 actions, but some subjects only support a subset of actions. Please view the table below for a list of subjects and the actions they support. - +Refer to the table below for a list of subjects and the actions they support. ## Subjects and Actions + - Not all actions are applicable to all subjects. As an example, the `secrets-rollback` subject only supports `read`, and `create` as actions. While `secrets` support `read`, `create`, `edit`, `delete`. + Not all actions are applicable to all subjects. As an example, the + `secrets-rollback` subject only supports `read`, and `create` as actions. + While `secrets` support `read`, `create`, `edit`, `delete`. - | Subject | Actions | - |-----------------------------|---------| - | `secrets` | `read`, `create`, `edit`, `delete` | - | `secret-approval` | `read`, `create`, `edit`, `delete` | - | `secret-rotation` | `read`, `create`, `edit`, `delete` | - | `secret-rollback` | `read`, `create` | - | `member` | `read`, `create`, `edit`, `delete` | - | `groups` | `read`, `create`, `edit`, `delete` | - | `role` | `read`, `create`, `edit`, `delete` | - | `integrations` | `read`, `create`, `edit`, `delete` | - | `webhooks` | `read`, `create`, `edit`, `delete` | - | `identity` | `read`, `create`, `edit`, `delete` | - | `service-tokens` | `read`, `create`, `edit`, `delete` | - | `settings` | `read`, `create`, `edit`, `delete` | - | `environments` | `read`, `create`, `edit`, `delete` | - | `tags` | `read`, `create`, `edit`, `delete` | - | `audit-logs` | `read`, `create`, `edit`, `delete` | - | `ip-allowlist` | `read`, `create`, `edit`, `delete` | - | `certificate-authorities` | `read`, `create`, `edit`, `delete` | - | `certificates` | `read`, `create`, `edit`, `delete` | - | `certificate-templates` | `read`, `create`, `edit`, `delete` | - | `pki-alerts` | `read`, `create`, `edit`, `delete` | - | `pki-collections` | `read`, `create`, `edit`, `delete` | - | `workspace` | `edit`, `delete` | - | `kms` | `edit` | +| Subject | Actions | +| ------------------------- | ----------------------------------------------------------------------------------------------------------- | +| `role` | `read`, `create`, `edit`, `delete` | +| `member` | `read`, `create`, `edit`, `delete` | +| `groups` | `read`, `create`, `edit`, `delete` | +| `settings` | `read`, `create`, `edit`, `delete` | +| `integrations` | `read`, `create`, `edit`, `delete` | +| `webhooks` | `read`, `create`, `edit`, `delete` | +| `service-tokens` | `read`, `create`, `edit`, `delete` | +| `environments` | `read`, `create`, `edit`, `delete` | +| `tags` | `read`, `create`, `edit`, `delete` | +| `audit-logs` | `read`, `create`, `edit`, `delete` | +| `ip-allowlist` | `read`, `create`, `edit`, `delete` | +| `workspace` | `edit`, `delete` | +| `secrets` | `read`, `create`, `edit`, `delete` | +| `secret-folders` | `read`, `create`, `edit`, `delete` | +| `secret-imports` | `read`, `create`, `edit`, `delete` | +| `dynamic-secrets` | `read-root-credential`, `create-root-credential`, `edit-root-credential`, `delete-root-credential`, `lease` | +| `secret-rollback` | `read`, `create` | +| `secret-approval` | `read`, `create`, `edit`, `delete` | +| `secret-rotation` | `read`, `create`, `edit`, `delete` | +| `identity` | `read`, `create`, `edit`, `delete` | +| `certificate-authorities` | `read`, `create`, `edit`, `delete` | +| `certificates` | `read`, `create`, `edit`, `delete` | +| `certificate-templates` | `read`, `create`, `edit`, `delete` | +| `pki-alerts` | `read`, `create`, `edit`, `delete` | +| `pki-collections` | `read`, `create`, `edit`, `delete` | +| `kms` | `edit` | +| `cmek` | `read`, `create`, `edit`, `delete`, `encrypt`, `decrypt` | - These details are especially useful if you're using the API to [create new project roles](../api-reference/endpoints/project-roles/create). - The rules outlined on this page, also apply when using our Terraform Provider to manage your Infisical project roles, or any other of our clients that manage project roles. - - - Not all actions are applicable to all subjects. As an example, the `workspace` subject only supports `read`, and `create` as actions. While `member` support `read`, `create`, `edit`, `delete`. - + + Not all actions are applicable to all subjects. As an example, the `workspace` + subject only supports `read`, and `create` as actions. While `member` support + `read`, `create`, `edit`, `delete`. + + +| Subject | Actions | +| ------------------ | ---------------------------------- | +| `workspace` | `read`, `create` | +| `role` | `read`, `create`, `edit`, `delete` | +| `member` | `read`, `create`, `edit`, `delete` | +| `secret-scanning` | `read`, `create`, `edit`, `delete` | +| `settings` | `read`, `create`, `edit`, `delete` | +| `incident-account` | `read`, `create`, `edit`, `delete` | +| `sso` | `read`, `create`, `edit`, `delete` | +| `scim` | `read`, `create`, `edit`, `delete` | +| `ldap` | `read`, `create`, `edit`, `delete` | +| `groups` | `read`, `create`, `edit`, `delete` | +| `billing` | `read`, `create`, `edit`, `delete` | +| `identity` | `read`, `create`, `edit`, `delete` | +| `kms` | `read` | - | Subject | Actions | - |-----------------------------|------------------------------------| - | `workspace` | `read`, `create` | - | `role` | `read`, `create`, `edit`, `delete` | - | `member` | `read`, `create`, `edit`, `delete` | - | `secret-scanning` | `read`, `create`, `edit`, `delete` | - | `settings` | `read`, `create`, `edit`, `delete` | - | `incident-account` | `read`, `create`, `edit`, `delete` | - | `sso` | `read`, `create`, `edit`, `delete` | - | `scim` | `read`, `create`, `edit`, `delete` | - | `ldap` | `read`, `create`, `edit`, `delete` | - | `groups` | `read`, `create`, `edit`, `delete` | - | `billing` | `read`, `create`, `edit`, `delete` | - | `identity` | `read`, `create`, `edit`, `delete` | - | `kms` | `read` | - \ No newline at end of file + + +## Inversion + +Permission inversion allows you to explicitly deny actions instead of allowing them. This is supported for the following subjects: + +- secrets +- secret-folders +- secret-imports +- dynamic-secrets +- cmek + +When a permission is inverted, it changes from an "allow" rule to a "deny" rule. For example: + +```typescript +// Regular permission - allows reading secrets +{ + subject: "secrets", + action: ["read"] +} + +// Inverted permission - denies reading secrets +{ + subject: "secrets", + action: ["read"], + inverted: true +} +``` + +## Conditions + +Certain subjects support conditional permissions that allow for more granular access control. These subjects are: + +- secrets +- secret-folders +- secret-imports +- dynamic-secrets + +### Properties + +Conditions can be applied to the following properties: + +- `environment`: Control access based on environment slugs +- `secretPath`: Control access based on secret paths +- `secretName`: Control access based on secret names +- `secretTags`: Control access based on tags (only supports $in operator) + +### Operators + +The following operators are available for conditions: + +| Operator | Description | Example | +| -------- | ---------------------------------- | ----------------------------------------------------- | +| `$eq` | Equal | `{ environment: { $eq: "production" } }` | +| `$ne` | Not equal | `{ environment: { $ne: "development" } }` | +| `$in` | Matches any value in array | `{ environment: { $in: ["staging", "production"] } }` | +| `$glob` | Pattern matching using glob syntax | `{ secretPath: { $glob: "/app/\*" } }` | + +These details are especially useful if you're using the API to [create new project roles](../api-reference/endpoints/project-roles/create). +The rules outlined on this page, also apply when using our Terraform Provider to manage your Infisical project roles, or any other of our clients that manage project roles. From 4f1fe8a9fafdca4b1be4b8ee7b9958cd85b9f4b6 Mon Sep 17 00:00:00 2001 From: Sheen Capadngan Date: Tue, 5 Nov 2024 01:37:26 +0800 Subject: [PATCH 2/3] doc: updated overview --- docs/internals/permissions.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/internals/permissions.mdx b/docs/internals/permissions.mdx index 691e739ef..045e4661f 100644 --- a/docs/internals/permissions.mdx +++ b/docs/internals/permissions.mdx @@ -111,7 +111,7 @@ When a permission is inverted, it changes from an "allow" rule to a "deny" rule. ## Conditions -Certain subjects support conditional permissions that allow for more granular access control. These subjects are: +Conditions allow you to create more granular permissions by specifying criteria that must be met for the permission to apply. This is supported for the following subjects: - secrets - secret-folders From 3e16d7e1603f19511e70a192cf525fc7d44532c7 Mon Sep 17 00:00:00 2001 From: Sheen Capadngan Date: Thu, 7 Nov 2024 18:51:26 +0800 Subject: [PATCH 3/3] doc: added migration tips --- docs/internals/permissions.mdx | 71 +++++++++++++++++++++++++++++++++- 1 file changed, 70 insertions(+), 1 deletion(-) diff --git a/docs/internals/permissions.mdx b/docs/internals/permissions.mdx index 045e4661f..1fce09def 100644 --- a/docs/internals/permissions.mdx +++ b/docs/internals/permissions.mdx @@ -3,7 +3,7 @@ title: "Permissions" description: "Infisical's permissions system provides granular access control." --- -## Summary +## Overview The Infisical permissions system is based on a role-based access control (RBAC) model. The system allows you to define roles and assign them to users and machines. Each role has a set of permissions that define what actions a user can perform. @@ -140,3 +140,72 @@ The following operators are available for conditions: These details are especially useful if you're using the API to [create new project roles](../api-reference/endpoints/project-roles/create). The rules outlined on this page, also apply when using our Terraform Provider to manage your Infisical project roles, or any other of our clients that manage project roles. + +## Migrating from permission V1 to permission V2 + +When upgrading to V2 permissions (i.e. when moving from using the `permissions` to `permissions_v2` field in your Terraform configurations, or upgrading to the V2 permission API), you'll need to update your permission structure as follows: + +Any permissions for `secrets` should be expanded to include equivalent permissions for: + +- `secret-imports` +- `secret-folders` (except for read permissions) +- `dynamic-secrets` + +For dynamic secrets, the actions need to be mapped differently: + +- `read` → `read-root-credential` +- `create` → `create-root-credential` +- `edit` → `edit-root-credential` (also adds `lease` permission) +- `delete` → `delete-root-credential` + +Example: + +```hcl +# Old V1 configuration +resource "infisical_project_role" "example" { + name = "example" + permissions = [ + { + subject = "secrets" + action = "read" + }, + { + subject = "secrets" + action = "edit" + } + ] +} + +# New V2 configuration +resource "infisical_project_role" "example" { + name = "example" + permissions_v2 = [ + # Original secrets permission + { + subject = "secrets" + action = ["read", "edit"] + inverted = false + }, + # Add equivalent secret-imports permission + { + subject = "secret-imports" + action = ["read", "edit"] + inverted = false + }, + # Add secret-folders permission (without read) + { + subject = "secret-folders" + action = ["edit"] + inverted = false + }, + # Add dynamic-secrets permission with mapped actions + { + subject = "dynamic-secrets" + action = ["read-root-credential", "edit-root-credential", "lease"] + inverted = false + } + ] +} +``` + +Note: When moving to V2 permissions, make sure to include all the necessary expanded permissions based on your original `secrets` permissions.