diff --git a/docs/internals/permissions.mdx b/docs/internals/permissions.mdx index 3eb7059d2..1fce09def 100644 --- a/docs/internals/permissions.mdx +++ b/docs/internals/permissions.mdx @@ -3,81 +3,209 @@ 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. -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 + +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 +- 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. + +## 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.