RBAC Configuration

Role-Based Access Control configuration and management.

Overview

The platform uses hierarchical RBAC with granular permissions: - Roles: Admin, Developer, User, Service - Permissions: Resource-action pairs (e.g., agent:execute) - Groups: GitLab group-based role assignment - Inheritance: Roles inherit permissions from parent roles - Policy Engine: Open Policy Agent (OPA) enforcement

Role Hierarchy

graph TD
    A[Admin] --> B[Developer]
    B --> C[User]
    A --> D[Service Account]

Built-in Roles

Admin

Description: Full system access Permissions: All (*:*) MFA: Required Assignment: Manual only

Permissions:

{
  "role": "admin",
  "permissions": ["*:*"],
  "restrictions": {
    "mfa": "required",
    "ipWhitelist": ["10.0.0.0/8", "192.168.0.0/16"]
  }
}

Developer

Description: Agent execution, workflow creation Permissions: Agent and workflow operations MFA: Recommended Assignment: GitLab group llm-platform/developers

Permissions:

{
  "role": "developer",
  "permissions": [
    "agent:read",
    "agent:execute",
    "workflow:read",
    "workflow:create",
    "workflow:update",
    "workflow:delete",
    "mesh:communicate",
    "tracer:read",
    "mcp:connect"
  ]
}

User

Description: Read-only access Permissions: View agents and workflows MFA: Optional Assignment: Default for all authenticated users

Permissions:

{
  "role": "user",
  "permissions": [
    "agent:read",
    "workflow:read",
    "tracer:read"
  ]
}

Service Account

Description: Service-to-service authentication Permissions: Specific to service MFA: N/A (certificate-based) Assignment: Manual via API

Example (Agent Brain):

{
  "role": "service.agent-brain",
  "permissions": [
    "agent:execute",
    "mesh:register",
    "mesh:communicate",
    "ollama:inference"
  ],
  "authentication": "mtls"
}

Permission Model

Permission Format

permission = resource:action

Examples:
- agent:execute
- workflow:create
- mesh:communicate
- admin:configure

Wildcard Permissions

agent:*       # All agent operations
*:read        # Read all resources
*:*           # All operations (admin only)

Resource Types

Permission Assignment

Via GitLab Groups

Group Mapping:

groupMappings:
  - gitlabGroup: "llm-platform/admins"
    platformRole: "admin"
    permissions: ["*:*"]

  - gitlabGroup: "llm-platform/developers"
    platformRole: "developer"
    permissions:
      - "agent:*"
      - "workflow:*"
      - "mesh:communicate"

  - gitlabGroup: "llm-platform/ml-team"
    platformRole: "ml-engineer"
    permissions:
      - "agent:execute"
      - "model:train"
      - "model:deploy"

Via API

POST /api/v1/auth/roles/assign
Authorization: Bearer admin-token
Content-Type: application/json

Request:

{
  "userId": "user-123",
  "roles": ["developer", "ml-engineer"],
  "permissions": [
    "agent:execute",
    "workflow:create"
  ],
  "expiresAt": "2025-12-31T23:59:59Z"
}

Policy Enforcement

Open Policy Agent (OPA)

Policy Language: Rego

Example Policy:

package authz

import future.keywords

# Default deny
default allow = false

# Allow if user has required permission
allow {
  required_permission := concat(":", [input.resource, input.action])
  required_permission in input.user.permissions
}

# Allow if user has wildcard permission
allow {
  wildcard := concat(":", [input.resource, "*"])
  wildcard in input.user.permissions
}

# Allow if user is admin
allow {
  input.user.roles[_] == "admin"
}

# Deny if resource is classified and user lacks clearance
deny {
  input.resource_classification == "top-secret"
  not input.user.clearance == "top-secret"
}

# MFA required for sensitive resources
mfa_required {
  input.resource_classification == "sensitive"
}

mfa_required {
  input.user.roles[_] == "admin"
}

Enforcement Points

API Gateway:

