diff --git a/rfcs/granular-permissions.md b/rfcs/granular-permissions.md new file mode 100644 index 00000000000..45aa90c3e79 --- /dev/null +++ b/rfcs/granular-permissions.md @@ -0,0 +1,195 @@ +# RFC: Granular Permission System + +This RFC proposes a new approach for handling user, organization member, and access tokens (CDN + +target access tokens) to allow resource granularity. + +## Problem Statement + +Today, our permission and access token system has several shortcomings. Here are a few examples: + +- Impossible to limit an access token to only publish a specific service within a target +- Impossible to limit project or target access based on an individual user +- Different types of access tokens (CDN access tokens and registry access tokens) + +This has become a inconvenience for organizations that want strict access control to resources +within Hive. + +## Goals + +- Unification of CDN access tokens and registry tokens as "global" organization scoped access token +- Introduction of personal access tokens +- Granular resource access (inspired by AWS IAM) for both organization member roles and access + tokens +- Update permissions of access tokens after creation by attaching new policies or updating existing + policies + +## Proposed Solution + +### Introducing Policies + +Instead of defining permissions for organization member roles, permissions are now defined as +policies. Policies allow granular access to resources and are heavily inspired by AWS IAM. + +A policy is a list of statements that will either allow or deny the access to a resource on Hive. If +any of the statements will evaluate to "deny", the actor will not be able to perform a specific +action like publish a schema, view a project or similar. + +A statement consists of a `effect` (either `"deny"` or `"allow"`), a action (what specific things +are allowed or denied) and a resource (on which resource are these actions allowed or denied). + +For Hive organization administrators, it will be possible to build these policies through either a +policy builder, or by editing raw JSON. + +Here are some example statements that serve to show the flexibility and granularity. + +**Sample Statement: Allow viewing a specific project** + +```json +{ + "effect": "allow", + "action": "project:view", + "resource": ["hrn::project/"] +} +``` + +**Sample Statement: Allow viewing a all projects** + +```json +{ + "effect": "allow", + "action": "project:view", + "resource": ["hrn::project/*"] +} +``` + +**Sample Statement: Allow viewing two specific projects** + +```json +{ + "effect": "allow", + "action": "project:view", + "resource": [ + "hrn::project/933007e7-b3f6-4182-8dd5-8d3ce1857b1a", + "hrn::project/7b572593-483c-4875-b1bf-4deb60239338" + ] +} +``` + +**Sample Statement: Allow publishing new schema version for service on specific federated target** + +```json +{ + "effect": "allow", + "action": "schema:publish", + "resource": ["hrn::target/933007e7-b3f6-4182-8dd5-8d3ce1857b1a/"] +} +``` + +**Sample Statement: Allow publishing new schema version for service on specific federated target** + +```json +{ + "effect": "allow", + "action": "schema:publish", + "resource": ["hrn::target/933007e7-b3f6-4182-8dd5-8d3ce1857b1a/*"] +} +``` + +Each policy will have a list of statements. One or more policies can be attached to either a +organization member role or organization access token. + +When updating a policy, the changes will be reflected for all organization members and organization +access tokens that reference such policies. + +### Merging CDN access tokens and registry access tokens + +In the new permission system, there will no longer be access tokens that belong to one target. +Existing "legacy" registry access tokens will keep working as before. + +Any new access token created within the scope of an organization will be an organization access +token, whose permissions are defined via policy statements. + +E.g. a statement for a organization access token that can both report usage, but also read a +supergraph from the Hive CDN would look like the following: + +```json +{ + "effect": "allow", + "action": ["usage:report", "cdn:read"], + "resource": ["hrn::target/"] +} +``` + +We highly encourage, that organization admins create these sensitive access tokens that are used for +production and CI/CD systems. However, it will be possible to grant organization members access to +create these tokens. + +### Personal Access Tokens + +Personal access tokens allow users to create access tokens that have a subset of the permissions +their user role provides. + +Some examples: + +- Pull the latest schema version for local frontend development +- Compose a local GraphQL schema/service with the services published to the Hive schema registry + +A organization member can not grant any permissions to the access token that are not covered by the +assigned role to the user. + +If an organization members permissions would be downgraded/removed, this change will be +automatically applied in all the access token that user has for this organization. + +It will also be possible for organizations to disable personal access tokens if desired. + +### ER Diagram + +```mermaid +erDiagram + +users ||--o{ organization_member : "can be a member of multiple" +users ||--o{ personal_access_tokens : "has one or more" +organization ||--o{ organization_access_tokens : "has many" +organization ||--o{ organization_member : "has many" +organization_member ||--o{ organization_member_roles : "has assigned a single" +organization_member_roles ||--o{ organization_policies : "has many attached" +organization_access_tokens ||--o{ organization_policies : "has many attached" +``` + +### Implications for CLI Tooling and Usage Reporting + +Since access tokens will no longer be tied to a specific target, for new access tokens, it will +become mandatory to provide the organization/project/target path. + +**Example: Running a schema check** + +```bash +# old command +hive schema:check schema.graphql + +# new command +# organization / project / target +hive schema:check the-guild-org/my-federation-project/development schema.graphql +``` + +For "Legacy" registry access tokens providing this path will remain optional as existing CI/CD setup +shall remain functional. + +The same also applies for usage reporting. + +For "legacy" registry access tokens, the endpoint will remain the same +(`https://app.graphql-hive.com/usage`), however, new access tokens will also require specifying the +target path (` https://app.graphql-hive.com/usage/the-guild/my-federation-project/development`). + +Our CLIs, SDKs, the Gateway, and documentation will be updated accordingly to support both legacy +tokens and the new access tokens. + +## Related Issues + +- https://github.com/kamilkisiela/graphql-hive/issues/4713 +- https://github.com/kamilkisiela/graphql-hive/issues/124 +- https://github.com/kamilkisiela/graphql-hive/issues/4713 + +## Internal Documentation + +- https://www.notion.so/theguildoss/New-Hive-Permission-System-113b6b71848a8013bbc7d6ad67d81b43?pvs=4