Integrating OpenLDAP with NineData SSO

This guide is for teams that manage employee accounts in OpenLDAP. It shows how to connect OpenLDAP to NineData SSO so users can authenticate once and sign in to NineData through Keycloak and phpLDAPadmin.

Background

OpenLDAP is an open-source LDAP server for storing and managing user accounts and identity data. Many enterprises run several application systems at the same time, and each system usually has its own login and permission model. When OpenLDAP is connected to SSO, users sign in once and then access the connected systems without repeating login and account management.

Prerequisites

• You have already created or joined an organization, and the organization has subscribed to DevOps Enterprise. Please ensure that your annual or monthly subscription is still active. For more information, please refer to Manage Organizations.
• Your current account has been switched to the target organization. For more information, please refer to Switching to an Organization.

• You have root access to the LDAP server. Use sudo su to switch to the root account before you start.

Environment

This guide walks through the setup from scratch. If a tool is already installed, skip the corresponding step. The environment used here is:

• System version: CentOS Linux release 7.9.2009

  tip

  You can view the current system version by executing the cat /etc/*release command in the command line.

• Docker version: 24.0.0

• Docker Compose version: 2.17.3

• OpenLDAP version: 2.4.57

• phpLDAPadmin version: 1.2.5

• Keycloak version: 9.0.0

Step 1: Install Docker and Docker Compose

This guide uses Docker and Docker Compose to run OpenLDAP, phpLDAPadmin, and Keycloak.

Use the yum commands below on RPM-based Linux distributions such as CentOS or Red Hat Enterprise Linux (RHEL).

Click to expand process description

Install Docker

1. Open a terminal and run the following command to uninstall any existing Docker packages:

   sudo yum remove docker docker-client docker-client-latest docker-common docker-latest docker-latest-logrotate docker-logrotate docker-engine

2. Install yum-utils:

   sudo yum install -y yum-utils

3. Add the Docker stable repository:

   sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

4. Install Docker:

   sudo yum install docker-ce docker-ce-cli containerd.io

5. Start Docker:

   sudo systemctl start docker

6. Verify that Docker is installed:

   sudo docker run hello-world
   tip

   If the following output appears, Docker is installed successfully:

   Hello from Docker! This message shows that your installation appears to be working correctly. ...

Install Docker Compose

1. Open a terminal and run the following command to download the Docker Compose binary to /usr/local/bin/docker-compose.

   curl -SL https://github.com/docker/compose/releases/download/v2.17.3/docker-compose-linux-x86_64 -o /usr/local/bin/docker-compose

2. Add execute permission to the docker-compose file.

   sudo chmod u+x /usr/local/bin/docker-compose

3. Create a symbolic link so docker-compose can be run from any directory.

   sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose

4. Verify that Docker Compose is installed:

   docker-compose
   tip

   If the following output appears, Docker Compose is installed successfully:

   Usage:  docker compose [OPTIONS] COMMAND ...

Step 2: Install OpenLDAP

If OpenLDAP is already installed, skip this section.

Click to expand process description

1. Open a terminal, create and edit docker-compose.yml in any directory, and paste this configuration into it. The comments explain each parameter.

   version: '3'
   
   services:
    openldap:
     image: osixia/openldap # Use the osixia/openldap image to start the OpenLDAP service.
     container_name: openldap # The container name of OpenLDAP, which can be customized.
     environment: # Configure environment variables.
       - LDAP_ORGANISATION=Ninedata # The organization name of OpenLDAP. Change NineData to your organization name.
       - LDAP_DOMAIN=ninedata.com # The domain name of OpenLDAP. Change it to your own OpenLDAP domain name.
       - LDAP_ADMIN_PASSWORD=your_password # The administrator password of the OpenLDAP service.
     ports: # Configure the service port of OpenLDAP.
       - "389:389" # The LDAP service port based on plain text transmission, the default is 389.
       - "636:636" # The LDAP service port based on SSL/TLS encrypted transmission, the default is 636.
     volumes: # Map the /var/lib/ldap and /etc/ldap/slapd.d directories to the local ./data/ldap and ./data/slapd.d directories so that data can be saved persistently.
       - ./data/ldap:/var/lib/ldap
       - ./data/slapd.d:/etc/ldap/slapd.d

2. Go to the directory that contains docker-compose.yml, then run the following command to pull the image and start OpenLDAP:

   docker-compose up -d

   After the command finishes, run docker-compose ps to check the OpenLDAP service status. If the STATUS column shows Up, the service started successfully.

Step 3: Install phpLDAPadmin

phpLDAPadmin provides a web interface for browsing the LDAP directory tree, searching and editing entries, and managing users, groups, and other LDAP objects.

1. Open a terminal and run the following command to pull the phpLDAPadmin Docker image:

   docker pull osixia/phpldapadmin

2. Create and start the phpLDAPadmin Docker container:

   docker run --name phpldapadmin-container -p 6443:443 --env PHPLDAPADMIN_LDAP_HOSTS=192.168.2.33 --detach osixia/phpldapadmin
   Parameter Description

   • --name phpldapadmin-container: Container name. Replace phpldapadmin-container with a custom name if needed.
   • -p 6443:443: Maps local port 6443 to container port 443. Replace 6443 with another local port if needed.
   • --env PHPLDAPADMIN_LDAP_HOSTS=192.168.2.33: LDAP host address. Replace 192.168.2.33 with your LDAP server address.
   • --detach: Runs the container in the background.
   • osixia/phpldapadmin: Docker image name.

3. Open the phpLDAPadmin URL, such as https://192.168.2.33:6443. Select login, enter Login DN and Password, and click Authenticate to sign in to OpenLDAP.

   • IP address: Use the actual PHPLDAPADMIN_LDAP_HOSTS value from the previous step.

   • Port: Use the actual -p value from the previous step.

   • Login DN: Use the LDAP login DN, such as cn=admin,dc=ninedata,dc=com. The cn=admin, dc=ninedata, and dc=com values are defined in docker-compose.yml in Step 2.

   • Password: Use the OpenLDAP administrator password from Step 2.

     tip

     • The browser may block the first visit because this example uses a self-signed certificate. In Chrome, click Advanced, then click Continue to 192.168.2.33 (unsafe). Browser prompts vary.
     • If the browser cannot open the page or shows ERR_INVALID_HTTP_RESPONSE, make sure the URL uses HTTPS instead of HTTP.

4. Because this example starts with a fresh OpenLDAP installation, there is no data yet. The next steps add an organization and a user through phpLDAPadmin.

   Create Organizational Unit (ou)

   1. Select the domain name from the phpLDAPadmin sidebar, then click Create a child entry.

      

   2. On the template page, click Default.

      

   3. In ObjectClasses, select organizationalUnit, then click Proceed >>.

      

   4. In the attribute configuration window, set RDN to ou (ou), enter the organizational unit name in ou, then scroll down and click Create Object.

      

      tip

      Add other organizational unit attributes if needed.

   5. On the confirmation page, click Commit.

      

   Create User in Organization (cn)

   1. Select the organizational unit under the domain name from the phpLDAPadmin sidebar, then click Create a child entry.

      

   2. On the template page, click Default.

      

   3. In ObjectClasses, select inetOrgPerson, then click Proceed >>.

      

   4. In the attribute configuration window, set RDN to cn (cn). Enter the user's common name in cn, surname in sn, and password in Password, then scroll down and click Create Object.

      

      

      tip

      Add other user attributes if needed.

   5. On the confirmation page, click Commit to complete the user creation.

      

   6. Add the User Name attribute as the unique login identifier. Select the new user in phpLDAPadmin and click Add new attribute.

      

   7. In the attribute configuration window, set RDN to User Name, enter the user's unique identifier under the added User Name attribute, then scroll down and click Update Object.

      

   8. On the confirmation page, click Update Object to add the user attribute.

      

Step 4: Install Keycloak and Synchronize User Data from OpenLDAP

Keycloak is an open-source identity and access management solution that provides authentication, authorization, and single sign-on (SSO). This section shows how to synchronize OpenLDAP users into Keycloak for SSO access.

1. Open a terminal and run the following command to pull the Keycloak image.

   docker pull jboss/keycloak:9.0.0

2. Create and start the Keycloak container.

   docker run --name keycloak-container -p 8443:8443 --env KEYCLOAK_USER=admin --env KEYCLOAK_PASSWORD=admin --detach jboss/keycloak:9.0.0
   Parameter Description

   • --name keycloak-container: Container name. Replace keycloak-container with a custom name if needed.
   • -p 8443:8443: Maps local port 8443 to container port 8443. Replace the local port if needed.
   • --env KEYCLOAK_USER=admin: Keycloak administrator account. Replace admin with a custom account if needed.
   • --env KEYCLOAK_PASSWORD=admin: Keycloak administrator password. Replace admin with a custom password if needed.
   • --detach: Runs the container in the background.
   • jboss/keycloak:9.0.0: Docker image name.

3. Open the Keycloak URL in your browser. In this example, use https://192.168.2.33:8443. Click Administration Console to open the login page.

   • IP address: Use the host address where Keycloak is installed.

   • Port: Use the -p value from the previous step.

     

   tip

   • The browser may block the first visit because this example uses a self-signed certificate. In Chrome, click Advanced, then click Continue to 192.168.2.33 (unsafe). Browser prompts vary.
   • If the browser cannot open the page or shows ERR_INVALID_HTTP_RESPONSE, make sure the URL uses HTTPS instead of HTTP.

4. On the login page, enter the login account and password, and click Log In.

   • Login account: Use the KEYCLOAK_USER value from the previous step. In this example, the account is admin.
   • Password: Use the KEYCLOAK_PASSWORD value from the previous step. In this example, the password is admin.

5. (Optional) Enable the Chinese interface.

   1. Open Realm Settings, then open the Themes tab. Update the theme settings and sign out to apply the change.

      

   2. Switch the language once, then sign back in to Keycloak.

      

6. Open User Federation, then select ldap as the user database.

   

7. On the Add User Federation Provider page, configure the provider settings shown in the numbered screenshot.

   

   

   Number	Description
   1	Select ldap as the provider.
   2	Enter the connection address of the OpenLDAP service, format: ldap://<OpenLDAP server IP>:<port>. After entering, you can click Test Connection to test the connectivity.
   3	Composed of the organization name and domain name, format: ou=<Organization Name>,dc=<Service Domain Name>,dc=<Service Domain Name>. Example: ou=ninedata,dc=ninedata,dc=com.
   4	Composed of the administrator username and domain name, format: cn=<Administrator Username>,dc=<Service Domain Name>,dc=<Service Domain Name>. Example: cn=admin,dc=ninedata,dc=com.
   5	Enter the administrator password for accessing OpenLDAP.
   6	Enable Periodic Full Sync to periodically synchronize the added, deleted, and modified member information in OpenLDAP automatically.
   7	Save changes.

8. After you click Save, the page shows Success! The provider has been created. Click Sync All Users to synchronize OpenLDAP users into Keycloak.

   

9. Open Realm Settings, right-click SAML Metadata, and save it as a .xml file for later use.

   

Step 5: Configure NineData SSO Login

Prerequisites

Your role must be "Administrator". For more information about roles, see Roles.

Operation Steps

1. Log in to the NineData Console.

   Open Account > **Organization**, and configure the numbered SSO settings in the screenshot.

   

   Number	Description
   3	Turn on the SSO login switch.
   4	Enter the SSO organization name. After you enter the name, SAML Service Provider Metadata automatically generates Identifier (Entity ID) and Reply URL (Assertion URL).
   5	Download the metadata file for later use.
   6	Click Upload File to Auto-recognition, select the SAML metadata downloaded from Keycloak, and let NineData parse and populate the metadata fields.
   7	Turn on this option so NineData automatically adds users when they sign in through SSO. You do not need to create SSO users in NineData in advance.
   8	Optional when Allow SSO Account Auto-join is turned on. Specify the default role for automatically joined SSO users. You can select one or more roles.
   9	Save changes.

2. Sign in to Keycloak with the administrator account. In this example, the account and password are admin/admin. Open Clients, then click Create in the upper-right corner.

   

3. On the Add Client page, click Select File and import the .xml metadata file downloaded from the NineData console (Step 1, Number 5). Click Save to open the client configuration page, turn off Require Client Signature, scroll down, and click Save.

4. Open Account > Organization, copy Org Login URL, and share it with the user. The user can then sign in to NineData with their own Keycloak account.

   

Step 6: Users Sign in to NineData via SSO

Prerequisites

Users must have Org Login URL from the administrator.

Operation Steps

1. Open Org Login URL in a browser. The page redirects to the Keycloak login page.

2. Enter the username and password, then click Log In to open the NineData console.

   

   tip

   The username and password must match the OpenLDAP user created by the administrator. See Add Organization and Users.

3. New users must complete the profile prompts before they can continue.

   

Result

Users who open the SSO organization URL are redirected to Keycloak, authenticate with their OpenLDAP username and password, and enter NineData. New users complete the profile prompts during their first sign-in.