Access Control Examples

Real-world examples of access control rules with JWT authentication

This guide provides real-world examples of using access control rules with JWT authentication and additional info fields.

ℹ️ NOTE: Access control rules are managed at Settings → User Management → Access Control → Additional Info tab.

Complete Workflow: JWT to Permissions

1. Configure JWT Field Mappings

   In your backend configuration, configure which JWT fields to extract:

   {
     "widget_jwt_fields_mapping": [
       {
         "jwt_field": "department",
         "label": "Department"
       },
       {
         "jwt_field": "user_metadata.subscription",
         "label": "Subscription Tier"
       },
       {
         "jwt_field": "location.region",
         "label": "Region"
       },
       {
         "jwt_field": "employee.id",
         "label": "Employee ID"
       }
     ]
   }
   
2. User Authenticates with JWT

   When a user authenticates via the widget with a JWT token:

   JWT Payload Example:

   {
     "sub": "user123",
     "email": "[e-mail]",
     "department": "IT",
     "user_metadata": {
       "subscription": "enterprise"
     },
     "location": {
       "region": "europe"
     },
     "employee": {
       "id": "EMP456"
     }
   }
   

   Resulting additional info fields:

   {
     "jwt_claims": { /* full JWT payload */ },
     "jwt_sub": "user123",
     "jwt_iss": "https://auth.company.com",
     "jwt_extracted_fields": {
       "Department": "IT",
       "Subscription Tier": "enterprise",
       "Region": "europe",
       "Employee ID": "EMP456"
     },
     "department": "IT",
     "subscription_tier": "enterprise",
     "region": "europe",
     "employee_id": "EMP456"
   }
   
3. Create Permission Rules

   Create additional info rules that leverage the flattened fields:

Example 1: Department-Based Access

Grant IT support permissions to IT department:

{
  "name": "IT Department Access",
  "conditions": [
    {
      "key": "department",
      "value": "IT",
      "negate": false
    }
  ],
  "permission_ids": ["it-support-permission-uuid"],
  "agent_ids": ["it-helpdesk-agent-uuid"],
  "priority": 100,
  "is_active": true
}

Example 2: Subscription Tier Access

Grant premium features to enterprise subscribers:

{
  "name": "Enterprise Features",
  "conditions": [
    {
      "key": "subscription_tier",
      "value": "enterprise",
      "negate": false
    }
  ],
  "permission_ids": ["enterprise-features-uuid"],
  "agent_ids": ["enterprise-agent-uuid"],
  "priority": 90,
  "is_active": true
}

Example 3: Regional Compliance

Grant GDPR-compliant access to European users:

{
  "name": "European Users - GDPR Compliant",
  "conditions": [
    {
      "key": "region",
      "value": "europe",
      "negate": false
    }
  ],
  "permission_ids": ["gdpr-compliant-permission-uuid"],
  "priority": 80,
  "is_active": true
}

Example 4: Combined Conditions

Grant special access to enterprise users in Europe:

{
  "name": "Enterprise Europe Premium",
  "conditions": [
    {
      "key": "subscription_tier",
      "value": "enterprise",
      "negate": false
    },
    {
      "key": "region",
      "value": "europe",
      "negate": false
    }
  ],
  "permission_ids": ["enterprise-eu-permission-uuid"],
  "agent_ids": ["eu-premium-agent-uuid"],
  "priority": 95,
  "is_active": true
}

Example 5: Negative Matching

Grant basic access to non-trial users:

{
  "name": "Non-Trial Users",
  "conditions": [
    {
      "key": "subscription_tier",
      "value": "trial",
      "negate": true
    }
  ],
  "permission_ids": ["full-access-uuid"],
  "priority": 70,
  "is_active": true
}

Use Case Scenarios

Scenario 1: SaaS Platform with Tiered Access

Business Requirements:

• Free users: Basic agent, limited features
• Pro users: Advanced agent, full features
• Enterprise users: Premium agent, priority support, custom features

Implementation:

1. Configure JWT to extract subscription_plan field
2. Create three rules:

Free tier (negate paid tiers):

{
  "name": "Free Tier Users",
  "conditions": [
    {"key": "subscription_plan", "value": "pro", "negate": true},
    {"key": "subscription_plan", "value": "enterprise", "negate": true}
  ],
  "permission_ids": ["basic-permission-uuid"],
  "agent_ids": ["basic-agent-uuid"],
  "priority": 10
}

