Role-Based Access Control (RBAC)

Summary

Role-Based Access Control (RBAC) is an authorization model that grants or denies access based on roles assigned to users. Instead of assigning permissions to individual users, RBAC associates permissions with roles and then assigns those roles to users. In Keymate, an RBAC policy defines a set of role references and, optionally, group references. When the platform evaluates an RBAC policy, it checks whether the authenticated user holds any of the specified roles or belongs to any of the specified groups. If a match is found, the policy grants access.

Why It Exists

Managing permissions at the individual user level does not scale. In organizations with hundreds or thousands of users, assigning permissions directly to each user creates an administrative burden and increases the risk of inconsistent access.

RBAC solves this by introducing an indirection layer — roles. A role represents a job function, responsibility level, or organizational position. Permissions attach to roles, and users acquire permissions by receiving role assignments. When a user's responsibilities change, administrators update the role assignment rather than modifying individual permissions.

This approach provides:

• Simplified administration — Add or remove a single role assignment instead of modifying dozens of individual permissions
• Consistent enforcement — All users with the same role receive identical permissions
• Auditable access — Role assignments create a clear trail of who has access and why
• Separation of duties — Distinct roles prevent any single user from holding conflicting permissions

Where It Fits in Keymate

RBAC is the most commonly used authorization model in Keymate. It serves as the foundation for permission management and often works alongside other models in composite policies.

Policy authoring: Administrators create RBAC policies through the Admin Console or the Policy Engine REST API. Each policy specifies one or more roles (and optionally groups) that grant access.

Runtime evaluation: When a permission check reaches the Authorization Decision Provider, the platform enriches the user's identity context with the full set of role assignments — both realm-level and client-level roles. The RBAC policy then checks whether the user holds any of the required roles.

Boundaries

What RBAC covers:

• Granting access based on role membership
• Granting access based on group membership
• Combining multiple role requirements in a single policy
• Supporting both realm-level and client-level role assignments

What RBAC does not cover:

• Attribute-based conditions (e.g., "allow only during business hours") — use ABAC
• Relationship-based access (e.g., "allow only if user is the document owner") — use ReBAC
• Composing multiple policy types into a single decision — use PBAC
• Risk-adaptive decisions based on context signals — use RADAC

How It Works

Policy Structure

An RBAC policy contains three key elements:

Element	Description
Roles	A list of role references. Each reference includes the role name and, optionally, the client that owns the role.
Groups	An optional list of group references. Group membership grants the same effect as role membership.
Fetch Roles	A flag that controls whether the platform retrieves the user's current role assignments from the identity provider at evaluation time, instead of relying on the token claims alone.

Evaluation Logic

When the Authorization Decision Provider evaluates an RBAC policy:

1. Role enrichment — The platform loads the user's complete set of role assignments (realm-level and client-level) into the evaluation context. This ensures the platform makes all assigned roles available, even if the token does not contain every role claim.
2. Role matching — The platform checks whether the user holds any of the roles listed in the policy.
3. Group matching — If the policy includes group references, the platform also checks group membership.
4. Decision — If any role or group matches, the policy produces a positive result. The decision strategy then determines the overall outcome.

Authoring Modes

RBAC policies support two authoring modes:

Mode	Description
Conditions	Visual builder in the Admin Console — select roles and groups from dropdown lists
Expression	Free-form expression using the Keymate policy expression language for advanced role matching logic

Diagram

Example Scenario

Scenario

A SaaS application needs to restrict invoice management to users with the "finance-manager" role. An administrator creates an RBAC policy that grants access to the invoices resource with read and write scopes for anyone holding the "finance-manager" role.

Input

• Actor: Authenticated user (user@example.com) with the finance-manager role assigned
• Resource: invoices with scopes read, write
• Action: Permission evaluation via the Authorization Decision Provider
• Context: clientId: acme-portal

Expected Outcome

• Decision: GRANT
• Why: The RBAC policy lists finance-manager as a required role. The platform enriches the user's identity with all role assignments and finds a match. The policy result is positive, and the decision strategy produces an overall GRANT.

Common Misunderstandings

• "RBAC requires roles to be in the token" — Not necessarily. When the Fetch Roles option is active, or when the platform performs role enrichment, the user's complete set of role assignments is loaded from the identity provider regardless of what the token contains.

• "An RBAC policy can only reference one role" — An RBAC policy can reference multiple roles and groups. Access is granted if the user matches any of the listed roles or groups (logical OR by default).

• "RBAC and ABAC are mutually exclusive" — They are complementary. RBAC handles role-based decisions, while ABAC handles attribute-based conditions. A PBAC composite policy can combine both in a single access decision.

warning

Role enrichment ensures evaluation accuracy, but it adds a call to the identity provider. For high-throughput scenarios, ensure the decision cache is active to avoid repeated enrichment for the same subject.

Design Notes / Best Practices

• Use client-level roles for application-specific permissions. Realm-level roles are shared across all applications in the realm. Client-level roles are scoped to a specific application and prevent unintended permission overlap.

• Combine RBAC with PBAC for layered access control. Use RBAC for coarse-grained role checks and add ABAC or RADAC policies as sub-policies within a PBAC composite for fine-grained context-aware decisions.

• Name roles descriptively. Role names like finance-manager or document-editor communicate intent. Avoid generic names like role-1 or admin-level-2.

tip

When multiple RBAC policies apply to the same resource, the decision strategy determines the outcome. Use AFFIRMATIVE (any role grants access) for additive models. Use UNANIMOUS (all policies must agree) for defense-in-depth scenarios.

Related Use Cases

• Restricting administrative operations to users with specific management roles
• Granting read-only access to reporting resources based on viewer roles
• Implementing department-level access through group membership
• Building tiered access levels (viewer, editor, admin) across a Multi-Tenant application

Related Docs

ABAC

Attribute-based conditions for context-aware authorization.

PBAC

Compose multiple policies into unified access decisions.

Policy Engine

Central service for managing authorization policies.

Policy Evaluation Model

How permission requests are evaluated and decisions produced.