Roles & Permissions (RBAC)

Role-Based Access Control is the classical authorization model. A permission names a single action on a resource (for example users:read). A role is a named bag of permissions. Users are assigned roles, and a user's effective permissions are the union of permissions from every role they hold, directly or through a group.

Use RBAC when access is mostly a function of job title — "admins can manage users, editors can edit content" — and the set of permissions is small enough to enumerate. When decisions depend on per-resource ownership, context, or relationships, combine RBAC with ABAC or Zanzibar.

---

Concepts

Permissions

A permission represents a specific action on a resource.

Example Permission	Description
users:read	View user profiles
users:write	Create and edit users
users:delete	Delete users
applications:manage	Full control over OAuth applications
audit-logs:read	View audit log entries
roles:assign	Assign roles to users

Permission slugs follow a resource:action convention.

Roles

A role is a named collection of permissions.

Role	Permissions
viewer	users:read, audit-logs:read
editor	users:read, users:write, applications:read
admin	All permissions
auditor	audit-logs:read, users:read

Role Assignment

Users can hold one or more roles. Effective permissions are the union across all assigned roles.

---

Managing Permissions

Create a Permission

1. Go to /orgs/{orgId}/portal/access-management/permissions.
2. Click Create Permission.
3. Fill in:

Field	Description	Example
Name	Human-readable name	Read Users
Slug	Machine-readable identifier	users:read
Description	What this permission grants	View user profiles and details

Via API

curl -X POST https://your-domain.com/orgs/{orgId}/api/v1/permissions \
  -H "Authorization: Bearer {admin_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Read Users",
    "slug": "users:read",
    "description": "View user profiles and details"
  }'

---

Managing Roles

Create a Role

1. Go to /orgs/{orgId}/portal/access-management/roles.
2. Click Create Role.
3. Fill in:

Field	Description	Example
Name	Display name	Editor
Slug	Machine-readable identifier	editor
Description	Role purpose	Can view and edit users and applications

4. Attach permissions to the role from the permissions list.

Via API

# Create a role
curl -X POST https://your-domain.com/orgs/{orgId}/api/v1/roles \
  -H "Authorization: Bearer {admin_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Editor",
    "slug": "editor",
    "description": "Can view and edit users and applications"
  }'

# Assign permissions to a role
curl -X POST https://your-domain.com/orgs/{orgId}/api/v1/roles/{roleId}/permissions \
  -H "Authorization: Bearer {admin_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": ["users:read", "users:write", "applications:read"]
  }'

---

Assigning Roles to Users

Via Portal

1. Go to /orgs/{orgId}/portal/access-management/users.
2. Select a user.
3. Click the Roles tab.
4. Add or remove roles.

Via API

# Assign a role to a user
curl -X POST https://your-domain.com/orgs/{orgId}/api/v1/users/{userId}/roles \
  -H "Authorization: Bearer {admin_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "roles": ["editor", "auditor"]
  }'

# List a user's roles
curl https://your-domain.com/orgs/{orgId}/api/v1/users/{userId}/roles \
  -H "Authorization: Bearer {admin_token}"

---

Roles in Tokens

When a user authenticates, their roles and effective permissions can be included as claims in the access token. The access token is a JWT (RFC 7519) — a signed JSON payload the client presents on each request.

{
  "sub": "user-uuid",
  "organization": "acme-corp",
  "roles": ["editor", "auditor"],
  "permissions": ["users:read", "users:write", "applications:read", "audit-logs:read"],
  "iat": 1706400000,
  "exp": 1706403600
}

Your application can verify the token signature and inspect these claims to make authorization decisions without a round trip back to LumoAuth.

---

Checking Permissions

In Your Application

Inspect the permissions claim on the verified access token.

// Node.js example
const token = jwt.verify(accessToken, publicKey);

if (token.permissions.includes('users:write')) {
  // Allow user edit
} else {
  // Deny access
}

Via Permission Tester

Use the Permission Tester at /orgs/{orgId}/portal/access-management/permission-tester to simulate an authorization decision for a given user, resource, and action.

---

Best Practices

Practice	Description
Principle of least privilege	Assign the minimum permissions needed
Assign permissions to roles, not users	Keeps user management simple
Consistent naming	Follow the resource:action convention
Avoid catch-all roles	Prefer focused roles over a single omnibus admin role
Audit role assignments	Review periodically who holds what

---

Related

• Groups — assign roles to groups for bulk management.
• ABAC — add attribute and context conditions to access decisions.
• Zanzibar — relationship-based access for hierarchical resources.
• Access Control Overview — compare all authorization models.