Keycloak Authorization System: A Practical Guide to Resources, Scopes, Permissions, and Policies

Introduction

In modern application development, authorization management is a critical aspect of system security. Keycloak, as an open-source identity and access management solution, offers robust authorization services supporting role-based access control (RBAC) and attribute-based access control (ABAC). This article aims to dissect the core components of Keycloak's authorization system—resources, scopes, permissions, and policies—through a specific migration case, exploring how to design and implement a scalable authorization model efficiently.

Core Concepts Explained

Keycloak's authorization system is built on fundamental concepts: resources, scopes, permissions, and policies. Resources represent objects that need protection, such as API endpoints or data entities; scopes define operations that can be performed on resources, like view, edit, or delete; permissions associate resources or scopes with policies to determine access; policies are logical units for authorization decisions, based on roles, user attributes, or other conditions.

When migrating traditional RBAC systems, common challenges include mapping existing "capabilities" to Keycloak components. For example, a "viewAccount" capability might correspond to an "account" resource and a "view" scope. However, design decisions require balancing flexibility and complexity. It is recommended to create independent scopes for each resource (e.g., "account:view" and "transaction:view") rather than using a globally shared "view" scope, which enhances security and maintainability. Industry practices, such as Slack and Box API designs, validate this approach.

Permission Types and Design Strategies

Keycloak supports two main permission types: resource-based permissions and scope-based permissions. Resource-based permissions apply directly to resources, while scope-based permissions can be associated with scopes or combinations of resources and scopes. In practice, the choice depends on business needs. For instance, resource-based permissions may be suitable for unified control over all operations on a resource, whereas scope-based permissions offer finer control for specific actions.

Permission design should avoid creating separate permissions for every resource-scope combination, as this can increase management complexity. Instead, aggregated policies can combine multiple policies and associate them with permissions. For example, a "help desk access" policy can include multiple roles or groups, then be applied to a "viewAccount" permission. Keycloak also supports group-based policies, allowing management of multiple groups without creating individual policies for each.

Decision Strategies and Authorization Workflow

Keycloak's authorization decisions rely on decision strategies, including "Unanimous" and "Affirmative" modes. Unanimous requires all relevant permissions to evaluate to permit for access to be granted, while Affirmative only needs at least one permission to permit. Decision strategies can be configured at the resource server level and individual permission level, providing flexible authorization control.

For example, suppose a resource has two permissions: Permission A evaluates to permit, and Permission B evaluates to deny. If the resource server's decision strategy is set to Unanimous, access will be denied; if set to Affirmative, access will be permitted. This mechanism enables Keycloak to handle complex authorization scenarios, such as resolving conflicting permissions. In configuration, decision strategies should be chosen carefully to ensure consistency in security policies.

Practical Example: Bank API Authorization Configuration

To demonstrate Keycloak's authorization system in action, we construct a simple bank API scenario. Assume a "bank-api" client needs to protect a "/account/{id}" resource with a defined "account:view" scope. User "bob" can have roles such as "bank_teller", "account_owner", or "user". Authorization is configured through these steps:

1. Create a resource "View Account Resource" with URI "account/{id}", associated with scope "account:view".
2. Create role-based policies: "Only Bank Teller and Account Owner Policy" (allowing bank_teller and account_owner roles) and "Only Account Owner Policy" (allowing only account_owner role).
3. Create a resource-based permission "View Account Resource Permission", applying "Only Bank Teller and Account Owner Policy", with decision strategy set to Unanimous.
4. Create a scope-based permission "View Account Scope Permission", applying "Only Account Owner Policy", with decision strategy set to Unanimous.

Using Keycloak's evaluation tool to test authorization: When bob has the "user" role, access is denied; with the "bank_teller" role, access is denied due to lack of scope permission (if the resource server decision strategy is Unanimous); with the "account_owner" role, access is permitted. By adjusting decision strategies, different authorization outcomes can be observed, highlighting the importance of configuration.

Best Practices and Conclusion

When designing a Keycloak authorization system, follow these best practices: First, clearly distinguish between resources and scopes, avoiding over-generalization; second, choose permission types appropriately, leveraging aggregated policies to simplify management; third, configure decision strategies based on security requirements to ensure clear authorization logic; finally, regularly test policies using evaluation tools to verify authorization behavior.

Keycloak's authorization system offers high flexibility and scalability, adapting to various scenarios from simple RBAC to complex ABAC. By deeply understanding its core concepts and configuration options, developers can build secure and efficient access control mechanisms. This discussion is based on Keycloak 8.0.0, but core principles apply to later versions. In real-world projects, refer to official documentation and community resources for up-to-date information and best practices.