Schema Management

Learn how to test, debug, and safely apply changes to your authorization schema and setup a GitOps workflow to automatically validate and apply changes to production.

Overview

Designing a schema that meets your requirements and using it in production for the first time is only the beginning of your fine-grained authorization journey. As your product’s authorization requirements change, you will need to evolve your schema to meet those requirements.

To do this safely, you need a process in place to test, debug, and safely apply changes to your schema in production. In case of bugs, you also need the ability to roll back to a previous (working) schema if needed.

This guide will explain how to use the FGA Dashboard and WorkOS CLI to test and debug your schema. We will use the CLI and the CLI GitHub Action to setup a GitOps workflow that automatically tests and applies changes to your schema as part of your software development life cycle (SDLC).

Before getting started

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

A WorkOS account

Your WorkOS API Key

The WorkOS CLI

Test Your Schema

Let’s create a shell script that uses the WorkOS CLI to test the example schema below.

Note: we’ve decided to prefix permissions in our authorization model with can_ (can_invite_users) to imply an action. This is not a required convention, so feel free to use relation names that suit your application.

schema.txt

 version 0.2

type user

type organization
    relation role_admin [user]
    relation role_member [user]
    relation can_invite_users []
    relation can_remove_users []
    relation can_view_users []

    inherit role_member if
        relation role_admin

    inherit can_invite_users if
        relation role_admin

    inherit can_remove_users if
        relation role_admin

    inherit can_view_users if
        relation role_member

First, apply the schema

Apply the example schema

 workos fga schema apply schema.txt

Next, use the fga warrant create command to setup some warrants.

Setup test data

 workos fga warrant create user:acme_admin role_admin organization:org_acme
workos fga warrant create user:acme_member role_member organization:org_acme

Then use the fga check command with the --assert flag to assert that a permission check returns the expected result.

Make assertions

 workos fga check user:acme_admin can_invite_users organization:org_acme --assert true
workos fga check user:acme_admin can_remove_users organization:org_acme --assert true
workos fga check user:acme_admin can_view_users organization:org_acme --assert true

workos fga check user:acme_member can_invite_users organization:org_acme --assert false
workos fga check user:acme_member can_remove_users organization:org_acme --assert false
workos fga check user:acme_member can_view_users organization:org_acme --assert true

Finally, use the fga resource delete command to clean up the test data. This makes it easy to re-run tests with a clean environment in the future.

Clean up test data

 workos fga resource delete user:acme_admin
workos fga resource delete user:acme_member
workos fga resource delete organization:org_acme

Debug Your Schema

The simplest way to understand (debug) why your schema is (or is not) answering a permission check as you expect it to is via the Check page or using the --debug flag via the CLI.

Using the FGA Dashboard

To debug a permission check from the FGA dashboard, navigate to the Check page. Enter valid arguments for the permission check you want to debug and click Check Access. The page will display the result of the permission check and a tree visualizing all of the paths in the authorization graph that were explored to reach the result.

Using the CLI

To debug a permission check using the CLI, use the fga check command with the --debug flag:

Debug a permission check

 workos fga check user:james can_approve_purchase purchase:pur_123 --debug

Permission checks that use the --debug flag will output the check result and a tree visualizing all of the paths in the authorization graph that were explored to reach the result.

Note: running the fga check command with the --debug flag will execute the check without any caching enabled.

GitOps Workflow

Now that we have a script to test that our schema works as we expect, let’s setup a GitHub Action to automatically test changes to the schema and apply the schema if all of the tests pass.

.github/workflows/fga.yaml

 name: Test FGA Schema

on:
  push:
    branches: [main]

jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - name: Install WorkOS CLI
        uses: workos/cli-action@v1
        with:
          version: latest
      - name: Test Schema
        run: |
          workos fga schema apply schema.txt

          workos fga warrant create user:acme_admin role_admin organization:org_acme
          workos fga warrant create user:acme_member role_member organization:org_acme

          workos fga check user:acme_admin can_invite_users organization:org_acme --assert true
          workos fga check user:acme_admin can_remove_users organization:org_acme --assert true
          workos fga check user:acme_admin can_view_users organization:org_acme --assert true

          workos fga check user:acme_member can_invite_users organization:org_acme --assert false
          workos fga check user:acme_member can_remove_users organization:org_acme --assert false
          workos fga check user:acme_member can_view_users organization:org_acme --assert true

          workos fga resource delete user:acme_admin
          workos fga resource delete user:acme_member
          workos fga resource delete organization:org_acme
        env:
          WORKOS_ACTIVE_ENVIRONMENT: staging
          WORKOS_ENVIRONMENTS_HEADLESS_API_KEY: <your_workos_staging_api_key>
      - name: Apply Schema to Production
        if: github.ref == 'main' && github.event_name == 'push'
        run: |
          workos fga schema apply schema.txt
        env:
          WORKOS_ACTIVE_ENVIRONMENT: production
          WORKOS_ENVIRONMENTS_HEADLESS_API_KEY: <your_workos_production_api_key>