Requirements
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. |
Recommended step: Setup an LDAP Viewer for Reference
Before beginning the LDAP setup, it is helpful to be able to browse the AD/LDAP structure in order to set up the integration properly. You can use any LDAP browser for this purpose. Possible tools for this include "Apache Directory Studio" (Version 2.0.0.v20180908-M14 at the time of writing this guide) which can run on any platform, or ADExplorer, if you have a Windows system and want integration with Active Directory.
| 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".
-
An assistant window opens. Enter your company’s appropriate LDAP information here. 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:
-
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".
-
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.
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.
-
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.
-
After successfully logging in, click the "User Federation" menu on the left-hand side to arrive at the following page. .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.
-
The page will automatically open a form to fill in your LDAP connection parameters. The form will initially be empty as shown below:
-
After the above step, you might want to continue to one of the following sections depending on your requirement.
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.
-
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. We do not have this field in our demo data. For this reason, we 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 full DN (Distinguished Name) of the LDAP tree where your users are located. You can also see this path in Apache Director Studio. It looks like this for our demo data:
"ou=people,dc=planetexpress,dc=com"
-
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.
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 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 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.
-
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.
-
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
-
-
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. Further information can be found in the output. For example, a mistyped entryUUID field value might cause something like below. You can then see the error in the application logs:
