Role-Based Access Control

RBAC provides a straightforward way to manage access by assigning users to roles, and roles to permissions.

Overview

RBAC in Authrim allows you to:

• Define roles that represent job functions or responsibilities
• Assign permissions to roles
• Assign users to one or more roles
• Scope assignments globally, to an organization, or to a resource
• Evaluate access based on user’s role memberships

Concepts

Roles

Roles represent a set of permissions that can be assigned to users:

{
  "id": "role-admin",
  "name": "Administrator",
  "description": "Full system access",
  "permissions": ["users:read", "users:write", "users:delete", "settings:manage"]
}

Permissions

Permissions are fine-grained access rights:

<resource>:<action>

Examples:
- users:read
- users:write
- documents:delete
- settings:manage

Role Assignment

Users can be assigned to multiple roles:

{
  "user_id": "user-123",
  "roles": [
    { "role_id": "role-admin", "scope": "global" },
    { "role_id": "role-editor", "scope": "org", "scope_target": "org-123" }
  ]
}

API Reference

Create Role

POST /api/admin/roles
Authorization: Bearer <admin_token>
Content-Type: application/json

{
  "name": "Editor",
  "description": "Can edit content",
  "permissions": ["content:read", "content:write"]
}

List Roles

GET /api/admin/roles
Authorization: Bearer <admin_token>

Get Role

GET /api/admin/roles/{role_id}
Authorization: Bearer <admin_token>

Update Role

PATCH /api/admin/roles/{role_id}
Authorization: Bearer <admin_token>
Content-Type: application/json

{
  "description": "Can edit and publish content",
  "permissions": ["content:read", "content:write", "content:publish"]
}

Delete Role

DELETE /api/admin/roles/{role_id}
Authorization: Bearer <admin_token>

Assign Role to User

POST /api/admin/users/{user_id}/roles
Authorization: Bearer <admin_token>
Content-Type: application/json

{
  "role_id": "role-editor",
  "scope": "org",
  "scope_target": "org-123",
  "expires_at": 1735689600000
}

Remove Role from User

DELETE /api/admin/users/{user_id}/roles/{assignment_id}
Authorization: Bearer <admin_token>

Get User’s Roles

GET /api/admin/users/{user_id}/roles
Authorization: Bearer <admin_token>

Get Effective Permissions

Resolve a user’s effective permissions from direct role assignments and organization membership:

GET /api/admin/users/{user_id}/effective-permissions
Authorization: Bearer <admin_token>

List Role Assignments

GET /api/admin/roles/{role_id}/assignments
Authorization: Bearer <admin_token>

Token-Embedded Permissions

Authrim can resolve role and permission claims for tokens when the tenant and client claim policy allow it. For administrative review and debugging, prefer the effective-permissions endpoint above.

ID Token with Roles

{
  "sub": "user-123",
  "roles": ["admin", "editor"],
  "permissions": ["users:read", "users:write", "content:read", "content:write"]
}

Requesting Roles in Token

Include roles in the scope:

GET /authorize
  ?response_type=code
  &scope=openid+profile+roles
  ...

Runtime Checks

Use the Policy Service for service-to-service checks. These endpoints require the internal policy API bearer token configured for the policy worker.

POST /policy/check-role
Authorization: Bearer <policy_api_secret>
Content-Type: application/json

{
  "subject": {
    "id": "user-123",
    "roles": [{ "name": "admin", "scope": "global" }]
  },
  "role": "admin"
}

Response:

{
  "allowed": true
}

Policy Definition

RBAC policies can be defined in JSON:

{
  "version": "1.0",
  "roles": [
    {
      "id": "admin",
      "name": "Administrator",
      "permissions": ["users:read", "users:write", "settings:manage"]
    },
    {
      "id": "editor",
      "name": "Editor",
      "permissions": ["content:read", "content:write", "content:publish"]
    },
    {
      "id": "viewer",
      "name": "Viewer",
      "permissions": ["content:read", "users:read"]
    }
  ]
}

Permission Format

Custom roles use resource:action permissions such as users:read or content:publish. System and built-in roles may expose broader effective permissions, but custom role creation validates explicit permission names.

Best Practices

Role Design

1. Keep roles focused - Each role should represent a clear function
2. Avoid role explosion - Don’t create too many fine-grained roles
3. Use permission inheritance - Build higher-level roles on lower-level ones
4. Document roles - Include clear descriptions

Security

1. Principle of least privilege - Assign minimum required permissions
2. Regular audits - Review role assignments periodically
3. Separation of duties - Split sensitive operations across roles
4. Role lifecycle - Remove unused roles and assignments

Example: E-commerce Application

{
  "roles": [
    {
      "id": "customer",
      "permissions": ["orders:read:own", "profile:read:own", "profile:update:own"]
    },
    {
      "id": "support",
      "permissions": ["orders:read", "customers:read", "tickets:read", "tickets:write"]
    },
    {
      "id": "warehouse",
      "permissions": ["orders:read", "orders:update_status", "inventory:read", "inventory:update"]
    },
    {
      "id": "admin",
      "permissions": ["orders:read", "orders:update_status", "customers:read", "inventory:update"]
    }
  ]
}

Integration with ABAC

RBAC can be combined with ABAC for more flexible authorization:

{
  "effect": "allow",
  "condition": {
    "and": [
      { "role": "editor" },
      { "resource.status": "draft" }
    ]
  }
}

This allows editors to edit only draft content.

References

• NIST RBAC Model
• RFC 7662 - Token Introspection