LDAP (Active Directory) Authentication Connector

Overview

Configuration

Starting with Seeq Server version R54, connector configuration JSON files do not need to be updated manually on the machine running the agent and can instead be managed through the administration page. In the datasources tab, select the datasource of interest and click “Manage” for the associated connection card.

Configuration is done by modifying the file ProgramData\Seeq\data\configuration\link\LDAP Connector.json. Navigate to the file and open it with a text editor such as Notepad.exe. As installed, the contents of the file looks like this :

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 { "Version" : "com.seeq.link.connectors.ldap.config.LdapConnectorConfigV1", "Connections" : [ { "Name" : "LDAP: all users have access to Seeq", "Id" : "00515700-a5ed-4d95-996d-396dd7ad899f", "Enabled" : false, "Transforms" : null, "VerboseLogging" : false, "KerberosKeytabLocation" : null, "KerberosServicePrincipal" : null, "Hostname" : "ad.example.com", "Port" : 389, "BaseDn" : null, "BaseDnForGroups" : null, "Filter" : null, "GroupsOfUserQuery" : "(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={dn}))", "AllowGroups" : null, "LdapSearchUsername" : null, "LdapSearchPassword" : null, "UseLdaps" : false, "UseStartTls" : false, "JavaKeyStoreLocation" : null, "JavaKeyStorePassword" : null, "PublicKeyCertPemLocation" : null, "Indexing" : { "Frequency" : "1w", "OnStartupAndConfigChange" : true, "Next" : "2019-06-11T11:47:44.781Z[UTC]" }, "IdentitySynchronization" : { "Enabled" : false, "GroupsToSync" : null, "GroupFilter" : null, "GroupNamePrefix" : null } }, { "Name" : "LDAP: members of 'Seeq ApprovedUsers' have access to Seeq", "Id" : "8d4f0b4c-1c7f-41cc-ae1e-b2815bc555c3", "Enabled" : false, "Transforms" : null, "VerboseLogging" : false, "KerberosKeytabLocation" : null, "KerberosServicePrincipal" : null, "Hostname" : "ad.example.com", "Port" : 389, "BaseDn" : "cn=Users,dc=example,dc=com", "BaseDnForGroups" : null, "Filter" : "(&(objectCategory=person)(objectClass=user)(memberOf=cn=Seeq ApprovedUsers,dc=example,dc=com))", "GroupsOfUserQuery" : "(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={dn}))", "AllowGroups" : null, "LdapSearchUsername" : null, "LdapSearchPassword" : null, "UseLdaps" : false, "UseStartTls" : false, "JavaKeyStoreLocation" : null, "JavaKeyStorePassword" : null, "PublicKeyCertPemLocation" : null, "GroupNameAttribute" : "samaccountname", "UserNameAttribute" : "name", "UserNameFallbackAttribute" : "samaccountname", "UserFirstNameAttribute" : "givenName", "UserLastNameAttribute" : "sn", "UserEmailAttribute" : "mail", "Indexing" : { "Frequency" : "1w", "OnStartupAndConfigChange" : true, "Next" : "2019-06-11T11:47:44.782Z[UTC]" }, "IdentitySynchronization" : { "Enabled" : false, "GroupsToSync" : null, "GroupFilter" : null, "GroupNamePrefix" : null } } ], "Help" : "For examples and documentation, see https://seeq12.atlassian.net/wiki/spaces/KB/pages/112822971" }

Note: Starting with Seeq Server version R54, scheduling must be configured in datasource administration page. In the Datasources tab of the administration page, select the datasource and click “Manage”. Note that any updates to the Indexing section of the connector JSON file will be ignored.

Note: Prior R22.0.45.00 the following fields will not be present in the configuration file: GroupsOfUserQuery, AllowGroups, Indexing, IdentitySynchronization, GroupNameAttribute, UserNameAttribute, UserNameFallbackAttribute, UserFirstNameAttribute, UserLastNameAttribute, UserEmailAttribute.