app.use(async (req, res, next) => {
  const decision = await opa.evaluate({
    input: {
      user: req.user,
      resource: req.params.resource,
      action: req.method.toLowerCase(),
      context: {
        ip: req.ip,
        time: new Date(),
        userAgent: req.headers['user-agent']
      }
    }
  });

  if (!decision.allow) {
    return res.status(403).json({
      error: 'forbidden',
      required: `${req.params.resource}:${req.method.toLowerCase()}`,
      userPermissions: req.user.permissions
    });
  }

  if (decision.mfa_required && !req.user.mfaVerified) {
    return res.status(403).json({
      error: 'mfa_required',
      message: 'Multi-factor authentication required'
    });
  }

  next();
});

Attribute-Based Access Control (ABAC)

Enhanced access control with attributes:

Policy Example:

# Allow developer to deploy model if they own it
allow {
  input.action == "deploy"
  input.resource == "model"
  input.resource_owner == input.user.id
  input.user.roles[_] == "developer"
}

# Allow access during business hours only
allow {
  input.action == "execute"
  business_hours(input.context.time)
}

business_hours(time) {
  hour := time.hour
  hour >= 9
  hour < 17
}

Role Management

Create Custom Role

POST /api/v1/auth/roles
Authorization: Bearer admin-token
Content-Type: application/json

Request:

{
  "name": "ml-engineer",
  "description": "Machine learning engineer role",
  "permissions": [
    "agent:execute",
    "model:train",
    "model:deploy",
    "dataset:read",
    "dataset:create"
  ],
  "inheritsFrom": ["developer"],
  "restrictions": {
    "maxConcurrentJobs": 10,
    "maxGPUTime": "24h"
  }
}

Update Role

PATCH /api/v1/auth/roles/{roleId}
Authorization: Bearer admin-token
Content-Type: application/json

Request:

{
  "permissions": {
    "add": ["workflow:execute"],
    "remove": ["agent:delete"]
  }
}

List Roles

GET /api/v1/auth/roles
Authorization: Bearer admin-token

Response:

{
  "roles": [
    {
      "id": "role-admin",
      "name": "admin",
      "permissions": ["*:*"],
      "userCount": 3
    },
    {
      "id": "role-developer",
      "name": "developer",
      "permissions": ["agent:*", "workflow:*"],
      "userCount": 25
    }
  ]
}

Permission Auditing

Check User Permissions

GET /api/v1/auth/users/{userId}/permissions
Authorization: Bearer admin-token

Response:

{
  "userId": "user-123",
  "roles": ["developer", "ml-engineer"],
  "permissions": [
    "agent:read",
    "agent:execute",
    "workflow:create",
    "model:train",
    "model:deploy"
  ],
  "effectivePermissions": [
    "agent:*",
    "workflow:*",
    "model:*"
  ]
}

Audit Log

GET /api/v1/audit/authorization?userId=user-123&timeRange=24h
Authorization: Bearer admin-token

Response:

{
  "events": [
    {
      "timestamp": "2025-01-15T10:00:00Z",
      "userId": "user-123",
      "resource": "agent",
      "action": "execute",
      "decision": "allow",
      "reason": "permission:agent:execute"
    },
    {
      "timestamp": "2025-01-15T10:05:00Z",
      "userId": "user-123",
      "resource": "admin",
      "action": "configure",
      "decision": "deny",
      "reason": "missing:admin:configure"
    }
  ]
}

Best Practices

1. Principle of Least Privilege

Assign minimum required permissions:

// ❌ Too broad
assignRole(user, 'admin');

// ✅ Specific permissions
assignPermissions(user, [
  'agent:read',
  'workflow:create'
]);

2. Regular Access Review

Review permissions every 90 days:

npm run compliance:access-review --days 90

3. Temporary Access

Grant time-limited permissions:

await grantPermission(user, 'admin:audit', {
  expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000) // 24 hours
});

4. Separation of Duties

Prevent privilege escalation:

# Prevent user from approving their own changes
deny {
  input.action == "approve"
  input.resource_creator == input.user.id
}

Integration

TypeScript SDK

import { RBACClient } from '@bluefly/auth-client';

const rbac = new RBACClient({
  endpoint: 'https://auth.bluefly.io',
  apiKey: process.env.API_KEY
});

// Check permission
const canExecute = await rbac.hasPermission(user, 'agent:execute');

// Get all permissions
const permissions = await rbac.getUserPermissions(user);

// Assign role
await rbac.assignRole(user, 'developer');

Next Steps

• JWT Authentication →
• OAuth 2.0 →
• Security Architecture →
• FedRAMP Compliance →