Synchronize data with Active Directory via LDAP

This guide demonstrates how to use Deskradar LDAP companion application to sync your LDAP data to your Deskradar instance.

Deskradar LDAP companion is a CLI application provided as a Docker container. It connects to your LDAP endpoint, downloads the data and pushes it to your Deskradar instance. On Deskradar, it initiates import process by creating an import job.

NOTE

The application can be run on demand manually or launched by a task scheduling mechanism of your choice.

Prerequisites

1. LDAP is enabled on your domain controller
2. Worker node to run the application
   1. Docker is installed on the worker node
   2. Worker node can access your LDAP server

Install on Linux worker node

Download the compressed Docker image file deskradar_ldap-companion_latest.gz. We provide you with the download link upon request. Please reach out to the Support Team by sending an email to support@deskradar.com.

wget https://<DOWNLOAD_URL>/deskradar_ldap-companion_latest.gz

Import Docker image:

cat deskradar_ldap-companion_latest.gz | gzip -d | docker load

Running the application

docker run deskradar_ldap-companion:latest <command> <options>

Run without parameters to get help:

docker run --rm deskradar_ldap-companion:latest

docker run --rm deskradar_ldap-companion:latest help

docker run --rm deskradar_ldap-companion:latest <command> --help

Commands

• export command downloads the data from the LDAP server and saves it locally as a CSV or JSON file.
• push csv command uploads the data from a local CSV file to your Deskradar instance.
• push ldap command upload the data from your LDAP server to your Deskradar instance.

Configuration

The application can be configured using following options:

1. Command line parameters
2. Environment variables
3. JSON configuration file

Configuration methods can be used in combination. Whereas, a single parameter can be defined using multiple configuration methods. In that case the value is determined by the configuration method with the highest priority. The order in which the configuration methods are listed above, reflects that priority.

Example. If a parameter defined in the command line, then the different value of the same parameter specified in the environment variable or JSON configuration file will be ignored.

Quick Start

Run application with command line parameters

Example for running application to export LDAP data to a CSV file on a Linux host.

docker run --rm -v $(pwd)/data:/data \
deskradar_ldap-companion:latest export \
--ldap-uri "ldaps://ldap.acme.lan:636" \
--ldap-username "admin" \
--ldap-password "p4Ssw0r6" \
--base-dn "cn=users,dc=acme,dc=com" \
--attributes "displayName,userPrincipalName" \
--format csv \
--output /data/output.csv

Configure application with a JSON configuration file

Default configuration:

{
  "logLevel": "info",
  "format": "json",
  "attributes": "displayName,userPrincipalName",
  "uuidAttributes": "objectGUID",
  "base64Attributes": "objectSid,thumbnailPhoto,jpegPhoto",
  "columns": "displayName,email",
  "resource": "staff",
  "attributesUpdateMode": "replace",
  "removeUnmatchedMode": "none"
}

Example JSON configuration file overriding some parameters:

{
  "ldapUri": "ldaps://ldap.acme.lan:636",
  "ldapUsername": "admin",
  "ldapPassword": "p4Ssw0r6",
  "baseDn": "cn=users,dc=acme,dc=com",
  "attributes": "displayName,userPrincipalName"
  "format": "csv",
  "output": "/data/output.csv",
}

To configure application with a JSON configuration file, create a config.json file. Then run the application with the local file mounted into the container on path exactly /app/config/local.json:

docker run --rm \
-v $(pwd)/config.json:/app/config/local.json \
deskradar_ldap-companion:latest export

Configure application with environment variables

docker run --rm \
-v $(pwd)/data:/data \
-e LOG_LEVEL=trace \
-e CONF_LDAP_URI=ldaps://ldap.acme.lan:636 \
-e CONF_LDAP_USERNAME=admin \
-e CONF_LDAP_PASSWORD=p4Ssw0r6 \
-e CONF_BASEDN=cn=users,dc=desk,dc=radar \
-e CONF_ATTRIBUTES=displayName,userPrincipalName \
-e CONF_FORMAT=csv \
-e CONF_OUTPUT=/data/output.csv \
deskradar_ldap-companion:latest export

Configuration Parameters

Configure logging

Command line argument	Environment variable	JSON configuration file key name
--quiet or --verbose	LOG_LEVEL	logLevel

Valid values for environment variables and JSON configuration file: trace, debug, info, warn, error, fatal.

Use --quiet to set logLevel to warn (display only errors and warnings) or --verbose to set logLevel to debug to show more log messages.

Default: info

Commands: export, push csv, push ldap

LDAP username

Command line argument	Environment variable	JSON configuration file key name
--ldap-username <string>	CONF_LDAP_USERNAME	ldapUsername

Username for LDAP server connection.

Default: empty

Commands: export, push csv, push ldap

LDAP password

Command line argument	Environment variable	JSON configuration file key name
--ldap-password <string>	CONF_LDAP_PASSWORD	ldapPassword

Password for LDAP server connection.

Default: empty

Commands: export, push csv, push ldap

Base DN

Command line argument	Environment variable	JSON configuration file key name
--base-dn <string>	CONF_BASEDN	baseDn

