AKHQ ACL Mapper for Keycloak

AKHQ ACL Mapper is a custom protocol mapper for Keycloak that supports AKHQ's latest ACL requirements as of version 0.25.0 when using Direct OIDC mapping. This mapper can be used as a simple way to transition from previous AKHQ versions for setups that use group attributes to adapt the UI to a logged in user. These attributes can use the previous regex expressions for defining ACLs, or a newer syntax that can leverage more features of the latest ACL system while having greater control over what roles are used.

Features

• Maps previous topics-filter-regexp, connects-filter-regexp, consumer-groups-filter-regexp, etc. group attributes to new ACLs.
• Define resource specific ACLs using previous syntax and or using a newer syntax for greater flexibility.
• Supports customizing the groups claim name for the ACL substructure in case it is already in use.
• Basic debugging support.

Prerequisites

• Keycloak 25.0.0 or newer (20.0.0+ may also work).
• AKHQ 0.25.0 or newer.
• Java 17+ (Temurin/Adopt) OpenJDK if building the Java-based project.
• Optional: Maven 3.8.4+ CLI for compiling the Java-based project.

Building

The following are the build steps needed for both flavors of the mapper available in this repo.

Java-based project

To build the JAR file, run the following command inside the java folder:

./mvnw clean package

There should now be a file called akhq-acl-mapper-<version>-bin.jar in the target folder that can be used for deploying the mapper.

Node.js-based project

To build the JAR file, zip together the META-INF folder and the akhq-acl-mapper-script.js file found in the nodejs folder. After, change the .zip extension to the .jar extension. For more information, see Create a JAR with the scripts to deploy.

Usage

The following describes what is needed to get up and running with this mapper.

Install custom provider for traditional setups

When using a traditional setup, place the JAR file into the providers folder of Keycloak. Restart the Keycloak server with the following command:

Java-based mapper

bin/kc.[sh|bat] start-dev

Tip

Ignore SPI warning (KC-SERVICES0047) for implementing the internal SPI protocol-mapper, it's expected. See keycloak/keycloak#9974 for more information.

Node.js-based mapper

bin/kc.[sh|bat] start-dev --features=scripts

Note

These command examples start Keycloak in development mode for testing only. The command used for the Node.js mapper also enables the required scripts preview feature in order to be supported.

Install custom provider for Kubernetes setups

When using a Kubernetes setup with Keycloak installed via the Bitnami Helm Chart, modify the chart's values.yaml file to include the following configuration:

Java-based mapper

initdbScripts:
  load_custom_provider_script.sh: |
    #!/bin/bash
    echo "Running load_custom_provider_script.sh..."
    # Replace 'latest' in the URL with a specific version like 0.3.0 to pin to a release.
    curl -SsLf https://github.com/StevenJDH/akhq-acl-mapper/releases/download/latest/akhq-acl-mapper.jar -o /opt/bitnami/keycloak/providers/akhq-acl-mapper.jar

containerSecurityContext:
  readOnlyRootFilesystem: false

Node.js-based mapper

initdbScripts:
  load_custom_provider_script.sh: |
    #!/bin/bash
    echo "Running load_custom_provider_script.sh..."
    # Replace 'latest' in the URL with a specific version like 0.3.0 to pin to a release.
    curl -SsLf https://github.com/StevenJDH/akhq-acl-mapper/releases/download/latest/akhq-acl-mapper-script.jar -o /opt/bitnami/keycloak/providers/akhq-acl-mapper-script.jar

extraEnvVars:
  - name: KEYCLOAK_EXTRA_ARGS
    value: "--features=scripts"

containerSecurityContext:
  readOnlyRootFilesystem: false

Note

The configuration used for the Node.js mapper enables the required scripts preview feature in order to be supported.

Configure user group attributes

Ensure that the user group attributes match the topics-filter-regexp, connects-filter-regexp, and consumer-groups-filter-regexp keys. If they don't, then they will either need to be updated in Keycloak or the code/script adjusted to match. Additionally, the registry-filter-regexp and acls-filter-regexp keys are supported.

The previous regex expressions used in the group attributes are still supported if migrating from previous versions of AKHQ. However, only *-reader roles will be applied for resources defined in this way. The AKHQ ACL Mapper supports defining ACLs using a newer syntax, which offers a number of benefits such as defining *-writer roles, using custom role names defined in AKHQ, and support for multiple clusters. The new syntax uses key value pairs separated by commas using the keys role, pattern, and the optional cluster key. For example, if topics-filter-regexp previously held a value of test.*, then in the new approach, this could be written as role:topic-writer,pattern:test.*,cluster:example.* or role:topic-writer,pattern:test.*. For reference, the build-in AKHQ roles use the format <resource>-<reader|writer|admin> such as topic-admin, acl-reader, registry-writer and so on.

Add custom protocol mapper

In Keycloak, perform the following steps:

1. Go to Clients, select the client used for AKHQ, and navigate to the Client scopes tab.
2. Select the <akhq>-dedicated item in the list.
3. Click the Configure a new mapper or Add mapper > By configuration button, and select the AKHQ ACL Mapper type in the list that appears.
4. Configure the mapper as follows:
   • Name: akhq-acl-mapper
   • Token Claim Name: groups (Must match setting in AKHQ for akhq.security.oidc.<label>.groups-field)
   • Claim JSON Type: JSON
   • Add to ID token: On
   • Add to access token: Off

Testing the mapper

Under the Client scopes tab of the AKHQ client configuration, select the Evaluate sub-tab. In the Users field, select a user associated with a group that has attributes configured for AKHQ. Then, on the right, click the Generated ID token button. There should now be a groups claim in the generated token on the left that has the required ACL structure similar to the following:

{
  "exp": 1725228553,
  "iat": 1725228493,
  "jti": "2fd02132-646f-47a4-8059-35e45568d06b",
  "iss": "http://localhost:8080/realms/master",
  "aud": "akhq",
  "sub": "a123346f-a37e-4369-807f-b313308a7ef4",
  "typ": "ID",
  "azp": "akhq",
  "sid": "bfc80bf8-6c10-46cb-8906-cab245b886e3",
  "acr": "1",
  "email_verified": true,
  "name": "john doe",
  ...< additional claims ommitted >...
  "groups": {
    "project-x": [
      {
        "role": "topic-writer",
        "patterns": [
          "test.*"
        ],
        "clusters": [
          "example-*"
        ]
      },
      {
        "role": "group-reader",
        "patterns": [
          ".*"
        ]
      },
      {
        "role": "connect-reader",
        "patterns": [
          ".*"
        ]
      },
      {
        "role": "registry-reader",
        "patterns": [
          ".*"
        ]
      },
      {
        "role": "acl-reader",
        "patterns": [
          ".*"
        ]
      }
    ]
  },
  "preferred_username": "j.doe",
  "given_name": "john",
  "family_name": "doe",
  "email": "j.doe@example.com"
}

Contributing

Thanks for your interest in contributing! There are many ways to contribute to this project. Get started here.

Do you have any questions?

Many commonly asked questions are answered in the FAQ: https://github.com/StevenJDH/akhq-acl-mapper/wiki/FAQ

Want to show your support?

Method	Address
PayPal:	https://www.paypal.me/stevenjdh
Cryptocurrency:	Supported options

// Steven Jenkins De Haro ("StevenJDH" on GitHub)