abas Software GmbH

Prerequisites

For the following guide, you’ll need:

  • To have the Keycloak module installed for your organization, ideally using the abas installer

  • To know your Keycloak URL where the admin console from Keycloak can be accessed.

  • To have an admin user name and password for your Keycloak instance.

  • To have the connection information for your LDAP server (hostname, port, Bind DN or user and your Bind password)

Getting started

Optional step: OpenLDAP container with demo data

If you just want to test LDAP integration on a local machine, you can use any LDAP container. One such container that is pre-populated with data for test purposes can be found here. It can be run with the following commands (see the readme at dockerhub for this image for credential information):

docker pull rroemhild/test-openldap
docker run --privileged -d -p 389:389 -p 636:636 rroemhild/test-openldap
You can also use your company LDAP in READ_ONLY mode to see how it will look like in the end instead of the test container above. You’ll need to adapt the given steps to your own company Active Directory/LDAP server implementations accordingly.

Recommend Step: Setup an LDAP Viewer for Reference

Before beginning the LDAP setup, it is helpful to be able to browse the AD/LDAP structure so that you can set up the integration properly. You can use any LDAP browser for this purpose. Possible tools for this purpose include "Apache Directory Studio" (version 2.0.0.v20180908-M14 when this guide was written), which can run on any platform, or if you have a Windows system and want to integrate with Active Directory, you can use ADExplorer.

Install Apache Directory Studio as a standalone RCP application and not an Eclipse plugin. If you install the plugin version of Eclipse, the steps below may vary for you.

Proceed as follows to create a connection for browsing LDAP information using "Apache Directory Studio":

  • Click "File→New …​"

  • Expand the "LDAP Browser" node and select "LDAP Connection".

  • Enter your company’s appropriate LDAP information on the wizard page that comes next. Also, as a precaution, select the read-only checkbox to avoid inadvertently changing anything.

  • Click "Check Network Parameter" to see if you have provided the right parameters.

  • Click "Next".

  • If you use the demo data container from the previous section, it might look like this:

Apache LDAP connection wizard - Network parameter screen
Figure 1: Apache LDAP connection wizard - Network parameter screen
  • In the next screen, configure your authentication method and provide the Bind user and password. Click "Check Authentication" to see if you have provided the right parameters. "Click Next".

Apache LDAP connection wizard - Authentication screen
Figure 2: Apache LDAP connection wizard - Authentication screen
  • Continue to the other screens and see if you need to configure anything. Click "Finish" when done. If you have successfully completed this step you will be able to browse your LDAP server like in the screenshot below.

Apache Browse LDAP
Figure 3: Apache Browse LDAP

First Steps for setting up user federation with Keycloak

  • To set up user federation with Keycloak, navigate to the Keycloak application using the hostname and https port you supplied during the installation. For this guide this URL is "https://arcturus.fritz.box:9091/auth".

  • This will take you to the Welcome page. Click "Administration Console" on this page.

Keycloak Welcome page
Figure 4: Keycloak Welcome page
  • This will take you to the login screen. Enter your admin user name and password you used to set up Keycloak. On a fresh install, this might be the user name "admin" and the password "admin". You should change them if this is the case.

Keycloak Login page
Figure 5: Keycloak Login page
  • After successfully logging in, click the "User Federation" menu on the left-hand side to arrive at the following page. .Keycloak User federation menu

    image::06-keycloak.png[Keycloak User federation menu]

  • This page only appears if you are adding a provider for the first time.

  • Otherwise, you will see a list of configured providers already in the system. In this case you can add a new provider by selecting one from a list of providers shown at the top-right of the table.

  • Select the "ldap" entry from the dropdown list.

Keycloak User federation menu in table view
Figure 7: Keycloak User federation menu in table view
  • The page will automatically open a form to fill in your LDAP connection parameters. The form will initially be empty as shown below:

Keycloak User federation page
Figure 8: Keycloak User federation page

Settings for OpenLDAP demo data

  • Enter an appropriate name in the "Console Display Name" field.

  • Proceed to the "Vendor" drop down list. Select the LDAP vendor that you want to configure. This will usually fill in reasonable defaults for many of the fields. The "Help" icon in Keycloak next to each field provides a good description of what is required as well as example values for AD or LDAP.

Keycloak User federation page filled form
Figure 9: Keycloak User federation page filled form
  • Use the LDAP browser tool to verify the values for your LDAP server as below by navigating to a user entry in the LDAP tree and selecting it to view details. These value must exist on your LDAP server, or you must provide the equivalent values you used for your setup here.

  • Most companies have the "UUID LDAP attribute" value set as "entryUUID". If you do not have this field, then just use another unique identifier. In our demo data, we don’t have this field, so we will change this value to "uid".

  • "User Object Classes" is another field that needs to be modified for our demo data. In "Apache Director Studio" when you click the user, you can see the objectClass fields and values that the user has. In our case we have four values and Keycloak only filled in two values correctly. We need to provide the rest of the values in the chain, i.e. the complete value as "inetOrgPerson, organizationalPerson, person, top" to be able to find the person correctly.

  • Next provide the DN (Distinguished Name) of the LDAP tree where your users are. You can also see this path in Apache Director Studio and looks like this for our demo data:

