Configure roles and permissions

Configure business role names and map governed capabilities (<resourceType>:<operation>) to those roles in rbac.yaml.

Prerequisites

Datasources with resourceType and exposed capabilities defined
aifabrix login and aifabrix auth status green

Where it lives

integration/<systemKey>/
  rbac.yaml              # recommended — roles + permissions
  <systemKey>-system.json   # optional inline roles (repair merges to rbac.yaml)

Permissions use capability names aligned with exposure — typically customer:read, document:search, not raw OpenAPI operation ids.

Platform roles vs business RBAC

Layer	Controls	Doc
Platform roles	Who can run `upload`, `protection upload`, `verify-governance`	Platform developer access
Business RBAC (`rbac.yaml`)	Which capabilities Role Assistants may invoke	This page

Integration developers need platform scopes for publish and test commands. Governance operators need scopes for identity sync and certification. Business Admin in rbac.yaml does not grant platform admin rights.

Builder MCP


Manifest section	`system.rolesPermissions`
Help topics	`section`, `repairRules`, `dependencyGraph`
Repair hooks	`rbac`

After capability or exposure changes on Business Entities, run aifabrix repair <systemKey> --rbac. Full CLI ladder: CLI workflow.

How to set

Choose business role names — Admin, Reader, SalesManager (reuse enterprise vocabulary).
Create rbac.yaml:

roles:
  - name: Admin
    value: admin
    description: Full integration maintenance
  - name: Reader
    value: reader
    description: Read-only governed access
  - name: SalesManager
    value: sales-manager
    description: Regional sales scope
permissions:
  - name: customer:read
    roles: [admin, reader, sales-manager]
    description: Read customer records
  - name: customer:search
    roles: [admin, sales-manager]
    description: Search customers within ABAC scope
  - name: document:read
    roles: [admin, reader]
    description: Read document metadata

Align permission names with exposed capabilities — match resourceType from datasource JSON + operation from exposed block.
Repair RBAC defaults:

aifabrix repair <systemKey> --rbac --dry-run
aifabrix repair <systemKey> --rbac
aifabrix validate <systemKey>

Map roles to Entra groups for governance tests:

aifabrix identity role set-groups sales-manager -e dev --groups "Sales Managers"
aifabrix identity sync -e dev

Upload:

aifabrix upload <systemKey> --probe

Defaults and examples

Role	value	Typical permissions
Admin	`admin`	All capabilities for the system
Reader	`reader`	`:read` and `:search` only
SalesManager	`sales-manager`	Customer/deal read + search in scope

Enable autoRbac on datasource exposed when operations lack explicit permission scopes — validator resolves <resourceType>:<operation> per operation. Explicit security on an operation overrides autoRbac for that operation.

Example rbac.yaml fragment (permissions must match root resourceType on datasources):

roles:
  - key: reader
    displayName: Reader
    permissions:
      - customer:read
      - customer:search
  - key: sales-manager
    displayName: Sales Manager
    permissions:
      - customer:read
      - customer:search
      - deal:read

Datasource root fields (key, displayName, systemKey, entityType, resourceType, primaryKey, externalId) must stay consistent with permission prefixes.

Validate

aifabrix validate <systemKey>
aifabrix verify-governance <systemKey> --subject-email scoped-user@example.com

Use a subject user with sales-manager role — not platform admin.

Common mistakes

Mistake	Fix
Permissions without matching capabilities	Align with `exposed` after `--expose`
RBAC only in UI	Keep `rbac.yaml` in git
Testing governance as admin	Create scoped subject user
Mismatched resourceType prefix	Use same token as datasource root `resourceType`

Limits

Entra group names and identity sync timing are environment-specific. After role/group changes, always run identity sync before verify-governance. Permission strings must reference the same resourceType token set on each datasource key — mixed prefixes (company:read vs customer:read) are a common cause of green validate and red governance tests. Each datasource displayName is independent of RBAC role names — roles grant capabilities, not UI labels. After repair --rbac, diff rbac.yaml against exposed capabilities — orphan permissions fail governance tests even when validate passes.

Example exposed and capabilities aligned with RBAC permission names:

{
  "exposed": {
    "filterable": ["externalId", "country"],
    "schema": {
      "externalId": "metadata.externalId",
      "country": "metadata.country"
    }
  },
  "capabilities": [
    { "key": "get", "description": "Read customer by id", "riskLevel": "low" },
    { "key": "search", "description": "Search customers", "riskLevel": "low" }
  ]
}

Permission strings in rbac.yaml use <resourceType>:<operation> — for example customer:get and customer:search when resourceType is customer.

After upload, run verify-governance with a subject mapped to sales-manager — admin subjects hide missing permission rows. Keep rbac.yaml in version control beside datasource JSON so repair and manual edits stay auditable. When exposed.autoRbac is true, permission names still must resolve to real catalog resourceType tokens on each datasource key. Treat primaryKey and externalId on datasource JSON as prerequisites — RBAC cannot compensate for missing join identity during governance tests.

Documentation Index