> 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-directory-via-the-adminx-broker.md). # Connect Directory via the AdminX Broker *** ## Overview This topic covers connecting both directory types and installing and running the broker on Windows or Linux. {% hint style="info" %} **Before you begin:** The downloaded broker must be copied to, and installed on, a Windows or Linux server that is part of your Active Directory domain. See [AdminX Broker System Requirements ](/authentication/authentication-broker/system-requirements.md)for full requirements. {% endhint %} {% hint style="warning" %} The broker service must be kept running indefinitely for the connection between your directory and AdminX to remain valid. {% endhint %} ### Connect AD via Broker #### Getting started 1. Log in to your tenant as a community administrator. 2. Navigate to **Directory > Directory Integrations**. 3. On the **Directory Integrations** page, click **Add new directory**. 4. Select **Active Directory** from the menu. 5. Enter a name to use for this connection, and click **Setup Directory**. #### Step 1: Download and install the broker 1. In the **Download Broker** tab, click the **Download** link for the broker you want. The downloaded archive must be copied to and installed on a Windows or Linux server that is part of your Active Directory domain. 2. After downloading the broker, click **Next**. {% hint style="info" icon="lightbulb-exclamation-on" %} **Tip:** We recommend running only one broker type (Linux or Windows) in an environment. {% endhint %} #### Step 2: Configure connection information Under **Connection Information**, enter the connection details for your Active Directory domain: * **Server protocol type** — select **LDAP** or **LDAPS** * **Base Domain** — your AD base domain * **Server Port** — your AD server port * **Hostname / IP Address** — the AD server IP address Under **Failover Support**, specify one or more hostnames. The broker fails over to the next hostname after the configured timeout: * **Timeout in seconds** — the duration after which the broker fails over to the next hostname in the list * **Server Port** — the port used to connect to the configured hostname * **Host Name / IP Address** — hostname or IP address of the target server for certificate operations * **Retry Host After (minutes)** — the time after which an inactive host is retried to check whether availability has been restored Under **Service Account Information**, enter the details for your Active Directory service account: * **Service account username** — the AD 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 your account, 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 let administrators specify conditions that determine which directory users are eligible to authenticate. This is useful, for example, when allowing only user accounts that are marked as active. 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 After configuring the connection information, map 1Kosmos attributes so the broker can interact with Active Directory. 1. In the **Attributes mapping** tab, click **Add new mapping**. 2. Map each directory attribute to its corresponding 1Kosmos attribute: | Directory attribute | 1Kosmos attribute | | ------------------- | ----------------- | | samaccountname | uid | | samaccountname | username | | mobile | phone | | mail | email | | givenname | firstname | | sn | lastname | For example, to add the `sAMAccountName` attribute: 1. In the **Attributes mapping** tab, click **Add new mapping**. 2. In the **Add attribute mapping** window, enter the directory attribute — in this example, `samaccountname`. 3. From the **1Kosmos attribute** drop-down, select `uid`. 4. Click **Create**. Repeat for each attribute in the table. To map a group attribute, follow these steps: 1. In the **Attributes mapping** tab, click **Add new mapping**. 2. In the **Directory attribute** box, enter your directory's group attribute (e.g., `ibm-allgroups` for IBM Directory Server). 3. From the **1Kosmos attribute** drop-down, select `groups`. 4. Click **Create**. 5. When you have finished adding mappings, click **Next**, then **Complete**. Once mapped, the platform requests this attribute during the user search and populates each user's group memberships from the returned values. **How Group Names Are Resolved** The directory returns group membership as distinguished names (DNs). The platform extracts the **CN** (common name) from each returned DN and uses it as the group name. For example, if the directory returns `cn=Employees,cn=Groups,ou=Users,o=Example`, the platform resolves it to the group name **Employees**. **Supported Directories** * Any LDAP directory that exposes group membership as an attribute when explicitly requested (e.g., IBM Directory Server via the `ibm-allgroups` pseudo-attribute) * Active Directory continues to work as before, with no configuration change #### Step 4: Associate brokers Use the **Brokers** tab to add a new broker for interacting with Active Directory. After adding a broker, use the (**...**) menu under the **Actions** column to rename or disable it. #### Step 5: Advanced configuration Use the **Advanced Configuration** tab to configure additional broker settings, including notifications and authentication behavior. Click **Save Changes** once all required options are configured. Available options include: **Broker Log Settings** * **Broker Log File Size** — the maximum log file size in megabytes (whole numbers only); a new log file is created when this size is reached. * **Broker Rotation Count** — the maximum number of log files to retain; when exceeded, the oldest log file is deleted. **Broker Notifications** — when enabled, sends email alerts to specified addresses if the broker experiences connectivity issues. Toggle the switch on, set the alert delay time in minutes, enter recipient addresses under **Who should we notify?**, and click **Add new** to add more. **Hostname status change notifications** — when enabled, sends email to administrators and other specified recipients whenever a host changes status from active to inactive. **Workstation Login (Linux Broker Settings)** — configure the NDES infrastructure to issue certificates required by Linux brokers: * **Enrollment Agent name** — a name to use for the enrollment * **SCEP Service URL** — usually `https:///CertSrv/mscep/mscep.dll` * **Enrollment Challenge URL** — usually `https:///CertSrv/mscep_admin` **Workstation Login (Windows Broker Settings)** — specify the Domain Controller DNS and the Certificate Authority (CA) that issues the X.509 certificate to the user: * **Windows Template** — the certificate template used to issue the X.509 certificate * **Domain Controller DNS** — the DNS address of the Domain Controller server * **Certificate Authority Name** — the CA designated to issue the X.509 certificate {% hint style="info" %} **Note:** You can define up to four Certificate Authority (CA) configurations. {% endhint %} **Certificate Authority status change notifications** — when enabled, sends email whenever a CA changes status from active to inactive. {% hint style="info" %} **Note:** An `E_CA_STATUSCHANGE` event is triggered when a CA status changes from active to inactive. A notification is generated for a CA only when the status changes from Active to Inactive, the previous status is Active and the new status is Inactive, and at least 5 minutes have elapsed since the last notification for the same CA. {% endhint %} **Enable Windows Broker to self-generate X.509 certificates for every user** — enables [Passwordless Login for Workstations ](/authentication/windows-workstation-mfa/overview.md)using X.509 certificates self-generated by the Windows Broker, allowing users to log in to workstations with the 1Kosmos mobile app without relying on NDES. Before enabling, the AD Broker `service` entry needs special permissions to execute the Windows `certutil` command: 1. *Stop* the AD Broker service. 2. Open **Administration Tools → Services → BlockID Broker → Properties**. 3. Select the **Log On** tab. 4. Click **This Account** and enter the user in `@` format. (You must use this format.) 5. Enter and confirm the **Password**, then apply. 6. Restart the AD Broker service. To find the **Windows Template Name**, run `certsrv` on a host with Domain Controller access, select your Domain Controller from the Certification Authority group, and select **Certificate Templates**. The template must have **Client Authentication** and **Smart Card Logon** listed under **Certificate Purposes**. Enter the same template name in AdminX under **Windows Template Name**. To find the **Domain Controller DNS** and **Certificate Authority Name**, run `certutil` from your Windows Server host to display the configured CAs, then enter the appropriate values in AdminX. (There may be multiple entries — select the CA used to generate X.509 certificates for your Windows workstations.) **Password Policies** — toggle on to define password reset requirements: * **Authentication Factor** — select a passwordless factor (Face ID/Touch ID for biometrics, or Live ID for live gestures) * **Password Policy Description** — guidance text shown to the user when resetting their password * **Password Policy** — set the new password requirements, including minimum length and complexity requirements **Check for Password Reset on Next Logon** — when enabled, all users authenticating are checked against Active Directory to determine whether a password reset is required. Users flagged for a forced reset on next logon (AD error code `773`) are prompted by AdminX to set a new password; users authenticating via passwordless methods are not prompted. Ensure the **user must change password at next logon** box is marked in Active Directory. When the user next logs in with a password-based method, they are prompted to change their password and then to enter a six-digit one-time passcode (OTP); after successful OTP authentication, they are logged in with their new password. **Kerberos Single Sign-on** — toggle on to enable Kerberos Desktop SSO, allowing users to sign in to 1Kosmos applications automatically when logged into their Active Directory domain. After enabling, upload your Kerberos **keytab** file via **Upload**. For more information, see [Kerberos SSO.](broken://pages/JGqgRYIR2XSbPEtTGzM9) **Enhanced Security** — toggle on to prevent scenarios in which a malicious broker could connect to your Active Directory. #### Step 6: User attribute transformation Use this tab to modify user attributes before including them in an assertion. For more information, see [User Attribute Transformation.](/authentication/admin-portal/directory-integrations/user-attribute-transformation.md) After making changes across the tabs, click **Save Changes**. *** ### 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. After downloading, click **Next**. #### 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="warning" %} 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" icon="lightbulb-exclamation-on" %} **Tip:** 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" icon="lightbulb-exclamation-on" %} **Tip:** 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-directory-via-the-adminx-broker.md?ask=&goal= ``` `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.