Structuring Authorization in Keycloak: Use Organizational Models for Efficient Access Management

---

• The challenge of translating traditional organizational structures with roles and delegations into an identity and access management (IAM) system like Keycloak.
• The benefits of a well-structured Keycloak setup for streamlined authorization and security.

While Keycloak doesn't have a direct equivalent to the hierarchical Organizational Units (OUs) found in Active Directory, you can effectively achieve a similar logical structure using a combination of groups and custom attributes. Here's how:

Groups for Hierarchy

• Parent Groups: Create high-level groups to represent the top levels of your organization:
  • "Acme Corporation" (Top-level)
  • "Finance" (Child Group of Acme Corporation)
  • "Sales" (Child Group of Acme Corporation)
• Nested Groups: Nest groups to reflect more specific departments or teams:
  • "Accounting" (Child group inside "Finance")
  • "Marketing" (Child group inside "Sales")

Custom Attributes for Additional Structure

To supplement the group hierarchy, consider custom attributes:

• department (Attribute on User): Store the user's primary department affiliation.
• location (Attribute on User): Store office location or geographic region for the user.

Example Tree-like Representation

Acme Corporation
    ├── Finance
    │   └── Accounting
    └── Sales
        └── Marketing 

User: John Smith

• Group Memberships:
  • "Acme Corporation"
  • "Finance"
  • "Accounting"
• Custom Attributes:
  • department: "Accounting"
  • location: "New York"

Benefits of this Approach

• Flexibility: Adjust the group structure as your organization evolves.
• Authorization: Leverage groups directly for role-based access control within Keycloak.
• Filtering and Queries: Use custom attributes to filter or search users based on department, location, etc.

How to Implement in Keycloak

1. Group Creation: Navigate to the "Groups" section in Keycloak's management console and build your hierarchy.
2. Custom Attributes: Under "Realm Settings" -> "Attributes", define your custom attributes.
3. Assign to Users: Ensure you've configured a user provider (database or federated). Edit individual user profiles to assign groups and set attribute values.

Considerations

• Complexity: Very complex hierarchies with many nested levels might increase administrative overhead. Consider carefully if a simpler approach fits your needs.
• Reporting and Tooling: Keycloak might not have out-of-the-box reporting tools tailored for OU-like structures. You might need to develop or use external tools for visualizations and queries based on attributes.

Let's extend our example showing how to manage roles and permissions in Keycloak to align with your groups representing a hierarchical organization.

Roles in Keycloak

• Scope: Roles in Keycloak can be Realm-level (broad) or Client-specific (for a particular application).
• Types of Roles:
  • Simple Roles: Basic permission sets (e.g., "Employee," "Manager," "Accountant").
  • Composite Roles: Combine other roles. This helps manage more complex permission structures and inheritance.

Mapping Roles to Your Group Hierarchy

Scenario 1: Identify Permissions

• Finance Department:
  • "View Financial Reports"
  • "Edit Transaction Entries" (Accountant role only)
• Sales Department:
  • "View Sales Dashboard"
  • "Manage Leads" (Marketing role only)

Step 2: Create Roles in Keycloak

• Realm-Level Roles (If Suitable): "Employee" (as a baseline for all employees).
• Client-Specific Roles: Create roles in relevant clients (applications), such as:
  • "Finance App":
    • "View Financial Reports"
    • "Edit Transaction Entries"
  • "CRM App":
    • "View Sales Dashboard"
    • "Manage Leads"

Step 3: Assign Roles to Groups

1. Navigate to your top-level groups ("Finance," "Sales") in Keycloak.
2. Go to the "Role Mappings" tab.
3. Assign relevant realm-level and client-level roles to each group.

Example: "Finance" Group Role Assignments

• Realm-Level: "Employee"
• Finance App: "View Financial Reports"

Example: "Accounting" Nested Group

• Inherits: All roles from its parent group, "Finance."
• Additionally: "Edit Transaction Entries" within the "Finance App."

Benefits

• Efficient Authorization: Applying roles at the group level streamlines authorization management.
• Inheritance: Composite roles and nested groups can simplify large permission structures.

Key Points

• Start Simple: Begin with essential roles and expand as needed.
• Least Privilege Principle: Grant minimally required permissions for each role.

In Action

A user who is part of the "Accounting" group would automatically be able to:

• Access general employee areas ("Employee" role).
• View financial reports and edit transactions within the "Finance App."

Let's explore ways to represent managers and delegation scenarios within your Keycloak group and role structure. Here are a few techniques:

Method 1: Manager Role

• Create "Manager" Roles:
  • Realm-level: A simple "Manager" role if management privileges are broad.
  • Department-Specific: "Finance Manager," "Sales Manager" for specialized permissions within each department.
• Assign to Managers: Add the relevant manager role(s) to user profiles of individuals holding managerial positions.
• Authorization Implications: In your applications or APIs, check for the existence of manager roles to authorize actions like approving reports, etc.

Method 2: Hierarchical Groups

• Manager Subgroups: Create groups like "Finance Managers," "Sales Managers" nested within their corresponding main department groups.
• Assign Roles: Grant management-specific roles to these manager subgroups.

Method 3: Custom Attributes

• manager (Attribute on User): Store the ID or username of a user's direct manager.
• Authorization Logic: Within your applications, you can fetch the user's "manager" attribute and implement custom authorization checks (e.g., a leave approval request could be routed to the designated manager).

Delegation

For temporary delegation (e.g., manager on vacation), consider these options:

• Temporary Role Assignment: Temporarily grant the manager role to a user within the group during delegation. Revoke the role afterwards.
• Dynamic Authorization Logic:
  • Store delegation data in an external source (database).
  • Application logic queries this data to determine if a user has acting authority for another user during delegation periods.

Combined Example

• Groups:
  • "Finance"
  • "Finance Managers" (Nested within "Finance")
• Roles:
  • "Finance App - Approve Reports" (Assigned to "Finance Managers")
• Attribute:
  • "manager" on each user within Finance potentially stores the username of their direct manager.

Choosing the Best Approach

• Simple Management: Role assignment is often easiest for basic scenarios.
• Fine-Grained Delegation: Custom attributes and authorization logic provide the most flexibility for complex, temporary delegation.

Considerations

• Authorization Logic: Your applications need to be coded to handle manager role checks or attribute-based authorization.
• Maintenance: Ensure manager assignments in roles/attributes are updated when employees change positions.