Configure Roles and Permissions

CRAFT uses OpenFGA for Relationship-Based Access Control (ReBAC). This guide covers setting up roles, assigning permissions, and configuring the permission inheritance model across organizations, projects, and resources.

Prerequisites

Before you begin, ensure you have:

A running CRAFT with the Governance service bootstrapped
Administrative access (the admin or owner role on the target organization)
A valid JWT token for the admin user
The OpenFGA schema loaded during Governance bootstrap

How Permissions Work

The platform uses a relationship-based model rather than traditional role-based access control. Permissions are computed at query time from relationships between users, roles, and resources.

User --[role]--> Organization --[parent]--> Project --[parent]--> Resource

Role Hierarchy

Role	Scope	Capabilities
`owner`	Organization	Full control, can transfer ownership, manage all settings
`admin`	Organization / Project	Manage users, projects, settings. Cannot transfer organization ownership
`member`	Project	Standard access to project resources
`developer`	Project	Create and modify agents, data connections, workflows
`operator`	Project	Deploy, schedule, and monitor resources
`viewer`	Project	Read-only access to all resources

Computed Permissions

Permissions are derived from roles via the OpenFGA schema:

Permission	owner	admin	member	developer	operator	viewer
`can_read`	Yes	Yes	Yes	Yes	Yes	Yes
`can_write`	Yes	Yes	Yes	Yes	No	No
`can_delete`	Yes	Yes	No	No	No	No
`can_execute`	Yes	Yes	Yes	Yes	Yes	No
`can_manage_secrets`	Yes	Yes	No	No	No	No

Step 1: Understand the OpenFGA Schema

The permission model is defined in the OpenFGA Schema DSL. The schema lives at:

packages/em_runtime_governance/schema/openfga-schema.fga

Key type definitions:

type organization
  relations
    define owner: [user]
    define admin: [user] or owner
    define member: [user] or admin

type project
  relations
    define parent: [organization]
    define admin: [user] or admin from parent
    define developer: [user] or admin
    define operator: [user] or admin
    define viewer: [user] or developer or operator
    define can_read: viewer or member from parent
    define can_write: developer or admin
    define can_delete: admin
    define can_execute: operator or developer or admin

The runtime JSON version at openfga-schema.json is what the Governance service reads at startup. After editing the .fga file, run ./scripts/generate-openfga-schema.sh to regenerate the JSON.

Step 2: Assign Organization Roles

Assign roles to users at the organization level using the Governance API.

API
Python SDK

# Assign the admin role to a user
curl -X POST "https://<platform-host>:8001/governance/organizations/<org-id>/members" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "<user-id>",
    "role": "admin"
  }'

from em_runtime_governance_sdk import GovernanceClient

client = GovernanceClient(
    base_url="https://<platform-host>:8001",
    token=admin_token
)

await client.organizations.add_member(
    org_id=org_id,
    user_id=user_id,
    role="admin"
)

Step 3: Assign Project Roles

Project roles provide finer-grained control within an organization.

# Assign the developer role on a specific project
curl -X POST "https://<platform-host>:8001/governance/projects/<project-id>/members" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Project-ID: <project-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "<user-id>",
    "role": "developer"
  }'

Permission Inheritance

Roles inherit downward through the hierarchy:

Organization owner

Automatically has admin-level permissions on all projects and resources within the organization.

Organization admin

Automatically has admin-level permissions on all projects. Can create and delete projects.

Project developer

Has can_read, can_write, and can_execute on all resources within the specific project. Cannot delete resources or manage secrets.

Project viewer

Has can_read only. Cannot modify, execute, or delete any resource.

Step 4: Verify Permissions

Check whether a user has a specific permission on a resource:

# Check if user can write to an agent
curl -X POST "https://<platform-host>:8001/governance/permissions/check" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "<user-id>",
    "permission": "can_write",
    "resource_type": "agent",
    "resource_id": "<agent-id>"
  }'

