This is part 3 of Keycloak tutorial series, this guide will focus on Keycloak’s user federation with LDAP federation provider.
You may refer to the following links for previous completed tutorials:
- Part 1: Keycloak Installation
- Part 2: OIDC and Oauth 2 with Keycloak
- Part 3: Keycloak with User Federation
Source Code can be found from:
As part 3 was built on top of part 2, a separate branch in github was created. Refer to branch Part3_Keycloak_User_Federation for this Guide.
Keycloak user federation supports LDAP and Keberos, this quick guide will only cover the integration with one OpenLDAP.
What You Will build
This tutorial will cover how to configure Keycloak with User Federation provider via LDAP. We will use the JavaScript application to test the integration.
Below diagram illustrates the relationship between each component.
JavaScipt(JS) app connects with Keycloak via OIDC and Keycloak connects with LDAP via ldap protocol.
System information
OS: Ubuntu 20.04
JDK: 11.0.11
Maven: 3.6.3
Docker: 20.10.2
Docker-compose: 1.29.2
Keycloak: 15.0.2 (Launch via docker)
Spring Boot: 2.0.3.RELEASE
Apache Directory Studio: 2.0.0.v20210717-M17
Launch LDAP and Connect to LDAP
- Compare with first two parts of the tutorial, additional service ldap was added in the keycloak-docker.yml file, launch the all the service via keycloak-docker.yml
docker-compose -f keycloak-docker.yml upConfirm keycloak and Ldap starter properly from the logs.
If keycloak service start properly, you may see the following logs:
keycloak-demo | 11:29:20,511 INFO [org.jboss.as] (Controller Boot Thread) WFLYSRV0025: Keycloak 15.0.2 (WildFly Core 15.0.1.Final) started in 10058ms — Started 594 of 872 services (584 services are lazy, passive or on-demand)
keycloak-demo | 11:29:20,512 INFO [org.jboss.as] (Controller Boot Thread) WFLYSRV0060: Http management interface listening on http://127.0.0.1:9990/management
keycloak-demo | 11:29:20,513 INFO [org.jboss.as] (Controller Boot Thread) WFLYSRV0051: Admin console listening on http://127.0.0.1:9990
If LDAP service start properly, you may see the following logs:
keycloak-userfedertaion-ldap | Caution: previously defined variables will not be overriden.
keycloak-userfedertaion-ldap | /container/environment/99-default/default.yaml
keycloak-userfedertaion-ldap |
keycloak-userfedertaion-ldap | To see how this files are processed and environment variables values,
keycloak-userfedertaion-ldap | run this container with ‘ — loglevel debug’
keycloak-userfedertaion-ldap | *** Running /container/run/process/slapd/run…
keycloak-userfedertaion-ldap | 62280a60 @(#) $OpenLDAP: slapd (Aug 10 2017 19:12:46) $
keycloak-userfedertaion-ldap | Debian OpenLDAP Maintainers <pkg-openldap-devel@lists.alioth.debian.org>
keycloak-userfedertaion-ldap | TLS: warning: ignoring dhfile2. Configure Apache directory studio to connect to OpenLdap. Click File -> New and you will see the following wizard.
3. Select LDAP Connection and click Next
4. Fill in the following information and click Next:
Connection name: keycloak-tutorial
Hostname: localhost
Port: 389
5. Fill in the Bind DN or user information and password. In this tutorial, OpenLDAP is used so the default administrator’s DN is
Bind DN or user: cn=admin,dc=example,dc=org
Bind password: admin
6. Click Check Authentication to confirm the configuration is correct. If the configuration is correct, you will see the following message. Then click OK
7. Click Finish to create the connection. Open the keycloak-tutorial connect you just created, and expand the Root DSE folder, you may see the following information.
The users and group was configured in the directory.ldif under ldap-ldif folder.
Configure Keycloak User Federation
1. Let’s login to Keycloak’s admin console by visiting http://localhost:8080/auth/ and use the credential created in Part 1 to access the admin console.
2. Confirm you are in Keycloak-tutorial realm and click User Federation.
3. In this guide, we are using default provider. Click Add provider and select ldap. Default information will be populated.
4. Fill in the following information for the respective fields, please kindly noted that the setting need to be changed based on the ldif file you are using, different Ldap might have compeltely diffferent setting, try to get ldif file for the most accurate information.
Edit Mode: WRITEBLE
Sync Registrations: ON
Vendor: Other
Username LDAP attribute: uid
RDN LDAP attribute: uid
UUID LDAP attribute: uid
User Object Classes: inetOrgPerson, organizationalPerson,person,top
Connection URL: ldap://keycloak-userfedertaion-ldap:389
Users DN: ou=People,dc=example,dc=org
Bind DN: cn=admin,dc=example,dc=org
Bind Credential: admin
As the services are running in Docker container, please kindly note the connection url address.
Click Test connection and Test authentication to ensure the configuration are correct.
If you do not see the success message, kindly review any settings.
5. Click Save and you will see new buttons appear.
6. Click Synchronize All users, the users from LDAP will be sync to Keycloak.
7. Click Users on the left panel and click View all users. You will see two new users being imported.
8. You will see the following details after you click on the user 1001. You can see ldap appear under Federation Link, this information means that the user is imported and referred to ldap
9. Click Credentials tab, you will see the password is provided by ldap.
10. Lets test the log in by using the JS application.
http://localhost:8080/auth/realms/keycloak-tutorial/account/
You will be redirected to the Keycloak login page, key in the credential for the imported user.
Username: 1001
Password: pass
11. Once you login you will be able to see the user information.
12. Click User Federation on the left panel and click ldap, enable Sync Registrations and click Save. If you enable the Sync Registrations setting, newly created user in Keycloak can be synchronised into Ldap.
13. Lets create a user and sync the user back to LDAP. Click Users in Keycloak Admin Console and click Add user
14. Add the following fields in the form and click Save
Username: 1003
Email: 1003@example.com
First Name: Oliver
Last Name: James
User Enabled: ON
Email Verified: ON
15. A new user will be created in Keycloak and lets click Users on the left panel and check the user again.
16. Click User Federation on the left panel and click ldap, scroll down to the bottom of the page and click Synchronise all users and you will see the newly created. It is indicating 3 users had been updated. Kindly noted that if any user created in keycloak before the Sync Registration enabled, the user will not be sync to Ldap.
17. Let’s switch to Apache Directory Studio, right click dc=example, dc=org and select refresh. You will see a new user with uid=1003 had been sync from Keycloak.
18. It is possible to enable Automatic Synchronisation between Keycloak and Ldap, you may adjust the Sync Settings under the Ldap federation provider to allow Keycloak automatically perform update. Remember to save update you update the Sync Settings.
19. Click Mappers in the Ldap user federation provider and click Create to create a new mapper with type group-ldap-mapper.
20. Fill in the following information for the respective fields. Please kindly noted that the following configuration need to be configured based on Ldap setting, the following configuration only works for the Ldap we are using in this example. If you are trying to integrate with other Ldap, try go get the ldif file from your Ldap administration team.
Name: group-mapper
Mapper Type: group-ldap-mapper
Group Name LDAP Attribute: cn
Group Object Classes: groupOfUniqueNames
Membership LDAP Attribute: uniqueMember
Membership Attribute Type: DN
Membership User LDAP Attribute: uid
Mode: LDAP_ONLY
User Groups Retrieve Strategy: LOAD_GROUPS_BY_MEMBER_ATTRIBUTE
Member-Of LDAP Attribute: memberOf
Click Save, and you will see the following Success message.
21. As the automatic synchronisation is enabled in step 18, the group and user group mapping will be appear in Keycloak’s Groups panel. Click Groups on the left panel in Keycloak Admin Console. You will see two groups had been created.
22. Go to Users section.
And Click The user with username 1001.
Click Groups tab and you will notice user 1001 is having Administrator and Developer membership.
Conclusion
Congratulations, you had been successfully configure the Keycloak with LDAP integration for user and group synchronisation. A few points to take into consideration:
- It is generally not recommended to use Keycloak to manage Ldap eg create group in Keycloak and sync back to Ldap.
- It is possible to configure Keycloak to synchronise with multiple user federation provider, the configuration will not be cover here.
- If you would like to perform Keycloak Group and Keycloak Role Mapping, it is possible to be done in the respective groups
Thanks for reading the length tutorial.