Base DN for the LDAP connection.

Example: cn=users,dc=acme,dc=com

Default: empty

Commands: export, push csv, push ldap

LDAP Filter

Command line argument	Environment variable	JSON configuration file key name
--ldap-filter <string>	CONF_LDAP_FILTER	ldapFilter

Search query for LDAP search.

Example: (&(physicalDeliveryOfficeName=Chicago)(department=ExampleDepartment))

Default: empty

Commands: export, push csv, push ldap

LDAP URI

Command line argument	Environment variable	JSON configuration file key name
--ldap-uri <string>	CONF_LDAP_URI	ldapUri

URL of the LDAP server.

Example: ldaps://10.0.0.24:636

Default: empty

Commands: export, push csv, push ldap

Format

Command line argument	Environment variable	JSON configuration file key name
--format <string>	CONF_FORMAT	format

Format in which to save the exported LDAP data. Valid values: json or csv.

Default: json

Commands: export

Output

Command line argument	Environment variable	JSON configuration file key name
--output <string>	CONF_OUTPUT	output

Path to file to which the exported LDAP data needs to be written.

Default: empty

Example: /app/data/output.csv

Commands: export

Attributes

Command line argument	Environment variable	JSON configuration file key name
--attributes <list>	CONF_ATTRIBUTES	attributes

Comma separated list of attributes to select from the LDAP records. Attributes list must have exactly the same number of items in the respective order as the columns list defined by the Columns parameter.

Default: displayName,userPrincipalName

Example: displayName,userPrincipalName,physicalDeliveryOfficeName,roomNumber,userWorkstations

Commands: export, push csv, push ldap

UUID attributes

Command line argument	Environment variable	JSON configuration file key name
--uuid-attributes <list>	CONF_UUID_ATTRIBUTES	uuidAttributes

Comma separated list of LDAP attribute names which need to be converted to UUID string.

Default: objectGUID

Commands: export, push csv, push ldap

Base64 Attributes

Command line argument	Environment variable	JSON configuration file key name
--base64-attributes <list>	CONF_BASE64_ATTRIBUTES	base64Attributes

Comma separated list of LDAP attribute names which contain binary data and need to be encoded as Base64 string.

Default: objectSid,thumbnailPhoto,jpegPhoto

Commands: export, push csv, push ldap

Deskradar instance URL

Command line argument	Environment variable	JSON configuration file key name
--site-uri <string>	CONF_SITE_URI	siteUri

Your Deskradar instance base URL.

Example: https://acme.deskradar.cloud

Default: empty

Commands: push csv, push ldap

Deskradar user email

Command line argument	Environment variable	JSON configuration file key name
--site-email <string>	CONF_SITE_EMAIL	siteEmail

Deskradar instance user email for accessing import API endpoints. User must have role Editor or Administrator. User must exist locally on the Deskradar instance, no SSO credentials can be used. Consider creating system user on your Deskradar instance with strong password.

Example: automation-editor@acme.com

Default: empty

Commands: push csv, push ldap

Deskradar user password

Command line argument	Environment variable	JSON configuration file key name
--site-password <string>	CONF_SITE_PASSWORD	sitePassword

Deskradar instance user password.

Default: empty

Commands: push csv, push ldap

CSV file

Command line argument	Environment variable	JSON configuration file key name
--file <string>	CONF_FILE	file

Path to CSV file which needs to be pushed to your Deskradar instance.

Example: /app/data/input.csv

Default: empty

Commands: push csv

Columns

Command line argument	Environment variable	JSON configuration file key name
--columns <list>	CONF_COLUMNS	columns

Comma separated list of column names for creating an import job on your Deskradar instance. Certain columns are required for certain resource types. Resource type is defined by the Resource parameter. Columns list must have exactly the same number of items in the respective order as the attributes list defined by the Attributes parameter.

Valid column names:

Column name	Required for resource types	Resource types	Validations	Notes
buildingName	any	any	string, max length 20 characters	Building names must be unique on your Deskradar instance.
floorLabel	any	any	string, max length 3 characters	Floor labels must be unique within every building on your Deskradar instance.
locationId	Required: desks, rooms, utilities. Optional: staff	any	string, max length 36 characters, regex: /^[a-zA-Z0-9_\.\:\/\\-]+$/	Identifies the location of the marker.
email	staff	any	string, valid email	Email identifies staff marker and must be unique for resource type staff.
firstName	optional	staff	string, max length 48 characters	Person first name
lastName	optional	staff	string, max length 48 characters	Person last name
displayName	optional	any	string, max length 100 characters	Value is used for the marker name. If not defined, firsName and lastName will be combined to construct the resulting name.
role	optional	any	string, max length 100 characters	Comma separated list of strings can used.
status	optional	any	string, must be one of available, unavailable or remote (only for resource type staff)	Marker status. Default: available.
statusText	optional	any	string, max length 140 characters	Marker status text
nickname	optional	staff	string, max length 100 characters	Person nickname
url	optional	any	string, max length 100 characters	URL of the relevant website or resource details page
skype	optional	any	string, max length 100 characters	Skype username
twitter	optional	any	string, max length 100 characters	Twitter handle
linkedin	optional	any	string, max length 100 characters	LinkedIn profile
phoneOffice	optional	any	string, max length 100 characters	Office phone number
phoneMobile	optional	any	string, max length 100 characters	Mobile phone number
notes	optional	any	string, max length 1000 characters	Marker notes
deskType	optional	desks	string, must be one of spare, hot	Default: spare

