Connect Directory via the AdminX Broker

AdminX Broker allows a tenant or community administrator to connect and integrate an existing Active Directory (AD) or LDAP user directory with AdminX.

---

Overview

This topic covers connecting both directory types and installing and running the broker on Windows or Linux.

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 for full requirements.

The broker service must be kept running indefinitely for the connection between your directory and AdminX to remain valid.

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.

Tip: We recommend running only one broker type (Linux or Windows) in an environment.

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://<IP-of-NDES-server>/CertSrv/mscep/mscep.dll

• Enrollment Challenge URL — usually https://<IP-of-NDES-server>/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

Note: You can define up to four Certificate Authority (CA) configurations.

Certificate Authority status change notifications — when enabled, sends email whenever a CA changes status from active to inactive.

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.

Enable Windows Broker to self-generate X.509 certificates for every user — enables Passwordless Login for Workstations 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 <user>@<domain> 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.

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.

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.

The broker service must be kept running indefinitely for the connection between your directory and AdminX to remain valid.

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.

Tip: If you ever need to troubleshoot a broker connection, the logs folder provides the most information.

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.

The broker service must be kept running indefinitely for the connection between your directory and AdminX to remain valid.

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

Tip: If you ever need to troubleshoot a broker connection, the logs folder provides the most information.

---

User Attribute Transformation

Overview

The User Attribute Transformation tab gives administrators a powerful way to customize user attributes before they are sent out in an assertion. Use it to concatenate attributes, parse multiple phone numbers from a single Active Directory (AD) attribute, filter out sensitive AD groups, and perform the transformations your applications require at login.

Transformation scripts support ECMAScript 5.1 only. ECMAScript 6 is not supported.

Prerequisites

Before you begin, make sure that:

• Your system is running AD Broker 1.08.01 or later.

• You have permission to access the User Attribute Transformation tab.

Accessing the User Attribute Transformation tab

1

Log in

Log in to your 1Kosmos admin console. {% endstep %}

2

Open the Directory section

Navigate to the Directory section.

3

Select a directory

Click the directory you want to manage.

4

Open the tab

Locate the User Attribute Transformation tab, adjacent to the Advanced Configuration tab.

Using the User Attribute Transformation tab

Once you've opened the tab, you can:

• Compose scripts — Write transformation scripts in the built-in JavaScript editor to reshape user attributes to your requirements.

• Save a script — Enter a one-time password (OTP) for additional verification before the script is saved.

• Test a script — Click Test User Attributes, enter a username, and review every attribute associated with that user when the username is valid.

Sample use cases and scripts

Concatenate user attributes

Combine multiple user attributes into a single attribute.

function transformUsers(usersStr) {
    const staticValue = "Himank"; // static value to concatenate.
    try {
        const users = JSON.parse(usersStr);
        for (const e of users) {
            e.fname_lname = concatenateWithDistinctAttributes(e.givenname, e.lastName); //`e.lastname` is the reference to attribute configured in AD in AdminX.
            e.static_value = concatenateWithStaticAttributes(staticValue, e.givenname); //`e.givenname` is the reference to attribute configured in AD in AdminX.
        }
        return JSON.stringify(users);
    } catch (error) {
       return {error}
    }
}

function concatenateWithDistinctAttributes(attribute1, attribute2) { //concatenates two dynamic values configured in the AD(Active directory)
    return `${attribute1}+${attribute2}`;
}

function concatenateWithStaticAttributes(staticValue, attribute) { //concatenates a dynamic and static values.
    return `${staticValue}+${attribute}`;
}

	Given Name	Last Name
Before transformation	John	Doe

	Concatenated Name	Static Value Concatenated
After transformation	JohnDoe	HimankJohn

Split mobiles and landlines from a single AD attribute

Split a single AD attribute that contains phone numbers into separate values for landlines and mobiles.

function transformUsers(usersStr) {
    try {
        const users = JSON.parse(usersStr)
        for (const e of users) {
            if (e.facsimiletelephonenumber) {
                const phones = parsePhoneString(e.facsimiletelephonenumber);
                e.mobiles = phones.mobiles;
                e.landlines = phones.landlines;
            }
        }
        return JSON.stringify(users);
    } catch (e) {
        console.log(e.toString());
        console.log(e.stack);
    }
    return usersStr;
}

function parsePhoneString(phoneString) {
    const phones = phoneString.split(';');

    const result = {
        mobiles: [],
        landlines: []
    };

    phones.forEach(function (phone) {
        const match = phone.match(/([ML])(\d+)(x\d+)?/);
        if (match) {
            const [, type, number, extension] = match;
            const phoneNumber = extension ? `${number}${extension}` : number;
            if (type === 'M') {
                result.mobiles.push(phoneNumber);
            } else if (type === 'L') {
                result.landlines.push(phoneNumber);
            }
        }
    });

    return result;
}

• Before transformation: M:192837496478; M: 17839978923; L:2345672349 x728

• After transformation: Mobiles: {192837496478, 17839978923} Landlines: {2345672349 x728}

UAC parsing for account locked and disabled

The following script checks a user's UAC (User Account Control) values and returns whether the account is disabled or locked.

function transformUsers(usersStr) {
    try {
        const users = JSON.parse(usersStr)

        for (const e of users) {
            const userAccountControlValue = e.useraccountcontrol || e.userAccountControl;

            e.isUserDisabled = (userAccountControlValue & 0x0002) !== 0; // Checks the user attribute values in the AD and matches with the defined condition. Please note that ['512', '544', '66048', '262656', '1049088', '520']are hardcoded as UAC values for an active user.
            e.isUserLocked = (e.lockouttime && e.lockouttime > 0) ? true : false;// A non-zero value of AD attribute `lockoutTime` denotes that the user is locked.
        }
        return JSON.stringify(users);
    } catch (e) {
        console.log(e.toString());
        console.log(e.stack);
    }
    return usersStr;
}

Summary

With the User Attribute Transformation tab, administrators can tailor user attributes to specific requirements, streamline authentication, and improve overall system efficiency. Use the sample scripts above as a starting point for your own transformations.