Role-Based Access Control

Implement security and access management for Builder applications with RBAC

Role-Based Access Control (RBAC) is the security model used in Prisme.ai to manage who can access, modify, and use different parts of your workspace. It ensures that users only have the permissions they need while protecting sensitive information and functionality.

RBAC Fundamentals

Core Concepts

The RBAC system consists of several key elements:

• Roles: Sets of permissions that can be assigned to users
• Subjects: Resources that can be acted upon (pages, files, events, etc.)
• Actions: Operations that can be performed on subjects (read, create, update, etc.)
• Rules: Define which roles can perform which actions on which subjects
• Conditions: Optional criteria that further restrict when rules apply

These components work together to create a flexible yet secure access control system.

Authorization Structure

RBAC configuration is defined in YAML format and consists of two main sections:

authorizations:
  # Define roles
  roles:
    editor: {}
    custom_role: {}
    
  # Define access rules
  rules:
    - role: editor
      action: read
      subject: pages

You can access and edit this configuration through your workspace settings.

Default Roles

Prisme.ai includes several built-in roles:

• Owner: Created automatically for workspace creator, has full access
• Editor: Can create and modify content but limited administrative access
• Custom Roles: Additional roles you define for specific needs

The Owner role is special and cannot be modified or deleted. It is automatically assigned to workspace creators and administrators.

Managing Roles and Rules

1. Accessing RBAC Settings

   To view and edit your workspace’s access control configuration:

   1. Go to your workspace
   2. Navigate to Settings > Advanced > Manage Roles
   3. Edit the YAML configuration
   4. Save your changes

   Changes to RBAC settings take effect immediately. Be careful not to lock yourself out!

2. Defining Roles

   Create custom roles to fit your organization’s needs:

   authorizations:
     roles:
       editor: {}  # Built-in role
       
       # Custom role for regular users
       user:
         auth:
           prismeai: {}  # Automatically assigned to all Prisme.ai users
           
       # Role for API access
       workspace:
         auth:
           apiKey: {}  # Can be used with API keys
   

   The auth section allows you to automatically assign roles based on authentication providers.

3. Creating Rules

   Define what each role can do with specific rules:

   rules:
     # Allow editors to read and update workspaces
     - role: editor
       action:
         - read
         - get_usage
         - aggregate_search
         - update
       subject: workspaces
       
     # Give editors full control over files
     - role: editor
       action: manage  # Shorthand for all permissions
       subject: files
   

   Each rule must include at least:

   • action: What can be done (a single action or list)
   • subject: What it can be done to (a single subject or list)

   Rules can optionally specify:

   • role: Which role this applies to (if omitted, applies to everyone)
   • conditions: Restrict the rule to specific cases. If omitted (or an empty object), the rule will apply to every instance of specified subject
   • inverted: Set to true to make this a deny rule instead of allow
   • reason: Documentation string for the rule
4. Adding Conditions

   Restrict rules to specific situations with conditions:

   # Allow access only to pages with a "public" label
   - action: read
     subject: pages
     conditions:
       labels:
         $in:
           - public
   
   # Deny editor access to API key events
   - role: editor
     inverted: true
     action: read
     subject: events
     conditions:
       type:
         $regex: ^apikeys\.*$
   

   Conditions use a subset of MongoDB query syntax for powerful filtering.

Common RBAC Patterns

Public Access

Control what unauthenticated users can access:

# Allow anyone to read pages with "public" label
- action: read
  subject: pages
  conditions:
    labels:
      $in:
        - public
        
# Allow anyone to create events (for automations)
- action: create
  subject: events
  conditions:
    source.serviceTopic: topic:runtime:emit
  reason: Anyone can create any events

Rules without a role specified apply to everyone, including unauthenticated users.

Role-Based Access

Define what each role can do:

# User role can read all pages
- role: user
  action:
    - read
  subject: pages

# Editor role can read and update pages
- role: editor
  action:
    - read
    - update
  subject: pages

This approach creates a clear hierarchy of access permissions.

API Key Permissions

Configure permissions for API access:

# Define workspace role for API access
roles:
  workspace:
    auth:
      apiKey: {}
      
