LdapLoginModule

Configure Kpow to read authentication and role information from LDAP.

For specifics on JAAS / LDAP configuration see the Jetty LdapLoginModule docs.

Form or Basic Authentication?

Form-based authentication is the default login mechanism for Kpow.

Kpow supports both form-based and basic authentication. To use basic authentication, set:

JETTY_AUTH_METHOD=basic

Configuration

To enable LdapLoginModule authentication you must:

Create a JAAS configuration file
Set the AUTH_PROVIDER_TYPE=jetty environment variable.
Start the JAR or Docker container with -Djava.security.auth.login.config=/path/to/jaas.conf

JAAS Configuration

Create a JAAS LDAP configuration file (the kpow realm is very important).

See the Kpow Secure Configuration Guide for details of bindPassword encryption.

## Your configuration will vary depending on your LDAP setup

kpow {
  io.kpow.jaas.spi.LdapLoginModule required
  useLdaps="false"
  debug="true"
  contextFactory="com.sun.jndi.ldap.LdapCtxFactory"
  hostname="localhost"
  port="10389"
  bindDn="uid=admin,ou=system"
  bindPassword="AES:ARAOyh4tygxSknnTNknnuFXG+PYr0oLlN9UO/0XSq4RSOw=="
  authenticationMethod="simple"
  forceBindingLogin="true"
  userBaseDn="OU=Users,DC=example,DC=com"
  userRdnAttribute="uid"
  userIdAttribute="uid"
  userPasswordAttribute="userPassword"
  roleBaseDn="OU=Groups,DC=example,DC=com"
  roleNameAttribute="roleName"
  roleMemberAttribute="uniqueMember"
  roleObjectClass="groupOfUniqueNames";
};

JAAS Debugging

To debug JAAS LDAP connections, first add debug="true" to your config:

kpow {
  io.kpow.jaas.spi.LdapLoginModule required
  debug="true"
  ...
  ...

Then turn on Jetty JAAS debug-level logging, see Application Logs for example configuration.

Finally to (optionally) debug LDAP connection errors, enable Jetty IGNORE level logs by starting Kpow with the following Java system variable:

-Dorg.eclipse.jetty.util.log.IGNORED=true

Once configured you will find debug log lines in your application logs that provide insight into how the LdapLoginModule is operating.

Environment Configuration

To activate Jetty JAAS authentication set the environment variable AUTH_PROVIDER_TYPE=jetty

JAR Startup

Specify the JAAS config file by setting the following system property when starting the JAR:

-Djava.security.auth.login.config=/path/to/jaas.conf

Note: System properties must come after java but before -jar.

AUTH_PROVIDER_TYPE=jetty \
<... more env vars ...> \
java -Djava.security.auth.login.config=/opt/kpow/jaas.conf -jar /opt/kpow/latest.jar

Docker Container Startup

Note: The JVM provides an environment variable called JAVA_TOOL_OPTIONS that can be used in place of system properties. We use this the thread the JAAS config to Docker.

Set the environment variable:

JAVA_TOOL_OPTIONS=-Djava.security.auth.login.config=/path/to/jaas.conf

Note: When your JAAS config is on the host machine and not within the container you will need to configure a docker volume mount so that Kpow can read that configuration:

docker run --volume="/config/path:/config/path/" -p 3000:3000 --env-file ...

When starting the docker container you will see logging output similar to:

Picked up JAVA_TOOL_OPTIONS: -Djava.security.auth.login.config=/path/to/jaas.conf

Custom SSL Certificates

To use self-signed certificates for LDAPS, provide them in a truststore and override the JVM default truststore with the following JVM parameter on startup.

To alter JVM startup parameters on startup when using the Kpow Docker container, set the same but as the JAVA_TOOL_OPTIONS environment variable.

  -Djavax.net.ssl.trustStore=/etc/kpow-truststore/kpow-truststore.jks -Djavax.net.ssl.trustStoreType=JKS -Djavax.net.ssl.trustStorePassword=***

User Experience

When configured your users will be prompted to authenticate on each new browser session.