Response:

{
  "allowed": true,
  "resolution": {
    "role": "developer",
    "inherited_from": "project:<project-id>"
  }
}

Common Permission Patterns

Data team with read-only analytics access

Assign viewer on the project containing data connections and dashboards. Users can run queries via Data Insights but cannot modify data connections or agent configurations.

DevOps team managing deployments

Assign operator on the target project. Operators can deploy agents, trigger schedules, and monitor health, but cannot modify agent code or data connection credentials.

Service accounts for CI/CD

Create Keycloak client credentials and assign developer or operator on the target project. Service accounts authenticate via client credentials grant and have the same permission model as human users.

Cross-project access

A user can have different roles on different projects within the same organization. Assign roles per project to implement least-privilege access.

Integration with SSO Groups

When SSO is configured, IdP groups map through Keycloak to OpenFGA:

IdP Group -> Keycloak Group -> OpenFGA Relation (role assignment)

This pipeline automates role assignment when users are provisioned via SSO. See the SSO Integration guide for configuring the IdP side.

Schema Modifications

Adding new permissions to the OpenFGA schema is safe. Renaming or removing existing permissions is a breaking change — coordinate schema and code changes in the same PR.

To add a new permission:

Edit packages/em_runtime_governance/schema/openfga-schema.fga
Run ./scripts/generate-openfga-schema.sh to regenerate the runtime JSON
Update the Permissions class in packages/em_runtime_common/src/common/permissions.py
Run make dev-sync to regenerate SDKs

Troubleshooting

Permission checks returning 403

Verify the OpenFGA schema is loaded by checking Governance bootstrap logs. Ensure the user’s JWT contains the correct groups claim. Confirm the user has been assigned a role on the target project.

Inherited permissions not working

Check that the project has a parent relationship to the organization in OpenFGA. This is set automatically when projects are created via the Governance API.

Role changes not taking effect

OpenFGA evaluates permissions at query time — there is no caching delay. If changes are not reflected, verify the role assignment was successful by listing members on the project.

Next Steps

SSO Integration

Configure SSO to automate group-to-role mapping from your IdP.

Authorization Deep Dive

Learn about the full OpenFGA schema and computed permissions model.

Multi-Tenancy

Understand how permissions integrate with the multi-tenant architecture.

Security Overview

Review the complete security model including authentication and data protection.

Solution Developer Guide

How-To Guides

RBAC Configuration

Configure Roles and Permissions

Prerequisites

How Permissions Work

Role Hierarchy

Computed Permissions

Step 1: Understand the OpenFGA Schema

Step 2: Assign Organization Roles

Step 3: Assign Project Roles

Permission Inheritance

Step 4: Verify Permissions

Common Permission Patterns

Integration with SSO Groups

Schema Modifications

Troubleshooting

Next Steps

SSO Integration

Authorization Deep Dive

Multi-Tenancy

Security Overview

Solution Developer Guide

How-To Guides

Documentation Index

​Configure Roles and Permissions

​Prerequisites

​How Permissions Work

​Role Hierarchy

​Computed Permissions

​Step 1: Understand the OpenFGA Schema

​Step 2: Assign Organization Roles

​Step 3: Assign Project Roles

​Permission Inheritance

​Step 4: Verify Permissions

​Common Permission Patterns

​Integration with SSO Groups

​Schema Modifications

​Troubleshooting

​Next Steps

SSO Integration

Authorization Deep Dive

Multi-Tenancy

Security Overview

Configure Roles and Permissions

Prerequisites

How Permissions Work

Role Hierarchy

Computed Permissions

Step 1: Understand the OpenFGA Schema

Step 2: Assign Organization Roles

Step 3: Assign Project Roles

Permission Inheritance

Step 4: Verify Permissions

Common Permission Patterns

Integration with SSO Groups

Schema Modifications

Troubleshooting

Next Steps