The default LDAP configuration file contains two example connections which are both disabled. The first example connection contains a minimal configuration where all users from LDAP will have access to Seeq. The second example connection contains a configuration where only members of 'Seeq ApprovedUsers' are allowed to enter Seeq. The example connections uses port 389 and no encryption. Using such a connection is the easiest way to set up a Seeq LDAP connection. However, for a production installation, we recommend using either the LDAPS protocol (most common, typically uses port 636) or StartTLS, both of which uses TLS encryption to protect the integrity and security of the connection between Seeq and the LDAP server. 

The following is an example from a Seeq test system based on R21.0.42.00:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 {  "Version" : "com.seeq.link.connectors.ldap.config.LdapConnectorConfigV1",  "Connections" : [ {    "Id" : "1ccddb80-f67e-456e-8da0-9a022f2cf33d",    "Enabled" : true,    "Hostname" : "ec2-255-255-255-255.us-west-2.compute.amazonaws.com",    "Port" : 389,    "Name" : "SeeqPIAF users with access to Seeq 1",    "BaseDn" : "cn=Users,dc=SeeqPiaf,dc=local",    "Filter" : "(&(objectCategory=person)(objectClass=user)(memberOf=cn=Seequsers, cn=Users,dc=SeeqPiaf,dc=local))", "LdapSearchUsername" : null, "LdapSearchPassword" : null,    "UseLdaps" : false,    "UseStartTls" : false, "VerboseLogging" : false,    "PublicKeyCertPemLocation" : null, "JavaKeyStoreLocation" : null, "JavaKeyStorePassword" : null  } ] }



The above example uses LDAP; LDAPS is disabled. Here are the setting changes made to the file:

  • “Enabled” is set to true

  • “Hostname” is set to the hostname of the ActiveDirectory server.

  • The "Name" field will be shown in the dropdown on the Seeq login page, so we update it to something meaningful.

  • “BaseDN”. SeeqPiAF.local is our domain and you can see we set the first dc (domain component) to SeeqPiaf and the second to local. You would do similar for your domain. The cn (common name) is set to Users; this is typical but may not be appropriate for your system.

  • “Filter”. We created a group called “Seequsers”. We added all users requiring access to Seeq to this group. You will likely need to work with your ActiveDirectory administer to get the correct settings here.

Consult the troubleshooting article for connectors for further guidance.

Starting with Seeq R22.0.45.00 additional filtering may be done using attribute AllowGroups. Instead of specifying a very complex LDAP filter, here we may specify a simple list of group names. When AllowGroups is set, only users being member of at least one of the listed groups are allowed to enter Seeq. 

Starting with Seeq R22.0.45.00 it is possible to use the LDAP connector also for eager synchronization of groups from LDAP into Seeq. As a result, the LDAP groups will be visible in Seeq and will be usable in definition of security for items in Seeq. Using GroupNameAttribute you can specify which LDAP attribute matches the group name in Seeq (by default it is set to "samaccountname" but in some configurations you may want to change this to "name").

The following JSON string is part of a configuration where eager synchronization is not enabled yet:

1 2 3 4 5 6 7 8 9 10 11 "Indexing" : { "Frequency" : "1w", "OnStartupAndConfigChange" : true, "Next" : "2019-06-18T11:58:58.818Z[UTC]" }, "IdentitySynchronization" : { "Enabled" : false, "GroupsToSync" : null, "GroupFilter" : null, "GroupNamePrefix" : null }

Here are the needed changes to make the eager synchronization start:

  • "IdentitySynchronization > Enabled" must be set to true

  • "IdentitySynchronization > GroupsToSync" must be set to a list of group names to be synchronized with Seeq.

  • "LdapSearchUsername" must be the LDAP user used by the connector (to read the groups listed in GroupsToSync)

  • "LdapSearchPassword" must be set to the password of the user specified in "LdapSearchUsername"

By default, a synchronization is made weekly but the interval may be changed using "Indexing > Frequency" field. 

It is possible to use property transforms on the user groups by setting them into "Transforms" property. Do not use "Transforms" to add the domain name to the user group name, use GroupNamePrefix instead.

To find out the groups to be synchronized, first the connector is making a LDAP query with the query specified in "GroupFilter". If not specified, all groups query is used: "(&(objectCategory=Group)(objectClass=group))". The entries returned by the query are further filtered to only the ones contained in "GroupsToSync" list.

