Integration of Atom with Ldap and Keycloak
This document aims to present the integration of Atom with LDAP and Keycloak to allow the creation of new users through a web interface.
The operating system used is Ubuntu 22.04.4 LTS with packages updated until September 5, 2024. The Atom test version will be used on Vagrant, OpenLdap installed on the Vagrant virtual machine, and Keycloak installed via Docker inside the virtual machine.
For this installation, we will follow the documentation available at: https://www.accesstomemory.org/en/docs/2.5/dev-manual/env/vagrant/
First, to install Atom, we need to install VirtualBox and Vagrant.
sudo apt install virtualbox vagrantBefore installing the Atom Vagrant, we need to modify the file /etc/vbox/networks.conf to allow network access.
sudo mkdir /etc/vbox
sudo touch /etc/vbox/networks.conf
sudo vim /etc/vbox/networks.confThe content of the file should be as follows:
* 10.0.0.0/8 192.168.0.0/16
* 2001::/64
After this configuration, we create a directory for Atom and initiate Vagrant to download the image.
mkdir atom-vagrant
cd atom-vagrant/
vagrant init artefactual/atom
vagrant upThe screen after Atom is initialized should look something like this:
Once Atom starts, it should be accessible at http://10.10.10.10/ with the username demo@example.com and the password demo.
For this installation, we will partly follow the documentation available at: https://help.scriptcase.net/portal/en/kb/articles/how-to-create-a-simple-ldap-database-on-linux, except for the final user creation step.
First, to perform the installation, we need to access the virtual machine where Atom is running on Vagrant. To do this, in the directory where the Atom installation was executed, we run the following command:
vagrant sshThe screen should look like this:
To install OpenLdap, execute the following commands:
sudo apt update
sudo apt install slapd ldap-utils vimDuring installation, you will be prompted for an admin password, with the following screen:
Set the password you want, for example, root. You will also need to confirm this password.
To configure OpenLdap, run the following command:
sudo dpkg-reconfigure slapdThe following screen will appear:
Select "No" on the first prompt.
Next, configure the domain where the users will be registered. For this example, we will use the domain teste.atom, but you can define any domain you wish for the users.
The following screen will appear:
Define the organization. In our example, it will be ldap-atom, although this configuration is not important.
The next screen will prompt you to set the admin password again. In our case, it will be root.
The following screen asks if you want to remove the database when uninstalling the server:
Select "Yes", although this is not relevant for our configuration.
Finally, select "Yes" to move the old configuration.
Now the initial Ldap configuration is complete.
To verify the configuration, execute the command:
sudo ldapsearch -x -b "dc=teste,dc=atom"The result should look like this, showing the admin account details:
To perform this integration, we will follow the documentation available at: https://www.accesstomemory.org/en/docs/2.7/admin-manual/customization/authentication/
First, we need to modify the factories.yml file. If you're making changes before installing and configuring Atom, modify the file in config/factories.yml. If after configuration, as in our case, modify the file in apps/qubit/config/factories.yml.
Run the following command:
sudo vim atom/apps/qubit/config/factories.ymlFind the section:
user:
class: myUserAnd replace it with:
user:
class: ldapUserClear the cache and restart the server with the following commands in the Atom installation directory (~/atom):
php symfony cache:clear
sudo systemctl restart php7.4-fpm.service
sudo systemctl restart nginx.serviceNext, access the server again at http://10.10.10.10/ and log in with the user demo@example.com and password demo. Go to Admin -> Settings.
In LDAP Authentication, configure the details of your OpenLdap server. Since the server is on the same machine as Atom, we will use localhost. The most important part is the Base DN, which is based on the domain configured for the users. In our case, we will use dc=teste,dc=atom.
This is what the LDAP configuration screen looks like:
At this point, the integration with LDAP is complete. To test, you can create a user in LDAP and check if you can log into Atom with it. This process involves a few steps, but if you prefer, you can skip directly to the Keycloak installation to create a user with that tool.
Inside the virtual machine (accessed with the command vagrant ssh), we will manually create a user in the Ldap database for testing purposes and later remove the user.
First, we generate an MD5 password hash using the password 123456:
sudo slappasswd -h {MD5}You will be asked to enter the password twice, and then the command will return a hash string. Copy this string for use in the user creation process.
Next, create the usuario.ldif file:
vim usuario.ldifInsert the following content:
dn: uid=usuario,dc=teste,dc=atom
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
objectclass: top
uid: usuario
mail: usuario@example.com
cn: Usuario
givenName: Usuario
sn: Sistema
userpassword: {MD5}4QrcOUm6Wau+VuBX8g+IPg==
After saving the file, run the following command to add the user to Ldap:
sudo slapadd -l usuario.ldif To verify that the user was successfully created, execute the command:
sudo ldapsearch -x -b "dc=teste,dc=atom"The result should look like this, displaying the newly created user:
Now you can access Atom at http://10.10.10.10/ and log in using the username usuario and password 123456. Login with the email won't work; only with the username.
Once you log in, return to the admin user demo@example.com and check if the user appears in Atom:
Using the Atom admin user (in our case demo@example.com), delete the user from Atom.
To remove the user from Ldap, access the virtual machine with vagrant ssh and run the following command:
sudo ldapdelete -v -c -D "cn=admin,dc=teste,dc=atom" -W "uid=usuario,dc=teste,dc=atom"You will be asked for the Ldap admin password, which we set as root. To verify that the user has been removed, run the following command:
sudo ldapsearch -x -b "dc=teste,dc=atom"The result should look like this, without the previously created user:
To install Keycloak, we will use Docker. This installation will be done inside the virtual machine (accessed via vagrant ssh).
Start by installing Docker. If Docker is already installed, skip to the next step.
To install Docker, follow the documentation available at: https://docs.docker.com/engine/install/ubuntu/. Run the following commands:
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-pluginDocker should
now be installed. To test, run the following command:
sudo docker run hello-worldThe result should be a screen like this:
To configure Keycloak, follow the documentation available at: https://www.keycloak.org/getting-started/getting-started-docker. Run the following command to start Keycloak in development mode:
sudo docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:25.0.4 start-devAfter running the command, the following screen should appear:
As the message notes, this command runs Keycloak in development mode, not production mode. Running in production is outside the scope of this document.
Keycloak should now be accessible at http://10.10.10.10:8080/ with the username admin and password admin.
The first configuration step is to create a new Realm. Access the dropdown menu in Keycloak and select Create Realm:
Enter the Realm name. In our case, it will be atom:
Ensure that the current Realm is the one you just created, as shown in the top left corner. Next, configure Ldap by going to User Federation in the left-hand menu:
Click Add Ldap Provider. Select the options corresponding to your server. For Vendor, select Other.
In Connection URL, enter ldap://10.10.10.10 to access the OpenLdap server we configured. Click Test connection to verify that the connection is working:
For Bind Type, select Simple. Set Bind DN according to the domain defined in our Ldap configuration, with the user admin. In our case, cn=admin,dc=teste,dc=atom. For Bind Credentials, enter the Ldap admin password. Click Test authentication to verify the connection with OpenLdap:
For Edit Mode, select WRITEABLE. Users DN is based on the domain created in our server, in this case, dc=teste,dc=atom. Set Username LDAP attribute to uid, RDN LDAP attribute to uid, and UUID LDAP attribute to uid. For User Object Classes, set person, organizationalPerson, inetOrgPerson, and top.
Disable Import Users. Once configured, click Save.
Go to the Ldap settings by clicking ldap url.
Go to the Mappers tab, click first name, and change LDAP Attribute to givenName. Click Save.
In the Mappers screen, click Add mapper, name it Full Name, and for Mapper Type, select full-name-ldap-mapper. Uncheck Write Only.
Keycloak should now be integrated with OpenLdap. To configure user creation, go to Realm Settings and open the Login tab. Enable User Registration and Forgot Password.
In the Themes tab, set Keycloak for all themes:
Click Clients in the left menu and select account. Here, you can configure login pages, redirect settings, and other options. For this example, we’ll leave them as default.
Note the URL for account creation: /realms/atom/account/. With this configuration, the account creation page will be accessible at http://10.10.10.10:8080/realms/atom/account/.
Accessing this link will bring you to the login screen. Click Register.
Fill out the registration form and click Register.
After registration, you will be directed to the user account page, where you can confirm or edit user details. This page can be customized in the settings. Click Save.
The user has been created in Ldap. Now, we can test the integration by logging into Atom. Go to http://10.10.10.10/ and log in with the username usuario and password 123456, which we registered earlier.
The login was successful.
Log out and access the admin account demo@example.com to verify that the user is registered in Atom:
By following these steps, we have integrated Atom with LDAP and Keycloak.
Some steps may vary significantly depending on your environment.
There are many additional configurations that could be made in Keycloak and Atom, such as customizing login pages to make the process more user-friendly.
As configured, users must log into Atom using their username, not their email address.
When deleting users using the Keycloak interface, the user is not removed from Atom but also cannot log in without being in Ldap. To completely remove a user, you must manually delete them in Atom.
Password changes and updates in Keycloak are working correctly.
Additional security configurations, such as email verification and password reset via email, can be set up in Keycloak.
However, changing the user password within Atom does not work; it doesn’t update in Ldap. This is a flaw in the Ldap-Atom integration, and fixing it would require modifying the integration plugin's code.
I hope this guide helps with completing this configuration.
Created by Murilo Ferraz