LDAP Auth in Buildly Core
Tags: openldap, ldap, buildly, activedirectory
Published: 2020-02-05 09:26:10

Several enterprise companies ask engineers to integrate their application authentication with LDAP (Lightweight Directory Access Protocol) or Active Directory (AD), Microsoft’s proprietary solution for storing user or employee information. The focus of this article is to explain how to integrate Buildly with an LDAP server.

# LDAP
LDAP, the Lightweight Directory Access Protocol, is a mature, flexible, and well supported standards-based mechanism for interacting with directory servers. It’s often used for authentication and storing information about users, groups, and applications, but an LDAP directory server is a fairly general-purpose data store and can be used in a wide variety of applications.[[1]](https://ldap.com/)

LDAP can define permissions, set by the admin to permit just certain individuals to access the LDAP database, and schema, to describe the format and properties of data in the server.

# Active Directory
Active Directory is used to store user information. It helps to work with interconnected, complex and different network resources.

A directory service, such as Active Directory Domain Services (AD DS), provides the methods for storing directory data and making this data available to network users and administrators. For example, AD DS stores information about user accounts, such as names, passwords, phone numbers, and so on, and enables other authorized users on the same network to access this information.[[2]](https://docs.microsoft.com/en-us/windows-server/identity/ad-ds/get-started/virtual-dc/active-directory-domain-services-overview)

# Configure Buildly LDAP connection
Before start
In our example, we’re using OpenLDAP as the LDAP server, so we also need an instance of it up and running. There are a couple of tutorials on the internet of how to start a LDAP server, so we’re not going to explain how to do it here but share some links that should help you. You can also use Azure Active Directory.

### OpenLDAP
- [How To Install OpenLDAP Server for Centralized Authentication](https://www.tecmint.com/install-openldap-server-for-centralized-authentication/)
- [How to Install OpenLDAP on Ubuntu Server 18.04](https://www.linux.com/tutorials/how-install-openldap-ubuntu-server-1804/)

### Active Directory
- [Install a new Active Directory forest using Azure CLI](https://docs.microsoft.com/en-us/windows-server/identity/ad-ds/deploy/virtual-dc/adds-on-azure-vm)
- [Create and configure an Azure Active Directory Domain Services instance](https://docs.microsoft.com/en-us/azure/active-directory-domain-services/tutorial-create-instance)

## Configure Buildly
First of all, we need to have a Buildly Core instance up and running locally, so we can safely expose our services and use an LDAP server to retrieve users’ data for authentication. To know how to quickly have a local instance of Buildly Core, go through the Quickstart documentation.

Now, we need to configure Buildly Core to connect to our LDAP server, so we have to have the URI, username, password and base domain name for the user search in hands. Buildly Core uses specific environment variables to configure its LDAP connection. These are the environment variables with our LDAP server values:
![ldap config](https://buildly.io/wp-content/uploads/2020/02/Firefox_Screenshot_2020-02-04T14-41-09.950Z.png)

We can specify each parameter using -e, –env, and/or –env-file flags to set simple (non-array) environment variables when running docker containers but if you are running Buildly Core with docker compose, you can update the *docker-compose.yml* file with the new environment variables.

Let’s run Buildly Core with the new configuration and test the authentication. But first of all, we are going to list all users from our current Buildly Core instance using superuser powers.
![get superuser](https://buildly.io/wp-content/uploads/2020/02/Firefox_Screenshot_2020-02-04T14-56-58.111Z.png)

As we can see in the response below, currently, there’s no other user besides the superuser.
![superuser data](https://buildly.io/wp-content/uploads/2020/02/Firefox_Screenshot_2020-02-04T14-58-52.795Z-613x1024.png)

We have already added a user called Rick Sanchez to our LDAP server with username rick and password admin. We will send the following request to Buildly Core to authenticate with it:
![auth rick](https://buildly.io/wp-content/uploads/2020/02/Firefox_Screenshot_2020-02-04T14-43-15.042Z.png)

Buildly Core responded with an access token for our user:
![rick oauth token](https://buildly.io/wp-content/uploads/2020/02/Firefox_Screenshot_2020-02-04T14-44-49.707Z.png)

Since this user didn’t exist in the Buildly database before, it should be created now. Let’s check that.

Example of request:
![get rick](https://buildly.io/wp-content/uploads/2020/02/Firefox_Screenshot_2020-02-04T14-45-49.847Z.png)

Buildly returns all information about my user:
![rick data](https://buildly.io/wp-content/uploads/2020/02/Firefox_Screenshot_2020-02-04T14-47-01.455Z.png)

Now, I will change the first and last name of the user in our LDAP server, then authenticate with it again and check if its name was updated in the Buildly Core database.

This is the data of the user in the LDAP server.
![server data](https://lh3.googleusercontent.com/jOz0qI8_XW08S3kGGNcwhGSAVHlgGiD7R0dL93r80IbZhodSWeXl_XqaicXDoJW0Yd2f18jJnKJjvslE7gLc-em2MVCC9yICv6kzuU_rqoTjSH-Q-WkLZbbZE3hOQ-qh2ll9SGcr)

Let’s authenticate to Buildly Core again:
![auth again](https://buildly.io/wp-content/uploads/2020/02/Firefox_Screenshot_2020-02-04T14-48-21.184Z.png)

Now, let’s retrieve the user data:
![get rick data again](https://buildly.io/wp-content/uploads/2020/02/Firefox_Screenshot_2020-02-04T14-49-35.095Z.png)
![update rick data](https://buildly.io/wp-content/uploads/2020/02/Firefox_Screenshot_2020-02-04T14-50-11.050Z.png)

Everything worked and the user data was updated in the Buildly Core database based on the information we have in our LDAP server. Buildly authenticates users against LDAP server, creates and updates users based on the data retrieved from the server.

# Conclusion
We connected Buildly Core to an OpenLDAP server in this tutorial but you can connect to Active Directory as well. To connect to an Active Directory Domain Service (AD DS) you would need to update the user search filter in the config, to the AD field that you would define as the username in your AD user data.

Example:
`LDAP_USERNAME_FIELD_SEARCH: “sAMAccountName”`

# Reference
1. LDAP – https://ldap.com/
2. Active Directory Domain Service – https://docs.microsoft.com/en-us/windows-server/identity/ad-ds/get-started/virtual-dc/active-directory-domain-services-overview