Keycloak Admin Guide for Mach5 Role Management

This guide explains how to configure roles, composite roles, and groups in Keycloak to manage permissions in Mach5.

Overview of Mach5 Role Patterns

Mach5 uses structured role strings in the format:

admin
<namespace>:<name>/<permission>
<namespace>:<name>/<entity>:<name>/<permission>

where <name> can be
 a string
 * to match zero or more characters
 ? to match a single character

where <permission> can be
 create
 read
 update
 delete
 admin --> all the above

• namespace: Logical grouping, e.g., namespace:default
• entity-pattern: e.g., index:.kibana*
• permission: Action allowed, e.g., read, update, admin

Example Roles:

Configuring Client Roles

Roles are typically assigned at the client level for Mach5.

Steps:

1. Select the default realm
2. Go to Clients → [Your Client] → Roles.

Example YAML:

roles:
  client:
    mach5:
      - name: "admin"
        description: "Administrator role with full access"
        composite: false
      - name: "namespace:*/index:*/read"
        description: "Read access to indices"
        composite: false

Creating Composite Roles

Composite roles group multiple roles together, so assigning a composite role automatically grants all included roles.

Steps:

1. Select the default realm
2. Go to Clients → [Your Client] → Roles → Create Role.
3. Give it a Role Name, e.g., power-user.
4. Go to Associated roles → Assign Role.
5. Add other roles to this composite.
6. The roles to assign to the composite role must already exist. Create individual roles according to the Mach5 role pattern specification.

Example YAML:

roles:
  client:
    mach5:
      - name: "power-user"
        composite: true
        composites:
          client:
            mach5:
              - "namespace:*/create"
              - "namespace:*/read"
              - "namespace:*/delete"
              - "namespace:*/index:*/create"
              - "namespace:*/index:*/read"
              - "namespace:*/index:*/update"
              - "namespace:*/index:*/delete"
      - name: "read-user"
        composite: true
        composites:
          client:
            mach5:
              - "namespace:*/read"
              - "namespace:*/index:*/read"

Assigning Roles to Users

1. Navigate to Users → [Select User] → Role Mapping → Assign Role.
2. Select the client roles.
3. Assign roles (composite or individual) to the user.

Tip: Using composite roles avoids assigning multiple roles individually.

Using Groups

Groups allow assigning roles to multiple users at once:

1. Go to Groups → Create Group, e.g., Developers.
2. Navigate to Groups → [Select Group] → Role Mapping → Assign Role.
3. Assign roles (client or realm roles) to the group.
4. Add users to the group to inherit the roles automatically.

Example Role Assignments

Diagram: Users, Composite Roles, and Groups

         ┌───────────┐
         │  Users    │
         │───────────│
         │ Alice     │
         │ Bob       │
         │ Charlie   │
         └─────┬─────┘
               │
               ▼
         ┌───────────┐
         │  Groups   │
         │───────────│
         │ Developers│
         │ Auditors  │
         └─────┬─────┘
               │
               ▼
        ┌────────────────┐
        │ Composite Roles│
        │----------------│
        │ power-user     │
        │ admin          │
        │ read-only      │
        └─────┬──────────┘
              │
              ▼
        ┌────────────────────────────┐
        │   Individual Roles         │
        │----------------------------│
        │ admin                      │
        │ namespace:*/admin          │
        │ namespace:*/*:*/admin      │
        │ namespace:default/admin    │
        │ namespace:default/*:*/read │
        │ ...                        │
        └────────────────────────────┘

• Users inherit roles from Groups and Composite Roles.
• Composite Roles automatically include multiple individual roles, reducing manual assignment.
• Wildcards, admin and /admin follow Mach5’s internal regex rules for matching role patterns.

Admin Notes

• Use client-level roles for Mach5 permissions.
• Composite roles simplify permission management.
• Groups allow bulk assignment to multiple users.
• Role strings must follow <namespace>/<entity-pattern>/<permission> to work correctly with Mach5.