Configure LDAP

The Incorta Direct Data Platform supports the Lightweight Directory Access Protocol (LDAP) 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:

Go to the <installation_path>/IncortaNode/bin directory, and open the file ldap-config.properties.
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.

Edit the ldap.properties file.
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 -clnm <CLUSTER_NAME> --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 Super User privilege and is accessed using the Incorta Analytic Services 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 Super User 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 Direct Data Platform user.
ldap.user.mapping.name: Maps the name of the Incorta Direct Data Platform user.
ldap.user.mapping.mail: Maps the mail of the Incorta Direct Data Platform 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 (filter).
user.type: (Optional) One of internal, SSO, or LDAP. Default is LDAP