Migrate from OpenFGA

This guide helps you migrate from OpenFGA to WorkOS FGA. While both systems are inspired by Google’s Zanzibar paper, they take different approaches. OpenFGA uses relation-based access control (ReBAC) with explicit tuple storage, while WorkOS FGA uses hierarchical role-based access control (RBAC) with automatic permission inheritance.

OpenFGA requires a schema DSL and explicit tuples for every relationship. WorkOS FGA simplifies this:

1. Permissions flow down automatically – A role at a parent level grants access to all children without additional tuples
2. Roles are scoped to resource types – Each resource type has its own set of roles
3. Single parent per resource instance – Each resource instance has exactly one parent, creating predictable traversal paths
4. No schema DSL – Configure resource types, roles, and permissions in the Dashboard
5. Native WorkOS integration – Works seamlessly with AuthKit, SSO, Directory Sync, and IdP role assignment

Unlike standalone authorization systems, WorkOS FGA integrates natively with the WorkOS identity platform (although it can be used standalone):

• AuthKit Integration – Organization-scoped roles and permissions are embedded in access tokens for instant JWT-based checks
• IdP Role Assignment – Map identity provider groups (Okta, Azure AD, Google Workspace) directly to organization-scoped roles
• Directory Sync – Automatically provision and deprovision users with appropriate role assignments when group memberships change
• SSO – Enterprise SSO users get role assignments based on IdP group membership during authentication

Extract domain objects from your OpenFGA type definitions. These become resource types in WorkOS FGA.

Create resource types for:

• Business containers: organizations, workspaces, projects, environments
• Shareable entities: apps, pipelines, repositories, dashboards

Exclude:

• type user – Use Organization Memberships as subjects instead
• type group – User groups are coming soon; for now, assign roles directly to users

# OpenFGA
type user
type organization
type workspace
type project

# WorkOS FGA Resource Types
organization (built-in)
└── workspace
    └── project

Navigate to Authorization > Resource Types in the Dashboard to create your hierarchy.

Map OpenFGA parent relations to WorkOS FGA parent-child resource type relationships.

Create a project resource type with workspace as its parent. The parent relationship is defined at the resource type level.

When you register individual project resources instances via the API, they automatically inherit from their workspace. Permissions flow down this hierarchy without explicit tuples.

OpenFGA relations like viewer, editor, and admin become roles scoped to resource types.

Create roles on the project resource type:

The or unions in OpenFGA become multiple permissions bundled into a single role.

OpenFGA computed relations using the from keyword are replaced by native hierarchical inheritance.

Create a workspace resource type with a role that includes child-type permissions:

When you assign workspace:viewer to a user, they automatically get project:view on all projects within that workspace. No explicit per-project tuples needed.

OpenFGA contextual tuples allow passing runtime context with permission checks. With WorkOS FGA, handle these checks in your application code instead. This keeps the check interface simple and puts conditional logic next to the data it depends on.

// Check time-based access in your app
const now = new Date();
const accessWindow = await getAccessWindow(resourceId);

if (now < accessWindow.start || now > accessWindow.end) {
  return { authorized: false };
}

// Then check FGA permissions
const { authorized } = await workos.authorization.check({
  organizationMembershipId,
  permissionSlug: 'project:view',
  resourceExternalId: resourceId,
  resourceTypeSlug: 'project',
});

Not everything belongs in FGA. We recommend using FGA for lower-cardinality resources (organizations, workspaces, projects) and handling high-cardinality entities (files, messages, comments) in your application.

Syncing millions of entities into FGA creates reconciliation overhead, race conditions, and consistency challenges. Instead, check access at the parent container level and filter entities in your application.

For detailed guidance on this pattern, including interceptor examples for nested entities, see High-Cardinality Entities.

1. Define resource types in the WorkOS Dashboard matching your OpenFGA types
2. Define permissions for each type (e.g., view, edit, manage)
3. Create roles that bundle permissions, including child-type permissions for inheritance
4. Register resources via API when entities are created in your app
5. Migrate tuples to role assignments on specific resources
6. Replace OpenFGA checks with WorkOS FGA check API calls

OpenFGA Check:

const { allowed } = await fga.check({
  user: 'user:alice',
  relation: 'viewer',
  object: 'project:budget',
});

WorkOS FGA Check:

const { authorized } = await workos.authorization.check({
  organizationMembershipId: 'om_01HXYZ', // available in a session token or via the API
  permissionSlug: 'project:view',
  resourceTypeSlug: 'project',
  resourceExternalId: 'budget',
});

Resource type hierarchy:

organization (built-in)
└── workspace
    └── project

Roles for workspace:

Roles for project:

Organization members get workspace:viewer through an organization-scoped role. Workspace editors automatically get project:edit on all child projects through inheritance.

• Resource Types – Design your hierarchy
• Roles and Permissions – Configure inheritance patterns
• AuthKit Integration – Embed permissions in access tokens
• IdP Role Assignment – Map IdP groups to roles
• Assignments – Migrate your tuples to role assignments
• Access Checks – Replace OpenFGA check calls