> For the complete documentation index, see [llms.txt](https://docs.1kosmos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.1kosmos.com/authentication/authentication-broker/connect-to-ldap-via-broker.md).

# Connect to LDAP via Broker

***

### Getting started

1. From the main menu, select **Directory Integrations** on the left.
2. On the **Directory Integrations** page, click **Add new directory**.
3. Select **LDAP** from the menu.
4. Enter a name to use for this connection, and click **Setup Directory**.

#### Step 1: Download and install the Linux broker

Click the **Download Now** link to download the broker. The downloaded archive must be copied to and installed on a Linux server that is part of your Active Directory domain. 

#### Step 2: Connection information

Under **Connection Information**, enter the connection details:

* **Server protocol type** — select **LDAP** or **LDAPS**
* **Server URL** — your LDAP server URL
* **Server Port** — your LDAP server port
* **Base Domain** — your LDAP base domain

Under **Service Account Information**, enter the details for your LDAP service account:

* **Service account username** — the LDAP service account
* **Service account read-only** — enable this if you only wish to read from this directory (cannot create new users)
* **Authentication method** — select **SIMPLE**
* **Filter** — enter a directory term to filter for, such as `user`
* **LDAP Query Filter** (optional) — enter an LDAP query to filter results (see below)

Click **Connect** to save your settings and enable the directory.

**LDAP query filter**

LDAP query filters use a regular expression to keep only the desired directory parameters and discard the rest. Administrators can use them to control which users can authenticate to 1Kosmos — for example, allowing only active accounts. The field is optional and can be left blank.

**Example:**

```
(&(objectClass=User)(!(userAccountControl:1.2.840.113556.1.4.803:=2))(!(lockoutTime>=1)))
```

#### Step 3: Map attributes

Click **Add new mapping**, then add each directory attribute and its corresponding 1Kosmos attribute:

| Directory attribute | 1Kosmos attribute |
| ------------------- | ----------------- |
| uid                 | uid               |
| uid                 | username          |
| mobile              | phone             |
| mail                | email             |
| givenname           | firstname         |
| sn                  | lastname          |

For example, to add the `uid` attribute:

1. Click **Add attribute mapping**.
2. Enter `uid` in the **Directory attribute** box.
3. Select `uid` from the **1Kosmos attribute** drop-down.
4. Click **Create**.

Repeat for all attributes above. When finished, click **Next**, then click **Complete** to finish setting up your LDAP Broker user directory in AdminX.

***

### Install and run the broker

#### Install and run the broker on Windows

Copy the broker you downloaded in Step 1 to your Windows server and **unzip** it.

{% hint style="info" %}
The broker service must be kept running indefinitely for the connection between your directory and AdminX to remain valid.
{% endhint %}

Open a PowerShell terminal, change to the directory where you unzipped the broker, and start it:

```
.\setupBroker.ps1
```

If the script fails with a `PSSecurityException` error, run:

```
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass setupBroker.ps1
```

Follow the on-screen instructions to configure and start the broker service. Enter `E` to edit the existing configuration. An example session:

```
Edit current license key 'd2a36a85-e81b-4956-b7c0-****** ' (Y/N/Q)?: n
Edit current community id '5f3d8d0cd866fa61****' (Y/N/Q)?: n
Edit current authmodule id '621e17cfd24493001****' (Y/N/Q)?: n
Edit current dns string 'blockid.1kosmos.net' (Y/N/Q)?: n
Change bind password (Y/N/Q)?: y
Enter new bind password: ********
Re-enter new bind password: ********
Enter new proxy url (Y/N/Q)?: n
Enter new proxy user (Y/N/Q)?: n
Change proxy password (Y/N/Q)?: n
Change scep agent password (Y/N/Q)?: y
Enter new scep agent password: ********
Re-enter new scep agent password: ********
(S)ave or (D)iscard edits (S/D)?: S
```

**Broker logs.** After the service starts, a new `logs` folder is created in the same directory from which the broker was started.

{% hint style="info" %}
If you ever need to troubleshoot a broker connection, the logs folder provides the most information.
{% endhint %}

**Removing the broker service.** Stop the broker service first, then run the removal script from the unzipped directory:

```
.\removeService.ps1
```

If the script fails with a `PSSecurityException` error, run:

```
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass removeService.ps1
```

#### Install and run the broker on Linux

Copy the broker you downloaded in Step 1 to your Linux server and **unzip** it.

{% hint style="warning" %}
The broker service must be kept running indefinitely for the connection between your directory and AdminX to remain valid.
{% endhint %}

Open your command terminal, change to the directory where you unzipped the broker, and start it:

```
./startBroker.bsh
```

Follow the on-screen instructions to configure and start the broker service. Enter `E` to edit the existing configuration. An example session:

```
Edit current license key 'd2a36a85-e81b-4956-b7c0-****** ' (Y/N/Q)?: n
Edit current community id '5f3d8d0cd866fa61****' (Y/N/Q)?: n
Edit current authmodule id '621e17cfd24493001****' (Y/N/Q)?: n
Edit current dns string 'blockid.1kosmos.net' (Y/N/Q)?: n
Change bind password (Y/N/Q)?: y
Enter new bind password: ********
Re-enter new bind password: ********
Enter new proxy url (Y/N/Q)?: n
Enter new proxy user (Y/N/Q)?: n
Change proxy password (Y/N/Q)?: n
Change scep agent password (Y/N/Q)?: y
Enter new scep agent password: ********
Re-enter new scep agent password: ********
(S)ave or (D)iscard edits (S/D)?: S
```

After saving your changes, the broker service starts.

**Broker logs.** After the service starts, a new `logs` folder is created in the same directory from which the broker was started.

**Stopping the broker service.** To stop the broker, run:

```
./stopBroker.bsh
```

{% hint style="info" %}
If you ever need to troubleshoot a broker connection, the logs folder provides the most information.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.1kosmos.com/authentication/authentication-broker/connect-to-ldap-via-broker.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.