Keycloak Security

This guide describes the configuration of the Keycloak implementation of Apache Isis' Authenticator and `Authorizor APIs.

Maven pom.xml

Dependency Management

If your application inherits from the Apache Isis starter app (org.apache.isis.app:isis-app-starter-parent) then that will define the version automatically:

pom.xml
<parent>
    <groupId>org.apache.isis.app</groupId>
    <artifactId>isis-app-starter-parent</artifactId>
    <version>2.0.0-M6</version>
    <relativePath/>
</parent>

Alternatively, import the core BOM. This is usually done in the top-level parent pom of your application:

pom.xml
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.apache.isis.core</groupId>
            <artifactId>isis-core</artifactId>
            <version>2.0.0-M6</version>
            <scope>import</scope>
            <type>pom</type>
        </dependency>
    </dependencies>
</dependencyManagement>

Dependency

In the webapp module of your application, add the following dependency:

pom.xml
<dependencies>
    <dependency>
        <groupId>org.apache.isis.mavendeps</groupId>
        <artifactId>isis-mavendeps-webapp</artifactId>
        <type>pom</type>
    </dependency>
</dependencies>

Update AppManifest

In your application’s AppManifest (top-level Spring @Configuration used to bootstrap the app), import the

AppManifest.java
@Configuration
@Import({
        ...
        IsisModuleSecurityKeycloak.class,
        ...
})
public class AppManifest {
}

Make sure that no other IsisModuleSecurityXxx module is imported.

Design

The module configures a filter that expects Keycloak to set three X-Auth-Xxx headers:

  • X-Auth-Userid - is used as the username

  • X-Auth-Roles - is a comma-separated set of roles.

    The org.apache.isis.viewer.wicket.roles.USER role — as required by Web UI (Wicket viewer)  — is automatically added to this list of roles.

  • X-Auth-Subject - is unused

The user and roles are accessible programmatically from the UserMemento obtained from UserService domain service.

Walk-through

TODO - show how this fits together.