Learn how to make user group abstractions to manage permissions at scale.
Explore the example from this guide in the FGA Playground, where you can interact with the schema, warrants, and access checks in real-time!
User groups in Fine-Grained Authorization (FGA) allow you to manage permissions at scale by grouping users and granting access to those groups. This is particularly useful in large organizations where managing individual user permissions can become cumbersome.
You should consider using user groups in the following scenarios:
Management groups can be applied in various scenarios, including:
version 0.3 type user type organization relation admin [user] relation document_viewer [user] relation document_manager [user] inherit document_manager if relation admin // admins are also document managers inherit document_viewer if relation document_manager // document managers are also viewers type document // A document has a parent organization relation parent [organization] relation edit [user] relation view [user] // Allow users to edit the document if they // are in the document manager group on the organization that owns it inherit edit if relation document_manager on parent [organization] // Allow users to view the document if they // are in the document viewer group on the organization that owns it inherit view if relation document_viewer on parent [organization]
Create a file called schema.txt
containing the schema definition from above. Then use the CLI to apply this schema to your WorkOS FGA environment.
Note: make sure to select the correct environment with the CLI
workos fga schema apply schema.txt
Create warrants that associate organizations and documents. Add a users to a document_viewer
/ document_manager
groups.
curl "https://api.workos.com/fga/v1/warrants" \ -X POST \ -H "Authorization: Bearer sk_example_123456789" \ --data-raw \ '[ { "op": "create", "resource_type": "organization", "resource_id": "acme", "relation": "document_manager", "subject": { "resource_type": "user", "resource_id": "user_2oDscjroNWtzxzYEnEzT9P7VYEe" } }, { "op": "create", "resource_type": "organization", "resource_id": "acme", "relation": "document_viewer", "subject": { "resource_type": "user", "resource_id": "user_3kLwpXyzQTuvbNApRmC5X4ZhAmd" } }, { "op": "create", "resource_type": "document", "resource_id": "document-1", "relation": "parent", "subject": { "resource_type": "organization", "resource_id": "acme" } } ]'
With our environment setup, we can check the user’s permission to view items.
curl "https://api.workos.com/fga/v1/check" \ -X POST \ -H "Authorization: Bearer sk_example_123456789" \ --data-raw \ '{ "op": "all_of", "checks": [ { "resource_type": "document", "resource_id": "document-1", "relation": "edit", "subject": { "resource_type": "user", "resource_id": "user_2oDscjroNWtzxzYEnEzT9P7VYEe" }, "context": {} }, { "resource_type": "document", "resource_id": "document-1", "relation": "view", "subject": { "resource_type": "user", "resource_id": "user_3kLwpXyzQTuvbNApRmC5X4ZhAmd" }, "context": {} } ] }'