abas Software GmbH

Prerequisites

As a prerequisite to the following guide, you must have:

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

  • You must know your Keycloak url where the admin console from keycloak can be accessed.

  • You must have an admin username and password for your keycloak instance.

  • You must 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 want to just test LDAP integration on a local machine, then 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 simply 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. Please then adapt the given steps for your own company Active Directory/LDAP server implementations.

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 are "Apache Directory Studio" ( at the time of writing at version 2.0.0.v20180908-M14), that can run on any platform or if you have a Windows system and want to integrate with Active Directory you can also 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.

To create a connection for browsing LDAP info using "Apache Directory Studio", you can do the following:

  • Click File→New …​

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

  • On the wizard page that comes next provide your company’s appropriate LDAP information. Also, as a precaution select the read only checkbox on the button 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, this might look as below:

Apache LDAP Connection Wizard - Network Parameter Mask
Figure 1: Apache LDAP Connection Wizard - Network Parameter Mask
  • 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 write parameters. Click Next.

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

Apache Browse LDAP
Figure 3: Apache Browse LDAP

First Steps for Setting up User Federation with Keycloak

  • To set up user federation with keycloak, browse to the keycloak application using the hostname and https port you supplied during the installation. For this guide this url looks like "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 username and password you used to set up keycloak with. On a fresh install, this might be username "admin" and password "admin". You should change this, if so.

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

    Keycloak User Federation Menu
    Figure 6: Keycloak User Federation Menu
  • This page displays only if you are adding a provider for the very 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 on the top right of the table.

  • From the drop down list select the "ldap" entry.

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 you ldap connection parameters. The form will be initially empty as shown below:

Keycloak User Federation Page
Figure 8: Keycloak User Federation Page

Settings for OpenLDAP demo data

  • In the empty form field, give an appropriate name for the field "Console Display Name".

  • 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 also provides a good description of what is required and example values for AD or ldap.

Keycloak User Federation Page Filled Form
Figure 9: Keycloak User Federation Page filled Form
  • Use 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 alternative 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 also "uid".

  • "User Object Classes" is another field that needs to be modified for our demo data. In "Apache Director Studio" when you click on 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 2 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 Fill DN of the LDAP tree where your users are. This path you can also see 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 specify a value in the "Custom User LDAP Filter" field. For example to only add users from a certain group, you could put in a value that looks like this :

(&(objectCategory=Person)(sAMAccountName=*)(memberOf=cn=CaptainPlanet,ou=users,dc=planetexpress,dc=com))
  • Set search scope to one level, if you want users from only 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 defined, will be applied in any case.

  • Next provide our LDAP server details, same as you provided for Apache Director Studio already i.e. connection url (hostname prefixed with ldap://), the port, the admin bind username and password.

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

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

Keycloak LDAP filled Form
Figure 11: Keycloak LDAP filled Form

Settings for Active Directory/AD

  • In the empty form field, give an appropriate name for the field "Console Display Name".

  • 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 also provides a good description of what is required and example values for AD or ldap.

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

    • Vendor: Active Directory

    • Username 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 specify a value in the "Custom User LDAP Filter" field. For example to only add users from a certain group, you could put in a value that looks like this :

(&(objectCategory=Person)(sAMAccountName=*)(memberOf=cn=CaptainPlanet,ou=users,dc=planetexpress,dc=com))
  • Set search scope to one level, if you want users from only 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 defined, will be applied in any case.

  • Next provide you company AD server details, same as you provided for Apache Director Studio already i.e. connection url (hostname prefixed with ldap://), the port, the admin bind username and password.

Instead of the Hostname, you can also enter the domain name like (ldap://mydomain.com). For this to work, the automatic search for an LDAP-Server over DNS must function. You can test if the search functions on windows using the command "nslookup -type=srv _ldap._tcp.mydomain.com". Then test if the list of servers discovered are pingable. This does not always work, in this 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 now look like below.

  • Click the "Save" button 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 on "Synchronize all users" button.

  • Shortly afterwards an info box will appear on the top with a success message, and the number of users imported and so on. If this step fails for you and you cannot find any reason in your input fields, then you might need to head to the trouble shooting section and look at 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 on the "Users" menu on the left-hand side and click the button "View all users" on the page that appears.

  • If you will proceed to set up SSO for abas GUI, then verify the following for the users, whether:

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

    • the columns "Email", "First Name" and "Last Name" contain the correct values for any (and all given) users.

Keycloak LDAP View Users
Figure 14: Keycloak LDAP View Users
  • If for some reasons your user import fails, and you cannot figure out what you may be doing wrong, you might want to start Keycloak with Debug log level to find out what is wrong. You can read more about how to do this in the 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