How to enable GitLab user authentication with ApacheDS LDAP
Test Environment
Fedora 32 installed
Docker and Docker compose installed
Every organization has some kind of LDAP server to manage their enterprise resources like user and servers. The LDAP servers are primary used to authenticate and authorizate any entity to carry out a particular action on the resources. Gitlab integrates with a number of external authentication and authorization providers. Here in this article we will see how we can enable gitlab user to authentication with the LDAP server.
If you are interested in watching the video. Here is the youtube video on the same step by step procedure below.
Procedure
Step1: Install Apache Directory Server
Here we are going to install the ApacheDS Directory server which is a LDAP and Kerberos server written in Java. You can download the RPM package from the following location.
Download URL – https://directory.apache.org/apacheds/downloads.html
Once you install the rpm package the following directory structure will be layed down on your machine.
[admin@fedser32 software]$ ls -ltr apacheds-2.0.0.AM26-x86_64.rpm
-rw-rw-r--. 1 admin admin 14480620 Sep 8 18:30 apacheds-2.0.0.AM26-x86_64.rpm
[admin@fedser32 software]$ sudo dnf install apacheds-2.0.0.AM26-x86_64.rpm
Installed:
apacheds-2.0.0.AM26-1.x86_64
[admin@fedser32 apacheds-2.0.0.AM26]$ pwd
/opt/apacheds-2.0.0.AM26
[admin@fedser32 apacheds-2.0.0.AM26]$ tree .
.
├── bin
│ ├── apacheds
│ └── wrapper
├── conf
│ └── wrapper.conf
├── lib
│ ├── apacheds-service-2.0.0.AM26.jar
│ ├── apacheds-wrapper-2.0.0.AM26.jar
│ ├── libwrapper.so
│ └── wrapper-3.2.3.jar
├── LICENSE
└── NOTICEStep2: Start the Apache Directory Server and validate the service
[admin@fedser32 ~]$ sudo systemctl start apacheds.service
[admin@fedser32 ~]$ ps -ef | grep apacheds
apacheds 13807 1 0 12:39 ? 00:00:00 /usr/lib/systemd/systemd --user
apacheds 13811 13807 0 12:39 ? 00:00:00 (sd-pam)
apacheds 13865 1 0 12:39 ? 00:00:00 /opt/apacheds-2.0.0.AM26/bin/wrapper /var/lib/apacheds-2.0.0.AM26/default/conf/wrapper-instance.conf set.INSTANCE_DIRECTORY=/var/lib/apacheds-2.0.0.AM26/default set.APACHEDS_COMMAND=start set.INSTANCE=default wrapper.syslog.ident=apacheds wrapper.pidfile=/var/lib/apacheds-2.0.0.AM26/default/run/apacheds-default.pid wrapper.daemonize=TRUE
apacheds 13867 13865 17 12:39 ? 00:00:12 java -Dlog4j.configuration=file:////var/lib/apacheds-2.0.0.AM26/default/conf/log4j.properties -Dapacheds.var.dir=/var/lib/apacheds-2.0.0.AM26/default -Dapacheds.log.dir=/var/lib/apacheds-2.0.0.AM26/default/log -Dapacheds.run.dir=/var/lib/apacheds-2.0.0.AM26/default/run -Dapacheds.instance=default -Djava.library.path=../lib -classpath ../lib/wrapper-3.2.3.jar:../lib/apacheds-service-2.0.0.AM26.jar:../lib/apacheds-wrapper-2.0.0.AM26.jar -Dwrapper.key=MuAT4EsH9LORN6G3 -Dwrapper.port=32000 -Dwrapper.jvm.port.min=31000 -Dwrapper.jvm.port.max=31999 -Dwrapper.pid=13865 -Dwrapper.version=3.2.3 -Dwrapper.native_library=wrapper -Dwrapper.service=TRUE -Dwrapper.cpu.timeout=10 -Dwrapper.jvmid=1 org.apache.directory.server.wrapper.ApacheDsTanukiWrapper /var/lib/apacheds-2.0.0.AM26/default start
admin 14068 3532 0 12:41 pts/0 00:00:00 grep --color=auto apachedsThe easiest way that we can make sure whether the LDAP service is up and running is using the curl command as shown below. Please note, the apacheds ldap service listens on port 10389.
[admin@fedser32 ~]$ curl -k ldap://localhost:10389
DN:
objectClass: top
objectClass: extensibleObjectBut in order to maange the apacheds ldap server, we can use the Apache Directory Studio. So in our next step we will install the Apache Directory Studio and connect to our local Apache Directory Server from the UI to validate.
Step3: Install Apache Directory Studio and Connect to Apache Directory Server
Download the Apache Directory Studio tar.gz package as shown below.
Download URL – https://directory.apache.org/studio/downloads.html
[admin@fedser32 software]$ ls -ltr ApacheDirectoryStudio-2.0.0.v20210717-M17-linux.gtk.x86_64.tar.gz
-rw-rw-r--. 1 admin admin 140122735 Jul 18 00:23 ApacheDirectoryStudio-2.0.0.v20210717-M17-linux.gtk.x86_64.tar.gzExtract the .tar.gz file to any of your preferred location.
[admin@fedser32 ApacheDirectoryStudio]$ pwd
/home/admin/middleware/stack/ApacheDirectoryStudio
[admin@fedser32 ApacheDirectoryStudio]$ ls -ltr
total 356
-rwxr-xr-x. 1 admin admin 29478 Jul 17 23:36 icon.xpm
-rwxr-xr-x. 1 admin admin 61928 Jul 17 23:36 ApacheDirectoryStudio
drwxr-xr-x. 4 admin admin 4096 Jul 17 23:37 p2
drwxr-xr-x. 8 admin admin 53248 Jul 17 23:37 plugins
drwxr-xr-x. 23 admin admin 4096 Jul 17 23:37 features
-rw-r--r--. 1 admin admin 118573 Jul 17 23:37 artifacts.xml
-rw-r--r--. 1 admin admin 178 Jul 17 23:37 NOTICE
-rw-r--r--. 1 admin admin 69356 Jul 17 23:37 LICENSE
-rw-r--r--. 1 admin admin 683 Jul 17 23:37 ApacheDirectoryStudio.ini
drwxr-xr-x. 9 admin admin 4096 Sep 9 11:34 configurationStep4: Start the Apache Directory Studio to launch the UI interface
Start the Apache Directory Studio with the binary shown below. Please note the current version of Apache Directory Studio requires Java version 11 or greater.
[admin@fedser32 ApacheDirectoryStudio]$ ./ApacheDirectoryStudioIf you get an pop error as shown below. Then you need to make sure that you install Java 11 and configure it to be used as the default.
As shown below i have two java versions installed on my system and its configured to use the java 11 version.
[admin@fedser32 ApacheDirectoryStudio]$ sudo alternatives --config java
[sudo] password for admin:
There are 2 programs which provide 'java'.
Selection Command
-----------------------------------------------
* 1 java-1.8.0-openjdk.x86_64 (/usr/lib/jvm/java-1.8.0-openjdk-1.8.0.292.b10-0.fc32.x86_64/jre/bin/java)
+ 2 java-11-openjdk.x86_64 (/usr/lib/jvm/java-11-openjdk-11.0.11.0.9-0.fc32.x86_64/bin/java)
Enter to keep the current selection[+], or type selection number: Once you have configured the Java runtime to use you version 11 you can launch the Apache Directory Studion again and it should start the UI.
In order to connect to the Apache Directory server, we need to setup the new LDAP connection by providing the details as shown in below screenshots.
Once the LDAP authentication succeds, you should be able to see the LDAP directory strcture and resource details as shown in below screenshot.
The important thing to note from the following LDAP server setup are below which we will be using further to configure the Gitlab for LDAP integration.
LDAP connection - ldap://localhost:10389/
Bind DN or user - uid=admin, ou=system
Bind password - secretStep5: Setup Gitlab EE using docker compose
We will be using GitLab Docker image which is based on the omnibus package for the Gitlab EE setup. Container spawned from this image contains multiple processes, these types of containers are also referred to as ‘fat containers’. GitLab in its core is a Ruby on Rails project. Omnibus GitLab follows a batteries-included style of distribution and its a customized fork of the Omnibus project from Chef.
Here is my docker-compose.yml file setting up the Gitlab EE server. Please note to create the volume mounts directory on the host machine to persist the Application data, Configuration data and logs data from the container.
[admin@fedser32 gitlab-latest-docker]$ ls -ld /apps/gitlab/config/ /apps/gitlab/logs/ /apps/gitlab/data/
drwxrwxr-x. 3 root root 4096 Sep 15 23:43 /apps/gitlab/config/
drwxr-xr-x. 20 root root 4096 Sep 15 23:46 /apps/gitlab/data/
drwxr-xr-x. 20 root root 4096 Sep 15 23:45 /apps/gitlab/logs/[admin@fedser32 gitlab-latest-docker]$ cat docker-compose.yml
version: "3"
services:
gitlab:
image: "gitlab/gitlab-ee:latest"
hostname: "192.168.29.117"
ports:
- "443:443"
- "80:80"
- "22:22"
volumes:
- "/apps/gitlab/config:/etc/gitlab"
- "/apps/gitlab/logs:/var/log/gitlab"
- "/apps/gitlab/data:/var/opt/gitlab"Start the gitlab service using the docker-compose file. Make sure you have the docker service up and running along with docker-compose installed.
[admin@fedser32 gitlab-latest-docker]$ docker-compose up -d
Starting gitlab-latest-docker_gitlab_1 ... doneThe initial ‘root’ administrator password can be captured from the below location in the config path.
[admin@fedser32 gitlab-latest-docker]$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
8df9794caac2 gitlab/gitlab-ee:latest "/assets/wrapper" 14 hours ago Up About a minute (health: starting) 0.0.0.0:22->22/tcp, :::22->22/tcp, 0.0.0.0:80->80/tcp, :::80->80/tcp, 0.0.0.0:443->443/tcp, :::443->443/tcp gitlab-latest-docker_gitlab_1
[admin@fedser32 gitlab-latest-docker]$ sudo docker exec -it gitlab-latest-docker_gitlab_1 grep 'Password:' /etc/gitlab/initial_root_password
Password: N9cwkaivnvnMaWaiwKSKZW3wnr7E7MiZpy5QKtzeUaI=After capturing the initial ‘root’ administrator password, we can login to the gitlab portal using that credentails.
URL - http://localhost/users/sign_in
username - root
password - N9cwkaivnvnMaWaiwKSKZW3wnr7E7MiZpy5QKtzeUaI= (captured from the config file)You can change the password for this ‘root’ administrator once logged into the gitlab portal by editing the user settings with the new password.
Now, lets stop our gitlab service so that we can continue further to configure it for the LDAP integration.
[admin@fedser32 gitlab-latest-docker]$ docker-compose stop
Stopping gitlab-latest-docker_gitlab_1 ... doneStep6: Configure Gitlab for LDAP integration
As mentioned previously, the Gitlab docker image is based on the Omnibus package. For LDAP integration we need to update the ‘/etc/gitlab/gitlab.rb’ within the container with the LDAP configuration details. Please note, LDAP users must have a set email address, regardless of whether or not it’s used to sign in.
As we have volume mounted the LDAP configuration data while starting up the gitlab using docker-compose file. The ‘/etc/gitlab/gitlab.rb’ will be availabe on your localhost at the following locaiton which can be edited locally and restart the docker container to make the changes effective.
[root@fedser32 config]# ls -ltr /apps/gitlab/config/gitlab.rb
-rw-------. 1 root root 122798 Sep 15 23:42 /apps/gitlab/config/gitlab.rbWe will be updating this file commenting out the LDAP configuration section and updating them with the required details as shown below in the sample configuration. Make sure to take the backup of the original configuraiton file before any changes.
Backup
[root@fedser32 config]# cp /apps/gitlab/config/gitlab.rb /apps/gitlab/config/gitlab.rb_backup_09162021LDAP Configuration
...
### LDAP Settings
###! Docs: https://docs.gitlab.com/omnibus/settings/ldap.html
###! **Be careful not to break the indentation in the ldap_servers block. It is
###! in yaml format and the spaces must be retained. Using tabs will not work.**
gitlab_rails['ldap_enabled'] = true
gitlab_rails['prevent_ldap_sign_in'] = false
###! **remember to close this block with 'EOS' below**
gitlab_rails['ldap_servers'] = YAML.load <<-'EOS'
main: # 'main' is the GitLab 'provider ID' of this LDAP server
label: 'LDAP'
host: '192.168.29.117'
port: 10389
uid: 'uid'
bind_dn: 'uid=admin, ou=system'
password: 'secret'
encryption: 'plain' # "start_tls" or "simple_tls" or "plain"
verify_certificates: true
# smartcard_auth: false
# active_directory: true
allow_username_or_email_login: false
lowercase_usernames: false
block_auto_created_users: false
base: 'ou=system'
# user_filter: ''
# ## EE only
# group_base: ''
# admin_group: ''
# sync_ssh_keys: false
...
EOSNow, we can start up the gitlab service using the docker-compose.yml file.
[admin@fedser32 gitlab-latest-docker]$ docker-compose up -d
Starting gitlab-latest-docker_gitlab_1 ... doneStep7: Validate Gitlab login with LDAP authentication
We are now ready test whether our LDAP integration is successfull or not by logging into the gitlab portal using the ldap ‘admin’ user credentials which are used to LDAP binding.
URL - http://localhost/users/sign_in
username - admin
password - secretThe login screen now has two option to login, one is using the LDAP credentials with label ApacheDS and other is with the default gitlab ‘root’ user using the Standard authentication method.
You can try to login with the below LDAP administrator credentails to check whether you are able to login successfully or not.
To validate the successful authenticaion from the logs you can check the gitlab service logs.
Sample Successful log
[admin@fedser32 gitlab-latest-docker]$ docker-compose logs -f gitlab
...
gitlab_1 | ==> /var/log/gitlab/gitlab-rails/production.log <==
gitlab_1 | Processing by Ldap::OmniauthCallbacksController#ldapmain as HTML
gitlab_1 | Parameters: {"authenticity_token"=>"[FILTERED]", "username"=>"admin", "password"=>"[FILTERED]"}
gitlab_1 |
gitlab_1 | ==> /var/log/gitlab/gitlab-rails/application.log <==
gitlab_1 | 2021-09-16T10:49:15.852Z: Instantiating Gitlab::Auth::Ldap::Person with LDIF:
gitlab_1 | dn: uid=admin,ou=system
gitlab_1 | cn: system administrator
gitlab_1 | sn: administrator
gitlab_1 | uid: admin
gitlab_1 |
gitlab_1 |
gitlab_1 | ==> /var/log/gitlab/gitlab-rails/application_json.log <==
gitlab_1 | {"severity":"DEBUG","time":"2021-09-16T10:49:15.853Z","correlation_id":"01FFQ3K4N0Z3RR9S4GCDDHX336","message":"Instantiating Gitlab::Auth::Ldap::Person with LDIF:\ndn: uid=admin,ou=system\ncn: system administrator\nsn: administrator\nuid: admin\n"}
gitlab_1 |
gitlab_1 | ==> /var/log/gitlab/gitaly/gitaly_ruby_json.log <==
gitlab_1 | {"type":"gitaly-ruby","grpc.start_time":"2021-09-16T10:49:15Z","grpc.time_ms":0.203,"grpc.code":"OK","grpc.method":"Check","grpc.service":"grpc.health.v1.Health","pid":432,"correlation_id":"335e5cdd8adc7cb9c34619820aca351b","time":"2021-09-16T10:49:15.895Z"}
gitlab_1 | {"type":"gitaly-ruby","grpc.start_time":"2021-09-16T10:49:15Z","grpc.time_ms":0.145,"grpc.code":"OK","grpc.method":"Check","grpc.service":"grpc.health.v1.Health","pid":433,"correlation_id":"9816dc7d1bb754287490aa9fb4e7dc05","time":"2021-09-16T10:49:15.896Z"}
gitlab_1 |
gitlab_1 | ==> /var/log/gitlab/gitlab-rails/audit_json.log <==
gitlab_1 | {"severity":"INFO","time":"2021-09-16T10:49:15.941Z","correlation_id":"01FFQ3K4N0Z3RR9S4GCDDHX336","author_id":2,"author_name":"system administrator","entity_id":2,"entity_type":"User","with":"ldapmain","target_id":2,"target_type":"User","target_details":"system administrator"}
gitlab_1 |
gitlab_1 | ==> /var/log/gitlab/gitlab-rails/production.log <==
gitlab_1 | Redirected to http://localhost/
gitlab_1 | Completed 302 Found in 264ms (ActiveRecord: 92.2ms | Elasticsearch: 0.0ms | Allocations: 55521)
...
NOTE: For this article we haven’t setup any separate LDAP OU groups and users. But you can try creating a sample LDAP organization structure and update the ‘base’ section of the configuration to point to the exact tree location where the users are located for authentication.
Hope you enjoyed reading this article. Thank you..
Leave a Reply
You must be logged in to post a comment.