# Grant specific permissions to this role
rules:
  - role: workspace
    action:
      - read
      - manage_permissions
    subject:
      - workspaces
      - events
      - pages
      - files

This allows creating an internal workspace API key with specific permissions.
The api key value can’t be directly accessed, but instead can be injected in fetch instruction :

  - fetch:
      url: '...'
      prismeaiApiKey:
        name: workspace

Automatic assignment

Automatically assign roles based on SSO provider & auth data :

roles:
  # Assign user role to all Prisme.ai & yourOwnSso authenticated users
  user:
    auth:
      prismeai: {}
      yourOwnSso: {}
      
  # Assign admin role to users from a specific email domain
  admin:
    auth:
      prismeai:
        conditions:
          authData.email:
            $regex: ^.*@mycompany.com$

This reduces manual user management by leveraging authentication information.

Subjects and Actions

RBAC controls access to various resource types through subject and action combinations:

Workspaces

Subject : workspaces

Actions :

• read : allows reading the workspace configuration
• update : allows updating the workspace configuration
• delete : allows deleting the workspace
• manage_security : allows updating security configuration
• manage_permissions : allows sharing / unsharing
• aggregate_search : allows using /search API
• get_usage : allows using /usage API
• manage_repositories : allows managing repositories settings
• manage : allows all above actions

Pages

Subject : pages

Actions :

• create : allows creating a page
• read : allows reading pages
• update : allows updating pages
• delete : allows deleting pages
• manage : allows all above actions

Files

Subject : files

Actions :

• create : allows uploading a file
• read : allows reading files
• update : allows updating files
• delete : allows deleting files
• manage : allows all above actions

Events

Subject : events

Actions :

• create : allows emitting an event
• read : allows reading events
• manage : allows all above actions

Automations

Subject : automations

Actions :

• create : allows creating an automation
• read : allows reading automations
• update : allows updating automations
• delete : allows deleting automations
• execute : allows executing automations
• manage : allows all above actions

Secrets

Subject : secrets

Actions :

• create : allows creating secrets
• read : allows reading secrets
• update : allows updating secrets
• delete : allows deleting secrets
• manage : allows all above actions

Apps

Subject : apps

Actions :

• create : allows publishing an app
• read : allows viewing/installing apps
• update : allows updating apps
• delete : allows deleting apps
• manage : allows all above actions

Securing Automations

By default, anyone can execute any automation that has an event or endpoint trigger. To restrict access to sensitive automations:

1. Define Authorization Action

   In your automation, specify an authorization requirement:

   slug: getAnalytics
   name: "Admin Page: Init Analytics"
   description: "Restricted automation for admin use only"
   when:
     events:
       - initAnalytics
   do:
     - emit:
         event: updateAnalytics
         payload:
           data: [...]
   authorizations:
     action: admin  # This is the authorization key
   

   The authorizations.action field specifies a permission key for this automation.

2. Create Permission Rule

   Define who can execute automations with this authorization key:

   # Allow admin role to execute automations with "admin" authorization
   - role: admin
     action: execute
     subject: automations
     conditions:
       authorizations.action:
         $in:
           - admin
   

   This restricts execution only to users with the specified role.

3. Test the Restriction

   Verify that:

   • Users with the admin role can execute the automation
   • Users without the admin role receive an authorization error
   • The automation cannot be called indirectly by other automations without permission

Using API Keys

External API Keys

API keys allow programmatic access to your workspace with specific permissions :

1. Use Prismeai APIs to generate an api key :

curl --location 'https://api.studio.prisme.ai/v2/workspaces/<WORKSPACE_ID>/security/apiKeys' \
--header 'Authorization: Bearer <JWT>' \
--header 'Content-Type: application/json' \
--data '{
  "name": "api key name",
  "rules": [
      {
          "action": "create",
          "subject": "files"
      },
      {
          "action": ["create", "update", "read"],
          "subject": "pages",
          "conditions": {
              "labels": {
                  "$in": ["internal"]
              }
          }
      }        
  ]
}'  

2. Include the received apikey in x-prismeai-api-key header :

fetch('https://api.studio.prisme.ai/v2/events', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-prismeai-api-key': 'your-api-key'
  },
  body: JSON.stringify({ type: 'custom-event', payload: { data: 'value' } })
});

