LDAP (Active Directory) Authentication Connector

JVM AGENT

Overview

Seeq supports authentication via LDAP. Most commonly this is Microsoft Active Directory. Configuration is required to enable this mode of authentication.

Once the LDAP connector is configured you will be able to log into Seeq using your DOMAIN\user or [email protected] style LDAP credentials. Please note that a user must consistently use one or the other format or Seeq will treat the two as different users.

Prerequisites

There are no prerequisites for the LDAP Auth connector.

Configuration

This is an example configuration template that is displayed in the Additional Configuration box that appears when you click Configure for an existing datasource (or if a new datasource is being created, in the Create new datasource connection modal that appears after clicking Add Datasource) on the Datasources administration page.

CODE

{
    "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,
    "IdentitySynchronization" : {
      "Enabled" : false,
      "GroupsToSync" : null,
      "GroupFilter" : null,
      "GroupNamePrefix" : null
    }
}

LDAP Auth Additional Configuration

Property Name	Default Value	Data Type	Description
`Hostname`	`ad.example.com`	String	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`	`389`	Integer	The AD domain controller port, most likely 389 for LDAP or 636 for LDAPS.
`BaseDn`	null	String	An optional field that can be used 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`	null	String	An optional field 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 for`BaseDn`.
`Filter`	null	String	An optional that can be used 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`	null	List of Strings	An optional field that can 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`	null	String	An 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`	null	String	An 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, this field is mandatory.
`LdapSearchPassword`	null	String/SecretFile	This field is the password that is used to log into the Active Directory domain controller. If set to "null", Seeq will log in using the currently logged in credentials. When IdentitySynchronization is enabled, the field is mandatory.
`UseLdaps`	false	Boolean	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.
`UseStartTls`	false	Boolean
`VerboseLogging`	false	Boolean	Set to true to log successful authentications. When false, only authentication failures are logged. May be set to true also log the skipped groups in the identity synchronization process.
`GroupNameAttribute`	`samaccountname`	String	The LDAP attribute used for the group name in Seeq.
`UserNameAttribute`	`name`	String	The LDAP attribute used for the user name in Seeq.
`UserNameFallbackAttribute`	`samaccountname`	String	The LDAP attribute used for the user name in Seeq if the attribute specified in UserNameAttribute is not found.
`UserFirstNameAttribute`	`givenName`	String	The LDAP attribute used for the first name of the user in Seeq.
`UserLastNameAttribute`	`sn`	String	The LDAP attribute used for the last name of the user in Seeq.
`UserEmailAttribute`	`mail`	String	The LDAP attribute used for the user email in Seeq.
`PublicKeyCertPemLocation`	null	String	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: 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. 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") 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.
`JavaKeyStoreLocation`	null	String
`JavaKeyStorePassword`	null	String/SecretFile
`IdentitySynchronization`	null	A IdentitySynchronizationDefinition	This field contains Identity Synchronization configuration information.

IdentitySynchronizationDefinition Configuration

Property Name	Default Value	Data Type	Description
`Enabled`	false	Boolean	Whether to enable synchronization of groups.
`GroupsToSync`	`389`	Integer	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`	null	String	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`	null	String	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.

Examples

Default Examples

The default LDAP configuration file contains two example connections. 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:

CODE

{
   "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.

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.

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:

JS

    "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\":

CODE

    "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"

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

Think of Example One as "Hello World" for LDAP. We recommend using Example One, ensuring it works, then (if needed by your organization) trying to narrow things down using Example Two.

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.

JS

{
  "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"
  } ]
}

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

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.

JS

{
  "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

JS

{
  "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.

JS

{
  "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" ],
  } ]
}

Known Issues

There are no known issues for the LDAP Auth connector. Please report any issues you find to our support portal.

Troubleshooting

If you are running into issues with connecting to or access data from the NOAA Weather Service, view our guide for troubleshooting datasource issues.

Performance considerations

The LDAP Auth connector does not have any special performance considerations. View our guide to optimizing datasource performance for general guidance.