"ou=people,dc=planetexpress,dc=com"
Apache Browse LDAP
Figure 10: Apache Browse LDAP
  • Optionally, if you need to filter users based on certain LDAP filters, you can specify a value in the "Custom User LDAP Filter" field. For example, to only add users from a certain group, you could enter a value like this:

(&(objectCategory=Person)(sAMAccountName=*)(memberOf=cn=CaptainPlanet,ou=users,dc=planetexpress,dc=com))
  • Set the search scope to one level, if only you want users from a single level.

  • If you have users arranged in subtrees and you want users from all levels, you can choose subtree of users here. Your filter, if any is defined, will be applied in any case.

  • Next provide the LDAP server details, same as you’ve already provided for Apache Director Studio, i.e. the connection URL (hostname prefixed with ldap://), the port, the admin Bind user name and password.

  • Click "Test Connection" and "Test Authentication". Both these tests should be successful.

  • The required fields in the form should now look like below.

Keycloak LDAP filled form
Figure 11: Keycloak LDAP filled form

Settings for Active Directory/AD

  • Enter an appropriate name in the "Console Display Name" field.

  • Proceed to the "Vendor" drop down list. Select the LDAP vendor that you want to configure. This will usually fill in reasonable defaults for many of the fields. The "Help" icon in Keycloak next to each field provides a good description of what is required as well as example values for AD or LDAP.

  • If you want to later setup SSO for the abas GUI, then the following are the suggested values for your setup to work correctly.

    • Vendor: Active Directory

    • User name LDAP attribute: sAMAccountName

    • RDN LDAP attribute: cn (default value, or your setup-specific value)

    • UUID LDAP attribute: objectGUID (default value, or your setup-specific value)

    • User Object Classes: person, organizationalPerson, user (default value, or your setup-specific value)

  • Optionally, if you need to filter users based on certain LDAP filters, you can specify a value in the "Custom User LDAP Filter" field. For example, to only add users from a certain group, you could enter a value like this:

(&(objectCategory=Person)(sAMAccountName=*)(memberOf=cn=CaptainPlanet,ou=users,dc=planetexpress,dc=com))
  • Set the search scope to one level, if only you want users from a single level.

  • If you have users arranged in subtrees and you want users from all levels, you can choose subtree of users here. Your filter, if any is defined, will be applied in any case.

  • Next provide the AD server details, same as you’ve already provided for Apache Director Studio, i.e. the connection URL (hostname prefixed with ldap://), the port, the admin Bind user name and password.

Instead of the hostname, you can also enter the domain name, such as ldap://mydomain.com. For this to work, the automatic search for an LDAP server via DNS must work. You can test if the search functions on Windows using the command "nslookup -type=srv _ldap._tcp.mydomain.com". Then test whether the list of servers discovered can be pinged. This does not always work, in which case you can enter your hostname directly.
  • Click "Test Connection" and "Test Authentication". Both these tests should be successful.

  • The required fields in the form should now look like below.

  • Click "Save" at the bottom of the page.

Syncing users from AD / LDAP

After successfully saving your LDAP settings from the previous section, new buttons will appear next to the "Save" and "Cancel" buttons as shown below.

Keycloak LDAP new Sync user buttons
Figure 12: Keycloak LDAP new Sync user buttons
  • Click "Synchronize all users".

  • Shortly afterwards an info box will appear at the top with a success message, and the number of users imported as well as other information. If this step fails for you and you cannot find any reason in your input fields, then you might need to head to the troubleshooting section and review the Keycloak logs in Debug mode.

Keycloak LDAP sync users
Figure 13: Keycloak LDAP sync users
  • At this point you can successfully view your imported users by clicking the "Users" menu on the left-hand side and then clicking "View all users" on the page that appears.

  • If you want to set up SSO for the abas GUI, verify the following for the users:

    • The "Username" column contains the Window’s login name

    • The columns "Email", "First Name" and "Last Name" contain the correct values for all users

Keycloak LDAP view users
Figure 14: Keycloak LDAP view users
  • If for some reason your user import fails, and you cannot figure out why, start Keycloak with Debug log level to find out what is wrong. You can read more about how to do this here. For example, a mistyped entryUUID field value might cause something like below. You can then see the error in the application logs:

Keycloak debug unsuccessful users import
Figure 15: Keycloak debug unsuccessful users import

Reference