Because LDAP server is not offering a possibility to extract the domain name for a given group, "GroupNamePrefix" may be used to prefix the group names with the domain in Seeq. See the configuration below where all the groups listed in GroupToSync will be prefixed with "SeeqPiaf\":

1 2 3 4 5 6 "IdentitySynchronization" : { "Enabled" : true, "GroupsToSync" : [ "SeeqUsers", "OaMSeeqGroup-A", "OaMSeeqGroup-A-1n111", "Test Group - Grandparent", "Test Group - Parent", "Test Group - Child", "Test Group - Grandchild" ], "GroupFilter" : null, "GroupNamePrefix" : "SeeqPiaf\\" }

In Seeq the groups will be created as "SeeqPiaf\SeeqUsers", "SeeqPiaf\OaMSeeqGroup-A", "SeeqPiaf\OaMSeeqGroup-A-1n111", "SeeqPiaf\Test Group - Grandparent", "SeeqPiaf\Test Group - Parent", "SeeqPiaf\Test Group - Child", "SeeqPiaf\Test Group - Grandchild"

Examples

Here are some examples you can use for guidance.  We recommend using Example One, ensuring it works, then (if needed by your organization) try to narrow things down using Example Two.

Think of Example One as "Hello World" for LDAP.  By using Example One (and inserting your AD domain name in the "Hostname" setting) you are validating that a user belongs to your AD domain only.  No groups or sub groups involved here, just ensuring they are valid in your AD domain.

Example #1: Minimal configuration, all LDAP users have access

1 2 3 4 5 6 7 8 9 10 { "Version" : "com.seeq.link.connectors.ldap.config.LdapConnectorConfigV1", "Connections" : [ { "Id" : "baaec9e7-8c8c-4cee-904a-06f1eac4f6ad", "Enabled" : true, "Hostname" : "ad-domain-controller.example.com", "Port" : 389, "Name" : "Minimal AD configuration" } ] }



Now Example #2 - here we try to specify a specific user group that will be allowed to access Seeq.  The user group is setup and managed via Active Directory.  Our LDAP connector is simply querying LDAP to see if the person attempting to log in is in the group specified in Active Directory.

Example #2: Added filtering, only users in group "Seeq Users" have access

1 2 3 4 5 6 7 8 9 10 11 12 { "Version" : "com.seeq.link.connectors.ldap.config.LdapConnectorConfigV1", "Connections" : [ { "Id" : "baaec9e7-8c8c-4cee-904a-06f1eac4f6ad", "Enabled" : true, "Hostname" : "ad-domain-controller.example.com", "Port" : 389, "Name" : "Filtered AD configuration", "BaseDn" : "cn=Users,dc=example,dc=com", "Filter" : "(&(objectCategory=person)(objectClass=user)(memberOf=cn=Seeq Users,dc=example,dc=com))" } ] }



Example #3: Added filtering, only direct or indirect members of "Seeq Groups" have access

1 2 3 4 5 6 7 8 9 10 11 12 { "Version" : "com.seeq.link.connectors.ldap.config.LdapConnectorConfigV1", "Connections" : [ { "Id" : "baaec9e7-8c8c-4cee-904a-06f1eac4f6ad", "Enabled" : true, "Hostname" : "ad-domain-controller.example.com", "Port" : 389, "Name" : "Filtered AD configuration", "BaseDn" : "cn=Users,dc=example,dc=com", "Filter" : "(&(objectCategory=person)(objectClass=user)(memberOf:1.2.840.113556.1.4.1941:=cn=Seeq Groups,dc=example,dc=com))" } ] }



Note

The 1.2.840.113556.1.4.1941: in example #3 above represents LDAP_MATCHING_RULE_IN_CHAIN which is a special extended match operator that walks the chain of ancestry in objects all the way to the root until it finds a match, which enables recursive belonging to groups.  See for more info: https://docs.microsoft.com/en-us/windows/desktop/adsi/search-filter-syntax

Example #4: Added more filtering, not all direct or indirect members of "Seeq Groups" have access but only the ones being part of group "SeeqUsers" or "Test Group - Grandparent" directly or indirectly.

