WorkOS Docs Homepage
Fine-Grained Authorization
API referenceDashboardSign In

Shareable Content

Build a Google Docs-like authorization model in which users have varying levels of access to documents they can collaborate on with each other.

Overview

If you are building an application that supports user-generated content (e.g. documents, notes, images, etc.), chances are you’ll need to build complex authorization logic to allow users to share access to that content with others. Building this type of fine-grained authorization logic can get complicated fast and is difficult to scale.

What you’ll build

In this guide, we’ll use FGA to implement an authorization model similar to the Google Docs document sharing model. It will allow users to grant read and/or write access to other users on individual documents and folders that contain other documents and folders nested inside of them.

  1. Define an FGA schema to model your application’s authorization requirements
  2. Create warrants that assign relationships between resources in your application
  3. Make access checks to determine if a user has a given privilege or not

This guide is now available as an example in the FGA Playground, where you can interact with the schema, warrants, and queries in real-time!

Before getting started

To get the most out of this guide, you’ll need:

API resource definitions

Schema
A schema defines the types of relationships between your application’s resources. It also shows how these relationships can inherit from one another.
Warrant
A rule assigning a relationship between two resources in your application

1. Install the WorkOS SDK

Don't see an SDK you need? Contact us to request an SDK!

2. Define a resource type schema

Since documents are the main type of resource we’re dealing with in our application, schema will include a document resource type. We’ll also have a user resource type to represent our users.

Here are the requirements for our authorization model:

  • Users can be assigned one of three roles on any document: owner, editor, and viewer
  • An owner of a document can read/write the contents of the document and read/write who else has access to the document
  • An editor of a document can read/write the contents of the document and read who else has access to the document
  • A viewer of a document read the contents of the document and read who else has access to the document
  • A user with any write privilege also inherits the read privilege
  • Documents can be parents of other documents (i.e. folders)
  • All roles or permissions a user has on a parent document are inherited on any child documents

To model our authorization requirements such that we can answer these questions, let’s define the following schema:

schema.txt

With the schema above, we’ve implemented an authorization model that can easily answer the following questions:

  • Does user U have permission P on document D?
  • Which documents does user U have permission P on?
  • Which users have permission P on document D?

A. Using the CLI

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.

B. Using the FGA Dashboard

Define a resource type schema in the FGA dashboard using the schema editor available on the Schema page.

3. Create warrants

Now that we have defined a resource type schema that meets our authorization requirements, we need to create warrants that associate:

  • documents with other documents (i.e. folders)
  • users with documents (using one of the defined roles: owner, editor, or viewer)

Let’s create a few warrants between documents doc-1, doc-2, doc-3, folder-1, folder-f2, and user user_2oDscjroNWtzxzYEnEzT9P7VYEe:

Create warrants

4. Check and query access

With our document hierarchy setup and permissions assigned to a user, we can check or query the user’s permissions to enforce access.

Check if a user has a permission on a document
List documents where a user has a permission

Summary

In this guide, we explained how to use FGA to set up an authorization model for shareable content. By giving each user an owner, editor, or viewer role on specific documents, and organizing documents with a parent relationship, we can enforce complex authorization rules. This approach manages fine-grained permissions without the usual complexity.