Skip to content
Authrim

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
  • 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-admin", "role-editor"]
}

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

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


{
  "name": "Editor",
  "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"
}

Remove Role from User

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

Get User’s Roles

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

Token-Embedded Permissions

Authrim can embed permissions directly in access tokens for offline authorization:

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
  ...

Authorization Check

Check Permission

POST /api/authorize
Authorization: Bearer <access_token>
Content-Type: application/json


{
  "resource": "users",
  "action": "delete",
  "subject": {
    "user_id": "user-123"
  }
}

Response:

{
  "allowed": true,
  "reason": "User has role 'admin' with permission 'users:delete'"
}

Policy Definition

RBAC policies can be defined in JSON:

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

Permission Wildcards

  • * - All permissions
  • resource:* - All actions on a resource
  • resource:action - Specific action on resource

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:*"]
    },
    {
      "id": "warehouse",
      "permissions": ["orders:read", "orders:update:status", "inventory:*"]
    },
    {
      "id": "admin",
      "permissions": ["*"]
    }
  ]
}

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