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.
{
"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 |
---|---|---|---|
|
| String | The hostname of the Active Directory domain controller, e.g.
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. |
|
| Integer | The AD domain controller port, most likely 389 for LDAP or 636 for LDAPS. |
| 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:
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. |
| null | String | An optional field similar to |
| 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:
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:
|
| 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. |
| 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). |
| 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. |
| 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. |
| 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. |
| false | Boolean | |
| 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. |
|
| String | The LDAP attribute used for the group name in Seeq. |
|
| String | The LDAP attribute used for the user name in Seeq. |
|
| String | The LDAP attribute used for the user name in Seeq if the attribute specified in UserNameAttribute is not found. |
|
| String | The LDAP attribute used for the first name of the user in Seeq. |
|
| String | The LDAP attribute used for the last name of the user in Seeq. |
|
| String | The LDAP attribute used for the user email in Seeq. |
| 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:
|
| null | String | |
| null | String/SecretFile | |
| null | A IdentitySynchronizationDefinition | This field contains Identity Synchronization configuration information. |
IdentitySynchronizationDefinition Configuration
Property Name | Default Value | Data Type | Description |
---|---|---|---|
| false | Boolean | Whether to enable synchronization of groups. |
|
| 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. |
| 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. |
| 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:
{
"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:
"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\":
"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.
{
"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.
{
"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
{
"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.
{
"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.