Jira Service Management Support

A Lightweight Directory Access Protocol (LDAP) directory is a collection of data about users and other assets. If you work with a corporate directory that contains your assets or employee-manager relationships used for approval processes, you can import such LDAP entries to Assets. To make things easy, Assets has modules that works with popular LDAP directories, which fetch the structure and the assets from your directory. This article shows you how to set this up. More about importing

You need to be a Jira admin to create, configure, and enable LDAP imports.

Skip to:

LDAP overview
LDAPS validation
Importing LDAP
Pre-defined structure and configuration
Import configuration created
Object type mapping

Overview

LDAP is an Internet protocol that web applications can use to look up information about those assets from the LDAP server.

We provide a built-in connectors for the most popular LDAP directory servers:

Microsoft Active Directory
Apache Directory Server (ApacheDS)
Apple Open Directory
Fedora Directory Server
Novell eDirectory
OpenDS
OpenLDAP
OpenLDAP Using Posix Schema
Posix Schema for LDAP
Sun Directory Server Enterprise Edition (DSEE)
A generic LDAP directory server

LDAPS validation

LDAPS (Secure LDAP) is supported and doesn't have any special requirements from Assets to work.

If you are trying to import from an LDAPS source, you can choose to validate the LDAP server certificate with an imported Certificate Authority (CA) certificate. If you select to validate the LDAP server certificate, you must import the root CA certificate from the CA that signed the LDAP server certificate, so your Jira can use the CA certificate to validate the LDAP server certificate. More information is explained here.

Be sure to change the port to 3269. This is due to the fact that a GC (global catalog) server returns referrals on 389 which refers to the greater AD "forest", but acts like a regular LDAP server on 3268 (and 3269 for LDAPS) when changing from LDAP to LDAPS.

Importing LDAP

To create an Import structure:

From your service project, go to Assets, then Object Schemas.
From the Object Schemas list, select More actions and then select Configure.
In the Schema configuration view, open the Import tab.
Under the Import tab:
- If there’s no import structure, you’ll see the message “You don't have any import connections yet”. Select Create Import configuration to create a new import structure.
- If an import structure has already been created, select Create Configuration.
Select CSV import, then select Next.
Fill in the General, Module, and Scheduling import fields.

General fields

Here are general fields, common for every import type:

Name	Description
Name	The name of the import.
Description	The description for your convenience.
Concatenator	You can specify a default concatenator. When joining multiple data locators into one Assets attribute, this will be the default concatenator. One example could be to join two columns like "First name" and "Last name" into one attribute. So "Mathias" (first name) and "Edblom" (last name) will be concatenated as "Mathias Edblom" if using \s as concatenator. Enter `\s` for space-concatenated. To include a concatenate character, place the value between double quotes (i.e "\s").
Empty Values	Defines what should happen when a Data Locator is empty: Ignore - the existing value in the object will be retained and not overridden by an empty value. Remove - the existing value for the object will be removed, and replaced with an empty field value.
Unknown Values	Defines what should happen if a Data Locator is unknown. This could happen with attribute types like "Status" and "Select". Ignore - the value from CSV will be ignored and the object attribute will be left empty. Add - the value passed in the CSV file will be added to the list and the object attribute will be updated with the new value.
Date Format	Format for date fields in import source to convert dates into Insight. If left empty, Insight will automatically try to find correct format. The format should be specified according to the Java SimpleDateFormat guidelines.
Date/Time Format	Format for date/time fields in import source to convert dates into Insight. If left empty, Assets will automatically try to find correct format. The format should be specified according to the Java SimpleDateFormat guidelines.

Module fields

These fields are specific to an import type (module).