1 2 3 4 5 6 7 8 9 10 11 12 13 { "Version" : "com.seeq.link.connectors.ldap.config.LdapConnectorConfigV1", "Connections" : [ { "Id" : "baaec9e7-8c8c-4cee-904a-06f1eac4f6ad", "Enabled" : true, "Hostname" : "ad-domain-controller.example.com", "Port" : 389, "Name" : "Filtered AD configuration", "BaseDn" : "cn=Users,dc=example,dc=com", "Filter" : "(&(objectCategory=person)(objectClass=user)(memberOf:1.2.840.113556.1.4.1941:=cn=Seeq Groups,dc=example,dc=com))", "AllowGroups" : [ "SeeqUsers", "Test Group - Grandparent" ], } ] }



Connector Settings

The following table describes all the available key settings.

Config Key

Optional?

Notes

Version

Required

Users should not modify this config setting. Keep the same value as the generated examples.

Id

Required

Must be a unique string. A UUID is recommended - you may generate one with a tool like https://www.uuidgenerator.net/version4.



Once you choose the "Id" for an LDAP connector and some users have logged in, do not change it! If you change the "Id", Seeq will treat it as an entirely separate LDAP server, so any users that log in would not have access to their existing work.

You may freely change the other configuration options without affecting the mapping between LDAP and Seeq users.



Enabled

Required

Whether to use this connector config. Possible values: true, false. Do not use quotes!

Hostname

Required

The hostname of the Active Directory domain controller, e.g.

"some-ec2-machine.us-west-2.compute.amazonaws.com"

Do not include any protocol prefix or TCP port suffix. The LDAP Connector must be installed on a machine that has a network path to this host.

Port

Required

The AD domain controller port, most likely 389 for LDAP or 636 for LDAPS.

Name

Required

A friendly name to show in the dropdown on the user login page.

BaseDn

Optional

For limiting access to Seeq to a specific group of users, provide a base distinguished name under which all users reside in the LDAP system. The value should be something similar to:

"cn=Users,dc=example,dc=com"

Note: When you provide a BaseDn config value, you must also provide a Filter config value. Note: Starting with R22.0.45.00 the filter becomes optional and defaults automatically to "(&(objectCategory=person)(objectClass=user))".

BaseDn is mandatory to be provided when IdentitySynchronization is enabled.

BaseDnForGroups

Optional

Similar to BaseDn but applied only to search for LDAP User Groups. This is particularly helpful for clients with large LDAP trees that have modeled their Groups in a different Organizational Unit than Users. If not specified, this configuration option is ignored and falls back to the value provided forBaseDn.

Filter

Optional

For limiting access to Seeq to a specific group of users, provide an LDAP search filter - in order to have access to Seeq a user will have to match the conditions in the filter.

An example looks like this:

"(&(objectCategory=person)(objectClass=user)
  (memberOf=cn=Seeq Approved Users,dc=example,dc=com))"

More examples of LDAP search filters can be found at

http://social.technet.microsoft.com/wiki/contents/articles/5392.active-directory-ldap-syntax-filters.aspx#Examples.

Note: When you provide a Filter config value, you must also provide a BaseDn config value.

Starting with R22.0.45.00 the filter becomes optional and defaults automatically to "(&(objectCategory=person)(objectClass=user))" when not provided.

The filter is used by LDAP Connector to load the user from LDAP by adding to it automatically one of:

  • sAMAccountName="username" if the provided user has the form "DOMAIN\username"

  • userPrincipalName="user@domain" if the provided user has the form of an email

AllowGroups

Optional

Available starting with release R22.0.45.00.

It may contain a list of group names. In order to be able to login a user has to be member of at least one of the provided groups. When null or empty, any user passing the Filter can login.

GroupsOfUserQuery

Optional

LDAP query to return all the groups of a given user recursively. For Microsoft Active Directory the query may be "(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={dn}))". When not provided, the query defaults to the Microsoft Active Directory query.

When AllowGroups is null and IdentitySynchronization is disabled, GroupsOfUserQuery can be changed to "(&(objectClass=group)(member={dn}))" to prevent the recursive search of groups that is very expensive. 

Later on, if AllowGroups becomes non null or IdentitySynchronization is enabled, GroupsOfUserQuery should be reset to the default value (by setting its value to null).