Example: displayName,email,buildingName,floorLabel,locationId

Default: displayName,email

Commands: push csv, push ldap

Resource

Command line argument	Environment variable	JSON configuration file key name
--resource <string>	CONF_RESOURCE	resource

Resource type for the import job on your Deskradar instance. Setting different resource type may require changes in the Columns parameter setting. See Columns parameter.

Valid values: staff, desks, rooms, utilities

Default: staff

Commands: push csv, push ldap

Attributes update mode

Command line argument	Environment variable	JSON configuration file key name
--attributes-update-mode <string>	CONF_ATTRIBUTES_UPDATE_MODE	attributesUpdateMode

Existing marker attributes update mode for import. Set to merge to keep the attributes of the existing markers that are not imported as part of the import procedure, but defined by the editors. For more information on, please refer to the import documentation.

Valid values: replace, merge

Default: replace

Commands: push csv, push ldap

Remove unmatched marker mode

Command line argument	Environment variable	JSON configuration file key name
--remove-unmatched-mode <string>	CONF_REMOVE_UNMATCHED_MODE	removeUnmatchedMode

Existing marker removal mode. For more information on, please refer to the import documentation.

Valid values: none, floorScope, all

Default: none

Commands: export, push csv, push ldap

Override JSON

Command line argument	Environment variable	JSON configuration file key name
--override-json <string>	CONF_OVERRIDE_JSON	overrideJson

Override entry data with data from given JSON string. JSON must be an object with keys for every field you want to override in the data entry. Values in the JSON object must be strings. Fields don't have to exist in the entry.

Example: {"buildingName":"Headquarters"}

Default: empty

Commands: export, push csv, push ldap

Data Processing Middleware

In order to modify or filter the data delivered by the LDAP endpoint before exporting it to CSV file or pushing it to Deskradar, use data processing middleware.

Data processing middleware is a JavaScript function that receives a single argument (an array of objects containing the data obtained from the LDAP endpoint) and is expected to return an array of objects as well. Here is the interface implementation:

module.exports = (entries) => {
  return entries
}

Single file override

Let's consider an example with the following given conditions:

• An attribute for floor label is not present in LDAP;
• Most of the entries in LDAP have a defined userWorkstation attribute which is the desk number;
• Floor label is encoded in the desk number in the format AA-000, where AA is a floor label and 000 is the actual desk number on the floor.

Out goal:

• Use userWorkstation attribute as locationId in Deskradar as defined in LDAP;
• Derive floor label from the desk number and use it as floorLabel column in Deskradar;
• Ignore all LDAP entries which have empty userWorkstation attribute.

To achieve that, create a file on the host machine named middleware.js with the following content:

module.exports = (entries) => {
  return entries.reduce((acc, entry) => {
    // Ignore entries with no userWorkstations attribute
    if (!entry.userWorkstations) {
      return acc
    }

    // Split the userWorkstations attribute
    const derivedFloorLabel = entry.userWorkstations.split('-').shift()

    acc.push({ ...entry, derivedFloorLabel })
    return acc
  }, [])
}

The middleware function will:

• skip the entries with an empty userWorkstations attribute;
• split the value of the userWorkstations attribute accordingly to the defined format and set the value of the new derivedFloorLabel field added to the entry as if it was received from the LDAP;
• pass the modified data to the CSV export and data push steps of the pipeline.

Next, create config.json file with the following configuration. Notice the new attribute derivedFloorLabel added to the attributes field, and floorLabel column added to the columns field (required if you want use the push csv command instead of export).

{
  "ldapUri": "ldaps://10.0.0.24:636",
  "baseDn": "ou=DemoUsers100,dc=contoso,dc=com",

  "ldapUsername": "<username>",
  "ldapPassword": "<password>",

  "attributes": "displayName,userPrincipalName,physicalDeliveryOfficeName,derivedFloorLabel,userWorkstations",
  "columns": "displayName,email,buildingName,floorLabel,locationId",

  "format": "csv",
  "output": "data/output.csv"
}

Now let's run the application. We'll mount the middleware file to the Docker container on the /app/data-middleware/index.js path.

docker run --rm \
  -v $(pwd)/middleware.js:/app/data-middleware/index.js \
  -v $(pwd)/config.json:/app/config/local.json \
  -v $(pwd)/data:/app/data \
  deskradar_ldap-companion:latest export

This will create a output.csv file in the host ./data directory with the columns:

• displayName
• userPrincipalName
• physicalDeliveryOfficeName
• derivedFloorLabel
• userWorkstations

This file can be imported via Deskradar user interface.

To push data directly to Deskradar, replace export command with push csv and provide access credentials to your Deskradar site accordingly to the documentation.