Setting	Description
URL	Protocol, Hostname and Port of the server running LDAP. For example: `ldap://ldap.example.com:389`
User DN	The distinguished name of the user that the application will use when connecting to the directory server. For example: `cn=administrator,cn=users,dc=ad,dc=example,dc=com` `cn=user,dc=domain,dc=name` `user@domain.name`
Password	The password of the user specified above.
Base DN	The root distinguished name (DN) to use when running queries against the directory server. Examples: `o=example,c=com` `cn=users,dc=ad,dc=example,dc=com` For Microsoft Active Directory, specify the base DN in the following format: `dc=domain1,dc=local`. You will need to replace the `domain1` and `local` for your specific configuration. Microsoft Server provides a tool called `ldp.exe` which is useful for finding out and configuring the the LDAP structure of your server. If you want specific Base DN in your object type see the Selector value below
Search filter	Defines the scope of the filter search, default is *(objectClass=)** which will give you all entries. If you only want Jira Users for example, you can set (objectClass=person). Note that the Users in LDAP need to have the the "objectClass" set to "person". The search filter is important in the way that it can affect the synchronization time.
Search scope when importing	Search scope can be ONE_LEVEL, OBJECT, or SUBTREE. This setting corresponds to the LDAP search scopes and determines how objects should be fetched from the LDAP. The default setting is ONE_LEVEL while the locators and structure are created with SUBTREE.
Follow Referrals	LDAP Follow Referrals is a functionality that ensures you receive the correct data in a distributed LDAP environment. This is particularly useful when dealing with multiple LDAP servers or domains, as it allows the LDAP client to follow referrals to other LDAP servers to retrieve the requested information. In practice, this means that if an LDAP server can't fulfill a request, it can refer the client to another server that might have the required information. This is crucial for maintaining data consistency and completeness across distributed systems.
Include namespace	This option is only applicable when creating an Assets object structure from an LDAP server. The option will append the namespace e.g. cn=users,ou=company,=dc=examle,dc=com to the object type description. The value is not used while performing synchronizations.

Scheduling fields

Scheduling fields are responsible for keeping your data in sync:

Name

Description

Synchronizing Account

The Jira user to use when synchronize data into Assets.

For LDAP and database imports, the account used for synchronization must have Jira admin permissions.

Cron Expression

The interval for the automatic synchronization.

Automatically Synchronize

If the import should be scheduled for automatic synchronization.

7. Select Save Import Configuration.

Next, you can create a predefined structure and configuration for your LDAP import.

Pre-defined structure and configuration

You can import users or groups from only one Organizational Unit (OU) during an Assets LDAP import. For more information, see How to import users or groups from specific OUs with Assets LDAP import.

In the next step, you can create the predefined structure and configuration manually or Assets can create them automatically. To make this process automatic, select:

Create predefined structure – this will create object types with attributes and relationships in the schema
Create predefined configuration – this will create type mappings in the import configuration.

Create predefined structure and configuration window

Here's some details for the LDAP import:

Predefined structure

The structure will be created based on the result from the LDAP server. When creating the predefined structure, a query will be sent to the LDAP server with the configuration specified and fetch the result. Based on the result, an object type hierarchy will be created. Each node (identified by DN) that has children will be treated as an object type and created. The attributes belonging to the Assets object type will be the attributes found on the node in the LDAP server.

If the result returned by LDAP server retrieves objects that don't have children, then it won't be possible to create a predefined structure automatically and it should be created manually.

The predefined structure will create two additional attributes for each object type. The attribute CN (Common Name) will be used as label and the attribute DN (Distinguished Name) will be set with the property hidden.

All attributes created by the predefined structure in the LDAP import will be of type Default Text. If the data represent something else review the attributes and change them accordingly.

Example

Example LDAP structure	Resulting Assets Object Type Structure

Predefined configuration

The predefined configuration will query the LDAP server and create a configuration mapping based on the same criteria as the structure described above. As data locators all attributes found will be choosable with the addition of the CN (Common Name) and the DN (Distinguished Name).

The identifier will be set to DN for each object to uniquely identify each object from the LDAP server. Since the predefined configuration will be different based on the connected LDAP server, the following is one example mapping the Employees as seen in the previous example.

If the LDAP import is configured to import users one can use the REGEX configuration to split users in order to create multiple users.

Import configuration created

You can now view your import configuration, but it's not ready yet. You still need to create or review the object type and attribute mapping, and make sure there are no problems with your import configuration.

When you're ready, go to 2. Create object type and attribute mapping.

Before you go

In the next step, you'll create the object mapping settings. Here are some settings specific to the LDAP import type.

Object type mapping

Name

Description

Selector

In the LDAP import type, the Selector is prepended to the Base DN value before the search in LDAP is executed. The value is used to narrow down the structured tree in the LDAP to specific nodes.

The search filter will be the same as specified in the general configuration but the selector will narrow the scope where the search filter is applied.

For example, if the Base DN is dc=ad,dc=example,dc=com and the Selector is cn=users the resulting LDAP search base will be cn=users,dc=ad,dc=example,dc=com.

Jira Service Management Support

Products

Jira Software