Keep API keys secure. They grant access based on their associated role without requiring user authentication.

Workspace API Keys

For internal API calls from automations, you can define built-in API keys:

roles:
  workspace:
    auth:
      apiKey: {}
      
rules:
  - role: workspace
    action:
      - read
      - aggregate_search
    subject:
      - workspaces
      - events

This creates an internal API key that automations can use:

- Prismeai API.searchEvents:
    query:
      type: user-login
    prismeaiApiKey:
      name: workspace
    output: events

Workspace API keys are not visible in the UI and are specifically for internal use.

Example RBAC Configuration

Here’s a complete example of a typical RBAC configuration:

Full RBAC Example

authorizations:
  roles:
    editor: {}
    user:
      auth:
        prismeai: {}
    workspace:
      auth:
        apiKey: {}
  rules:
    # Public access rules
    - action: read
      subject: pages
      conditions:
        labels:
          $in:
            - public
            
    # Workspace API key permissions
    - role: workspace
      action:
        - read
        - manage_permissions
      subject:
        - workspaces
        - events
        - pages
        - files
    - role: workspace
      action:
        - update
      subject:
        - files
        
    # User role permissions
    - role: user
      action:
        - read
      subject: pages
      
    # Editor role permissions
    - role: editor
      action:
        - read
        - get_usage
        - aggregate_search
        - update
      subject: workspaces
    - role: editor
      action: manage
      subject: files
    - role: editor
      action:
        - read
        - update
      subject: pages
    - role: editor
      action:
        - read
        - update
      subject: apps
    - role: editor
      action:
        - read
        - create
      subject: events
        
    # Editor role restrictions
    - role: editor
      inverted: true
      action: read
      subject: events
      conditions:
        type:
          $regex: ^apikeys\.*$
          
    # Public event access
    - action: create
      subject: events
      reason: Anyone can create any events
      conditions:
        source.serviceTopic: topic:runtime:emit
    - action: read
      subject: events
      conditions:
        source.serviceTopic: topic:runtime:emit
        source.sessionId: '{{session.id}}'
      reason: Anyone can read any events from its own session
      
    # Public file upload
    - action: create
      subject: files
      conditions:
        mimetype:
          $regex: ^(.*)$
      reason: Anyone can upload any file

Security Best Practices

Principle of Least Privilege

Give users only the permissions they actually need:

• Start with minimal permissions and add as required
• Use specific conditions to limit rule scope
• Avoid “manage” permission when more specific actions suffice
• Regularly review and prune unnecessary permissions

Secure Public Access

Carefully control what unauthenticated users can do:

• Use explicit conditions on public rules
• Limit event creation to specific event types
• Be cautious with file upload permissions
• Restrict user session events appropriately

Protect Sensitive Automations

Secure automations that access sensitive data:

• Add authorization requirements to important automations
• Create specific roles for administrative functions
• Avoid sensitive data exposure through events
• Test automations with different user roles

Manage API Access

Control programmatic access carefully:

• Create API keys with minimal required permissions
• Rotate API keys regularly
• Monitor API key usage for unusual patterns
• Delete unused API keys promptly

Troubleshooting

Access Denied Unexpectedly

When users encounter permission errors they shouldn’t:

Check these common issues:

• Verify the user has the correct role assignment
• Look for inverted rules (deny rules) that might be applying
• Check if conditions on rules are unintentionally restrictive
• Ensure the rule order places more specific rules after general ones

Example fix:

# Add a more permissive rule for this specific case
- role: user
  action: read
  subject: pages
  conditions:
    category: reports

Too Much Access

When users have permissions they shouldn’t have:

Check these common issues:

• Look for overly broad rules without conditions
• Check if the user has multiple roles granting cumulative permissions
• Verify automatic role assignment isn’t giving unintended access
• Ensure public rules (no role specified) aren’t too permissive

Example fix:

# Add a specific deny rule
- role: user
  inverted: true
  action: read
  subject: pages
  conditions:
    category: admin
    
# Or make existing rules more specific
- role: user
  action: read
  subject: pages
  conditions:
    category: 
      $ne: admin

Next Steps

Automations

Explore automations and their security model