User Groups

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.

When to Use It?

You should consider using user groups in the following scenarios:

Large Organizations: When you have a large number of users and resources, managing permissions individually can be inefficient.
Dynamic User Base: If your user base changes frequently (e.g., employees joining or leaving), management groups can simplify the process of updating permissions.
Hierarchical Structures: When your organization has a hierarchical structure (e.g., departments, teams), management groups can help you define permissions at different levels of the hierarchy without duplicating effort.

Example Applications

Management groups can be applied in various scenarios, including:

Enterprise Applications: In large enterprises, you can create groups for different departments (e.g., Sales, Engineering) and assign permissions to these groups rather than individual users.
Multi-Tenant SaaS Applications: For SaaS applications serving multiple organizations, you can create groups for each tenant and manage permissions for users within those tenants.

Schema

 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]

Example

1. Apply the schema

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

2. Create warrants

Create warrants that associate organizations and documents. Add a users to a document_viewer / document_manager groups.

Create warrants

 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"
      }
    }
  ]'

3. Check access

With our environment setup, we can check the user’s permission to view items.

Check if a user can view a document

 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": {}
      }
    ]
  }'