LdapSearchUsername

Optional

Username to log into the Active Directory domain controller as.  If set to "null", Seeq will log in using the currently logged in credentials.

When IdentitySynchronization is enabled, the field is mandatory.

LdapSearchPassword

Optional

Password to log into the Active Directory domain controller with.  If set to "null", Seeq will log in using the currently logged in credentials.

When IdentitySynchronization is enabled, the field is mandatory.

Starting with Seeq version 52, this field can be specified using an external secret file.

UseLdaps

Optional

For transport-layer security between the connector and AD, users may choose between two protocols, either LDAPS or StartTLS. LDAPS usually uses port 636 and is analogous to HTTPS. StartTLS usually uses port 389 and starts as an unencrypted LDAP connection but "upgrades" to TLS before transmitting sensitive data. Possible values: true, false. Do not use quotes!

UseStartTls

Optional

VerboseLogging

Optional

Set to true to log successful authentications. The default (false) logs only authentication failures. May be set to true also log the skipped groups in the identity synchronization process.

Transforms

Optional

Available starting with release R22.0.45.00.

Transform to be applied on users groups before sending them to Seeq. See Connector Property Transforms for more information.

GroupNameAttribute

Optional

Available starting with release R22.0.45.00.

LDAP attribute used for the group name in Seeq. The default is "samaccountname". 

UserNameAttribute

Optional

Available starting with release R22.0.45.00.

LDAP attribute used for the user name in Seeq. The default is "name". 

UserNameFallbackAttribute

Optional

Available starting with release R22.0.45.00.

LDAP attribute used for the user name in Seeq if the attribute specified in UserNameAttribute is not found.

UserFirstNameAttribute

Optional

Available starting with release R22.0.45.00.

LDAP attribute used for the first name of the user in Seeq. The default is "givenname". 

UserLastNameAttribute

Optional

Available starting with release R22.0.45.00.

LDAP attribute used for the last name of the user in Seeq. The default is "sn". 

UserEmailAttribute

Optional

Available starting with release R22.0.45.00.

LDAP attribute used for the user email in Seeq. The default is "email". 

PublicKeyCertPemLocation

Optional

For transport-layer security between the connector and AD, when using LDAPS or StartTLS, there are three possibilities for the TLS certificates that were trusted:

  1. The default (all of these options set to null) will use the certificates bundled with Java. Certificates that were verified with a major public certificate authority (Comodo, Symantec, GoDaddy, GlobalSign, LetsEncrypt, etc.) will be trusted.

  2. For a self-signed or internal certificate authority, use a PEM-format public key and provide the location of the file as PublicKeyCertPemLocation. Instructions for exporting the root certificate in Windows. Note: the backslashes in the path must be escaped (e.g. "c:\\temp\\seeqcert.pem")

  3. Alternatively, for a self-signed or internal certificate authority, provide a Java KeyStore in the same format as the "cacerts" file bundled in Java as JavaKeyStoreLocation. Provide the password as JavaKeyStorePassword.
    Starting with Seeq version 52, JavaKeyStorePassword can be specified using an external secret file.

JavaKeyStoreLocation

Optional

JavaKeyStorePassword

Optional



The following table describes all the available key settings for Identity Synchronization (available starting with release R22.0.45.00).

Config Key

Optional?

Notes

Config Key

Optional?

Notes

Enabled

Required

Whether to enable synchronization of groups. Possible values: true, false. Do not use quotes!

GroupsToSync

Optional

The groups to be sent to Seeq. The connector gets the groups from LDAP using GroupFilter and filters them out using GroupsToSync.

When the list of groups is not exactly known, VerboseLogging can be set and all the groups passing GroupFilter will be listed in the log.

GroupFilter

Optional

LDAP query to return the groups from LDAP. If not provided it defaults to "(&(objectCategory=Group)(objectClass=group))". From the returned groups, only the ones listed in GroupsToSync are sent to Seeq.

GroupNamePrefix

Optional

A string that will prefix all the group names sent to Seeq. Example: If GroupNamePrefix is set to "SeeqPiaf\\" a group name "ABC" from LDAP will become "SeeqPiaf\ABC" in Seeq.