Pro tier:

{
  "name": "Pro Users",
  "conditions": [
    {"key": "subscription_plan", "value": "pro", "negate": false}
  ],
  "permission_ids": ["pro-permission-uuid"],
  "agent_ids": ["advanced-agent-uuid"],
  "priority": 50
}

Enterprise tier:

{
  "name": "Enterprise Users",
  "conditions": [
    {"key": "subscription_plan", "value": "enterprise", "negate": false}
  ],
  "permission_ids": ["enterprise-permission-uuid"],
  "agent_ids": ["premium-agent-uuid"],
  "priority": 100
}

Scenario 2: Multi-Tenant B2B Platform

Business Requirements:

• Each client organization has different feature sets
• Internal employees get admin access
• Partners get limited access

Implementation:

Internal employees:

{
  "name": "Internal Employees",
  "conditions": [
    {"key": "organization_type", "value": "internal", "negate": false}
  ],
  "permission_ids": ["admin-permission-uuid"],
  "priority": 100
}

Partner organizations:

{
  "name": "Partner Access",
  "conditions": [
    {"key": "organization_type", "value": "partner", "negate": false}
  ],
  "permission_ids": ["partner-permission-uuid"],
  "agent_ids": ["partner-agent-uuid"],
  "priority": 50
}

Client-specific features:

{
  "name": "Client ABC - Advanced Features",
  "conditions": [
    {"key": "organization_id", "value": "client-abc", "negate": false}
  ],
  "permission_ids": ["advanced-features-uuid"],
  "priority": 80
}

Scenario 3: Role-Based Access Control

Business Requirements:

• Support agents: Access to support tools
• Managers: Access to analytics and reporting
• Admins: Full system access

Implementation:

Support agents:

{
  "name": "Support Agents",
  "conditions": [
    {"key": "role", "value": "support", "negate": false}
  ],
  "permission_ids": ["support-tools-uuid"],
  "agent_ids": ["support-agent-uuid"],
  "priority": 60
}

Managers:

{
  "name": "Manager Access",
  "conditions": [
    {"key": "role", "value": "manager", "negate": false}
  ],
  "permission_ids": ["manager-permission-uuid", "analytics-uuid"],
  "priority": 80
}

Admins:

{
  "name": "Admin Access",
  "conditions": [
    {"key": "role", "value": "admin", "negate": false}
  ],
  "permission_ids": ["admin-permission-uuid", "full-access-uuid"],
  "priority": 100
}

Testing Your Rules

Method 1: Verify via Admin UI

Check a user’s profile in the admin panel to see what fields are available for rule matching:

1. Navigate to Settings → User Management → Users
2. Select the user you want to inspect
3. Review the Additional Info section to see available fields and values
4. Confirm the fields match what your rules expect

Method 2: Test with a Sample User

To verify a rule works as expected:

1. Create or identify a test user whose additional info matches your rule conditions
2. Log in as that user (or use impersonation if available)
3. Confirm the user sees the expected agents, knowledge sources, and features based on the applied permissions

Best Practices

1. Use Descriptive Names: Make rule names clear and specific
2. Set Appropriate Priorities: Higher priority for more specific rules
3. Test in Development: Verify rules work before deploying to production
4. Document Business Logic: Keep track of why each rule exists
5. Regular Audits: Review and update rules periodically
6. Use Consistent Naming: Stick to snake_case for field names
7. Monitor Performance: Watch for rules that may need optimization

Troubleshooting

Rule Not Applying

1. Check if the rule is active
2. Verify the user has the expected additional info fields
3. Check field names match exactly (case-sensitive after normalization)
4. Ensure all conditions in the rule match (AND logic)
5. Check if a higher-priority rule might be overriding

Field Not Found

1. Verify JWT field mapping is configured correctly
2. Check JWT actually contains the expected field
3. Check the user’s additional info fields in Settings → User Management → Users
4. Ensure field name normalization is working correctly

Unexpected Permissions

1. Check all active rules that might apply
2. Remember rules are cumulative (user gets ALL matching permissions)
3. Review priority settings
4. Check for wildcard domain rules that might apply