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.
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).
To get the most out of this guide, you’ll need:
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.
version 0.3 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
workos fga schema apply schema.txt
Next, use the fga warrant create command to setup some warrants.
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.
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.
workos fga resource delete user:acme_admin workos fga resource delete user:acme_member workos fga resource delete organization:org_acme
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.
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.
To debug a permission check using the CLI, use the fga check command with the --debug flag:
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.
The CLI provides a streamlined way to run multiple tests against your schema using a single workos fga test command. The test command will set up warrants, perform checks, and handle teardown.
It also supports running multiple test files from a directory, allowing you to organize tests in a structure that fits your application.
setup: warrants: - subject: user:acme_admin relation: role_admin resource: organization:org_acme - subject: user:acme_member relation: role_member resource: organization:org_acme tests: - name: acme_admin can invite users check: subject: user:acme_admin relation: can_invite_users resource: organization:org_acme expect: true - name: acme_admin can remove users check: subject: user:acme_admin relation: can_remove_users resource: organization:org_acme expect: true - name: acme_admin can view users check: subject: user:acme_admin relation: can_view_users resource: organization:org_acme expect: true - name: acme_member cannot invite users check: subject: user:acme_member relation: can_invite_users resource: organization:org_acme expect: false - name: acme_member cannot remove users check: subject: user:acme_member relation: can_remove_users resource: organization:org_acme expect: false - name: acme_member can view users check: subject: user:acme_member relation: can_view_users resource: organization:org_acme expect: true teardown: resources: - user:acme_admin - user:acme_member - organization:org_acme
To run the tests defined in the schema.test.yaml file, use the following command:
workos fga test org-roles.test.yaml
The teardown section is optional and used for cleaning up specific data (resources or warrants). If you want to automatically cleanup all resources and warrants created during the test, you can also use the --cleanup flag when running the workos fga test command.
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.
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 test tests/org-roles.test.yaml 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>