Configure LDAP

Lightweight Directory Access Protocol (LDAP) is supported by Incorta Analytics to manage users, groups, and authorization. Use SSO with LDAP to access the groups and users stored in your user database.

Active Directory

If the Active Directory is configured with referrals and the scope of the search is not in the same domain as the contacted domain controller, search the Global Catalog.

To search the global catalog:

  1. Go to the <installation_path>/IncortaNode/bin directory, and open the file ldap-config.properties.
  2. Change ldap.base.provider.url to the Global Catalog URL, using ldaps for the secured Active Directory setup along with the Global Catalog port number. For unsecured setups, use ldap with the Global Catalog number.

Enable LDAP Tenants

To use LDAP for a tenant, configure a tenant in LDAP using the following process.

  1. Edit the ldap.properties file.
  2. Run the Tenant Management Tool (TMT) to update the tenant configuration with the ldap.properties file using the following command:

    • Linux or Mac: ./tmt.sh --update-property <tenant_name> file ldap.properties
    • Windows: tmt --update-property <tenant_name> file ldap.properties

Incorta uses the ldap.user.mapping.login attribute as the default for logging in. Configure ldap.user.mapping.auth with the following values:

  • Null (not defined) – When null, the system uses the default ldap.user.mapping.login values lookup the DN and authenticate the user.
  • Same values – When the same values as ldap.user.mapping.login are used it looks up the same location.
  • Different values – When different values are used it looks up the DN and authenticates the user. After authenticating the user the ldap.user.mapping.login is used to to lookup the appropriate ID and search the Incorta “USER” table to find the user record and log the user in.

Synchronize a Directory

This command synchronizes users and groups between Incorta and the source application where the Administrator has exported a list of users/groups/assignments from the source system into csv files, the sync_directory command reads those files and and imports the information into Incorta.

  • users.csv
  • groups.csv
  • user-groups.csv

This endpoint requires superuser privilege and is accessed using the Incorta Analytics CLI API. It returns a list of which rows succeeded and which rows failed.

Use the following commands to synchronize a directory. Note that these commands must be run from the folder containing the incorta.py file.

session=`python incorta.py login <server host> <tenant name> <username> <password>`

python incorta.py sync_directory $session <archive path><full sync>

Examples:

python incorta.py sync_directory $session directory.zip

python incorta.py sync_directory $session directory.zip true

The examples use the following parameters:

Command Definition
sync_directory Synchronize the system users and groups along with their assignments using a zip file containing three CSV files
archive path The path to the three CSV files
full sync (optional) The default value for this parameter is set to ‘false’, meaning syncing existing users and groups would fail. When set to  ‘true’ all user and group assignments are flushed before importing. Existing users and groups are updated.
session The superuser session for executing the command

The CSV files contain the following parameters:

File Content for groups.csv:

Parameter Notes
Name Required. Group name.
Description Group description. Required, but can be null (blank)
Type Group type. Optional. Possible values: 1. Internal (default): using Incorta login (not SSO). 2. SSO: the group is imported from an SSO. 3. LDAP: The group is maintained by an LDAP directory server.
ExternalID Required only if the type is LDAP when it holds the value of the Group Distinguished Name.

Sample Content

Name Description Type
Group1 Sample Group 1 Internal
Group2 Sample Group 2 SSO

File Content for users.csv:

Parameter Notes
Login Name Required. Unique.
Email Required. Unique.
Display Name Required. Unique.
Language Required only if the type is LDAP when it holds the value of the Group Distinguished Name.
Country Required, but can be null (blank)
Timezone Required, but can be null (blank)
Calendar Required, but can be null (blank)
Type User type: Optional. Possible values: internal, default, or user. Incorta handles password management. Store, encrypt, change, reset, are authenticated by an SSO gateway before reaching the Incorta server. SSO gateway must send Incorta a user ID that matches the login. LDAP: The user is authenticated by an LDAP server reachable by the Incorta instance. For internal users, the password is set to the same value as the login name. The user must change the password on first login.

Sample Content

Login Name Email Display Name Type
User1 user@email.com User1 INTERNAL
User2 user@email.com User2 SSO
User2 user@email.com User3 SSO

File content for user-groups.csv

Parameter Notes
Group Name Required.
Login Name Required.

Sample Content

Group Name User Login Name
group 1 user_1
group 2 user_2
group 3 user_3

Notes:

  • Fields including a comma, (,) must place the comma between double quotes ("").
  • CSV files can not contain unnecessary spaces.
  • Column order is important.

Use the Directory Export tool to export users and groups

The directory export tool (dirExport) exports users and groups, along with their assignments, as zipped CSV files that can later be imported using the syncDirectory API. Use this tool to export users and groups from a database or export users and groups from an LDAP Server in a zipped CSV file.

Export users and groups from a Database

To export users from a database, use the following command:

Windows: dirExport -db db-config.properties [--debug] Linux: ./dirExport.sh -db db-config.properties [--debug]

Use the [—debug] flag to enable the debugging mode.

The db-config.properties file must have the following defined:

  • connectionString: This is the JDBC connection string for the database, for example: jdbc:mysql://localhost/sec_db for MySQL.
  • driverClass: This  is the JDBC driver class name, for example, com.mysql.jdbc.Driver
  • user: This is the database username.
  • password: This is the database user password.
  • groupsQuery: This is the SQL query used to import the groups. The original columns in the source table must be aliased using the labels: [GROUPNAME], [DESCRIPTION].
  • usersQuery: This is the SQL query import the users. The original columns in the source table must be aliased using the labels: [LOGINNAME], [EMAIL], [NAME], [LANGUAGE], [`COUNTRY],[TIMEZONE],[CALENDAR]`.
  • assignmentsQuery: This is the SQL query to get the groups/users assignments. The original columns in the source table must be aliased using the labels: [LOGINNAME], [GROUPNAME].
  • user.type: This is optional, and it could be one of the following: internal, sso (the default is internal).

If you use a database that is not supported by the server, edit the script file to include the path of the driverClass in the classpath.

All columns are mandatory in groupsQuery and assignmentsQuery. In usersQuery, the following columns are optional and the column order is not necessary:

  • [LANGUAGE]
  • [COUNTRY]
  • [TIMEZONE]
  • [CALENDAR]

Export users and groups from an LDAP Server

To export users from an LDAP Server, use the appropriate command according to your operating system.

Windows: dirExport -ldap ldap-config.properties [--debug]

Linux: ./dirExport.sh -ldap ldap-config.properties [--debug]

The [--debug] flag enables debugging mode.

Define the following properties in the ldap-config.properties file:

  • ldap.base.provider.url: The address of the directory server.
  • ldap.base.dn: The Distinguished Name to connect with while accessing the server.
  • ldap.user.dn: The Distinguished Name of the user in LDAP to authenticate.
  • ldap.user.dn.password: The password for the authentication user.
  • ldap.user.mapping.login: Maps the login name of the Incorta Analytics user.
  • ldap.user.mapping.name: Maps the name of the Incorta Analytics user.
  • ldap.user.mapping.mail: Maps the mail of the Incorta Analytics user.
  • ldap.group.mapping.name: Maps the name of the Incorta group.
  • ldap.group.mapping.member: Maps the users in the LDAP group.
  • ldap.user.search.filter: This is used to look for users (filter).
  • ldap.group.search.filter: This is used to look for groups (fiter).
  • user.type: (Optional) One of internal, SSO, or LDAP. Default is LDAP

© Incorta, Inc. All Rights Reserved.