# Soffid LDAP

# Introduction to Soffid LDAP

## What is Soffid LDAP?

Soffid LDAP is a complete LDAP Server based on OpenLDAP. It is always distributed as a docker container. The proposed system architecture is as follows:

[![image-1654607834304.png](https://bookstack.soffid.com/uploads/images/gallery/2022-06/scaled-1680-/image-1654607834304.png)](https://bookstack.soffid.com/uploads/images/gallery/2022-06/image-1654607834304.png)

The SoffidLDAP is not directly using Soffid database. Instead, it is using its own database, that can contain a subset or superset of the information stored in Soffid database.

The integrations work as follows:

- Soffid syncserver pushes to Soffid LDAP any change in Soffid database. It does this task by means of the standard LDAP connector. Thus, you can perform any kind of transformation or filtering during this process.
- Soffid syncserver can also fetch any change performed in SoffidLDAP by means of the standard LDAP connector
- Soffid LDAP delegates any password management task to Soffid sync server. This includes validation against trusted third-party authenticators and checking new password policies.
- Third-party applications can access Soffid LDAP by using LDAP (or LDAPS) protocol.

# How to install Soffid LDAP?

## Installation

### Prerequisites

To install **Soffid LDAP**, you must install [Docker](https://hub.docker.com/search?q=&type=edition&offering=community). Despite Docker desktop can be used for testing purposes, Docker container runtime usage is recommended.

### Installation

To start Soffid LDAP, execute:

```shell
docker volume create ldapconf
docker volume create ldapdata
docker run --name soffidldap -p 1389:389 -v ldapconf:/etc/ldap/slapd.d -v ldapdata:/var/lib/ldap -d -e SOFFID_SERVER=https://<SYNCSERVERNAME>:760 -e SOFFID_AGENT=<SOFFID_AGENT> -e USER=<ADMIN_USERNAME> -e PASSWORD=<ADMIN_PASSWORD> -e DN=<YOUR_BASE_DN> soffidldap:latest
```

<details id="bkmrk-%F0%9F%92%BB-image"><summary>💻 Image</summary>

[![image-1654601131618.png](https://bookstack.soffid.com/uploads/images/gallery/2022-06/scaled-1680-/image-1654601131618.png)](https://bookstack.soffid.com/uploads/images/gallery/2022-06/image-1654601131618.png)

</details>Now, you can connect to the LDAP Server using the user name and password used to create the docker instance.

#### Docker commands

##### Stop the service

```
docker stop soffidldap
```

##### Start the service

```
docker start soffidldap
```

##### Remove the service

```
docker rm soffidldap
```

#### Docker Volumes

- The initial configuration files are located in the **ldapconf volume**, usually in /var/lib/docker/volumes/ldapconf/\_data
- The initial data files are located in the **ldapdata volume**, usually in /var/lib/docker/volumes/ldapdata/\_data

# How to debug Soffid LDAP?

## Installation

### Prerequisites

To install **Soffid LDAP**, you must install [Docker](https://hub.docker.com/search?q=&type=edition&offering=community). Despite Docker desktop can be used for testing purposes, Docker container runtime usage is recommended.

### Steps to debug

1.- First of all, you have to add the **DEBUG environment variable** to your container

```
-e DEBUG: 65535
```

2.- You need to restart the Soffid LDAP container

```
sudo docker restart <YOUR_CONTAINER>
```

3.- In this point, you can check your LDAP

4.- Retrieve the log

5.- Delete the DEBUG environment variable

6.- Restart the Soffid LDAP container

### Log level

Multiple log levels may be used and the levels are additive. To display what numbers correspond to what kind of debugging, consult the table below. The possible values for &lt;integer&gt; are:

<table align="Center" border="" class="columns" id="bkmrk-level-description--1"><tbody><tr class="heading"><td align="Right">**Level**</td><td>**Description**</td></tr><tr><td align="Right">-1</td><td>enable all debugging</td></tr><tr><td align="Right">0</td><td>no debugging</td></tr><tr><td align="Right">1</td><td>trace function calls</td></tr><tr><td align="Right">2</td><td>debug packet handling</td></tr><tr><td align="Right">4</td><td>heavy trace debugging</td></tr><tr><td align="Right">8</td><td>connection management</td></tr><tr><td align="Right">16</td><td>print out packets sent and received</td></tr><tr><td align="Right">32</td><td>search filter processing</td></tr><tr><td align="Right">64</td><td>configuration processing</td></tr><tr><td align="Right">128</td><td>access control list processing</td></tr><tr><td align="Right">256</td><td>stats log connections/operations/results</td></tr><tr><td align="Right">512</td><td>stats log entries sent</td></tr><tr><td align="Right">1024</td><td>print communication with shell backends</td></tr><tr><td align="Right">2048</td><td>print entry parsing debugging</td></tr><tr><td align="Right">16384</td><td>syncrepl consumer processing</td></tr><tr><td align="Right">32768</td><td>only messages that get logged whatever log level is set</td></tr></tbody></table>

The desired log level can be input as a single integer that combines the (ORed) desired levels.

# Connecting to the LDAP using user short names

## Connecting to the LDAP 

The Soffid LDAP accepts the usual way to connect to the LDAP service using the distinguished name and password for the user.

Additionally, one can use the uid attribute to login. Then for the user:

<table border="1" id="bkmrk-dn%3A-cn%3Duser%2Cou%3Dtest%2C" style="border-collapse: collapse; width: 100%;"><tbody><tr><td style="width: 99.8765%; border-color: #6983a7;">dn: cn=user,ou=test,dc=soffid,dc=com

cn: user

givenName: John

sn: Snow

uid: jsnow

userPassword: secret

</td></tr></tbody></table>

The user can use one of these two ways to login to the LDAP server:

1. USER: cn=user,ou=test,dc=soffid,dc=com PASSWORD: secret
2. USER: uid=jsnow,dc=soffid,dc=com PASSWORD: secret

# Seamless authentication

The password authentication process is redesigned to allow users to connect to Soffid LDAP using their internally stored password, or a password trusted by Soffid.

<div class="wiki-content" id="bkmrk-the-first-attempt-is"><div class="wiki-content">1. The first attempt is to check the password against the **local userPassword attribute**. If it fails, Soffid LDAP will connect any of the configured sync servers, and will let the sync server validate the password.
2. Then, the sync server will check the password against **Soffid internal tables**.
3. If the password is not accepted according to Soffid internal tables, the authentication request will be forwarded to any **trusted target systems**. The trusted flag is enabled or disabled on a per-agent basis, at the agents configuration page
4. If everything fails, the login is rejected

</div></div>Anyway, whenever a password change is detected by Soffid, the attribute userPassword can be updated. This is done by means of the LDAP connector.

The opposite way also works for password changes. Whenever the user attribute userPassword is updated, SoffidLDAP does:

<div class="wiki-content" id="bkmrk-generates-a-secure-h">1. Generates a secure hash using SSHA-256, and replaces the provided value for the corresponding hash
2. Notifies Soffid sync server the password has been changed
3. Adds an additional value {SOFFID} to the userPassword attribute. Now, the userPassword attribute has two values: the SSHA hash and the Soffid marker
4. Soffid sync server, in turn, validates the received passwords and stores it in Soffid database and other target systems. This only happens if the trusted flag is enabled for the Soffid LDAP agent

</div>

# Soffid overlay configuration

The communication channel from Soffid LDAP to Soffid sync server is configured by the Soffid overlay. The overlay configuration object looks like this:

<table border="1" id="bkmrk-%23%23-soffid-overlaydn%3A" style="border-collapse: collapse; width: 100%;"><tbody><tr><td style="width: 99.8765%; border-color: #6983a7;">\#  
\# Soffid overlay  
dn: olcOverlay=soffid,olcDatabase={1}mdb,cn=config  
olcOverlay: soffid  
objectClass: olcOverlayConfig  
objectClass: olcSoffidConfig  
olcDomain: soffidldap  
olcSoffidServer: https://soffid.bubu.lab:760</td></tr></tbody></table>

  
The two configuration parameters are olcDomain and olcSoffidServer.

olcSoffidServer is a multivalued attribute that hosts the list of Soffid sync servers that will receive password change notifications. They will be used for authentication purposes as well.

olcDomain is the agent name used in Soffid console to manage the current Soffid LDAP Database