LDAP authentication and user directory settings

The following information is required to set up LDAP authentication and user directory mode, including LDAP group synchronization. Contact the LDAP directory administrator if you do not have the required information.

The following table provides an overview of LDAP settings and their applicability. Detailed descriptions of the settings are provided below the table.

A: Applicable to LDAP as authentication mechanism
UD: Applicable to LDAP User Directory mode
GS: Applicable to LDAP User Directory mode with group synchronization
M: Mandatory
**: Required by configurations with LDAP server type Custom. These options have template values for the non-predefined LDAP server types. The template values can be overridden when necessary.


A			Authentication Attribute Specifies the name of the LDAP attribute containing a user identity that can be used for authenticating with the LDAP server.
A	UD	M	LDAP Server Type Specifies the type of LDAP server: ActiveDirectory, SunOne, SunJavaSystem, or Custom.
A	UD	M	LDAP Server URLs A white-space separated list of LDAP server URLs.
A	UD	M	Context Names A list of distinguished names (DNs) of the containers holding the user accounts to be visible within Spotfire Server.
A	UD		Username The name of the LDAP service account to be used when searching for users and groups in the LDAP directory.
A	UD		Password The password for the LDAP service account.
A	UD		Security Authentication Specifies the security level to use when binding to the LDAP server. The default value is simple.
A	UD	**	User Search Filter Specifies an LDAP search expression filter to be used when searching for users.
A	UD		Referral Mode Specifies how LDAP referrals should be handled.
A	UD	**	Username Attribute Specifies the name of the LDAP attribute containing the user account names.
A	UD		Custom LDAP Properties Multiple key-value pairs specifying additional JNDI environment properties to be used when connecting to the LDAP server.
	UD		Request Control Specifies the type of LDAP controls to be used when executing search queries to the LDAP server: Probe, PagedResultsControl, VirtualListViewControl or none.
	UD		Page Size Specifies the page size to be used with the paged results control or the virtual list view control when performing search queries to the LDAP server. The page size value defaults to 1000 for both the paged results control and the virtual list view control.
	UD		Import Limit Specifies a threshold that limits the number of users that can be imported from an LDAP server to Spotfire Server in one query.
	UD		Synchronization Schedules Specifies a list of schedules for when the synchronization task should be performed.
	GS		Group Synchronization Enabled Specifies whether or not group synchronization should be enabled for this LDAP configuration.
	GS		Group Names Specifies a list of distinguished names (DNs) of either individual groups to be synchronized or a context name where all groups are to be synchronized. If the group synchronization enabled option is set and the list of group names is empty, then all groups that can be found in the LDAP directory will be synchronized.
	GS	**	Group Search Filter Specifies an LDAP search expression filter to be used when searching for groups.
	GS	**	Group Name Attribute Specifies the name of the LDAP attribute containing the group account names
	GS	**	Supports memberOf Specifies whether or not the LDAP servers support a memberOf-like attribute on the user accounts that contain the names of the groups or roles that the users are members of. In general, this is true for all Microsoft Active Directory servers and all types of Sun directory servers.
	GS	**	Member Attribute For all LDAP servers with support for a memberOf-like attribute, this option specifies the name of the LDAP attribute on the user account that contains the names of the groups or roles that the user is a member of.
	GS	**	Ignore Member Groups Specifies whether or not the group synchronization mechanism should recursively traverse the synchronized groups' non-synchronized subgroups and include their members in the search result.

Authentication Attribute

Specifies the name of the LDAP attribute containing a user identity that can be used for authenticating with the LDAP server. This attribute fills no purpose in most common LDAP configurations, but can be useful in more advanced setups where the distinguished name (DN) does not work for authentication or where users should be able to log in using a username that does not map directly to an actual LDAP account. A typical case for using this option is when setting up SASL; see SASL authentication for LDAP.

LDAP Server Type

Specifies the type of LDAP server. There are four valid types: ActiveDirectory, SunOne, SunJavaSystem, and Custom.

When specifying one of the predefined server types, we will assume that default values will be applied for the most fundamental configuration options. It is possible to override the default values. When specifying a Custom LDAP server type, there is no configuration template and all fundamental configuration options must be specified explicitly. The table above shows which configuration options are required for a Custom LDAP server type.

LDAP Server URLs

A whitespace-separated list of LDAP server URLs. An LDAP server URL has the format <protocol>://<server>[:<port>]

<protocol>: Either LDAP or LDAPS
<server>: The fully qualified DNS name of the LDAP server
<port>: An optional number indicating the TCP port the LDAP service is listening on. When using the LDAP protocol, the port number defaults to 389. When using the LDAPS protocol, the port number defaults to 636. Active Directory LDAP servers also provide a Global Catalog containing forest-wide information, instead of domain-wide information only. The Global Catalog LDAP service by default listens on port number 3268 (LDAP) or 3269 (LDAPS).

Spotfire Server does not expect any search base, scope, filter, or other additional parameters after the port number in the LDAP server URLs. Such properties are specified using other configuration options for this command.

Examples of LDAP server URLs:

LDAP://myserver.example.com

LDAPS://myserver.example.com

LDAP://myserver.example.com:389

LDAPS://myserver.example.com:636

LDAP://myserver.example.com:3268

LDAPS://myserver.example.com:3269

Context Names

A list of distinguished names (DNs) of the containers holding the LDAP accounts to be visible within Spotfire Server. When specifying more than one DN, the DNs must be separated by pipe characters (|). If the specified containers contain a large number of users, but only a few should be visible in Spotfire Server, a custom user search filter can be specified to include only the filtered users; see "User Search Filter", below.

Username

The name of the LDAP service account to be used when searching for users and groups in the LDAP directory. This service account does not need to have any write permissions, but it needs to have read permissions for all configured context names (LDAP containers). For most LDAP servers, the account name is the account's distinguished name (DN). For Active Directory, the account name can also be specified in the forms ntdomain\name or name@dnsdomain.

Examples:

CN=spotsvc,OU=services,DC=research,DC=example,dc=COM

RESEARCH\spotsvc (Active Directory only)

spotsvc@research.example.com (Active Directory only)

Password

The password for the LDAP service account.

Security Authentication

Specifies the security level to use when binding to the LDAP server. The default value is simple. Only use this parameter in special cases, and use it with care in production environments.

To enable anonymous binding, it should be set to none.
To enable plain user name/password authentication, it should be set to simple.
To enable SASL authentication, it should be set to the name of the SASL mechanism to be used. Spotfire Server supports the two SASL mechanisms DIGEST‐MD5 and GSSAPI. You can set multiple ‐C flags to set the additional JNDI environment properties that the SASL authentication mechanism typically requires

A typical case for using this option is when setting up SASL; see SASL authentication for LDAP.

User Search Filter

This parameter specifies an LDAP search expression filter to be used when searching for users.

If only a subset of all the users in the specified LDAP containers should be allowed access to Spotfire Server, a restrictive user search filter can be specified. For instance, the search expression can be configured so that it puts restrictions on which groups the users belong to, or which roles they have.

For Active Directory servers, the parameter value defaults to objectClass=user
For Active Directory servers, access can be restricted to only those users belonging to a certain group by using a search expression with the pattern &(objectClass=user)(memberOf=<groupDN>) where <groupDN> is to be replaced by the real DN of the group to which the users must belong. If the users are divided among multiple groups, use the pattern &(objectClass=user)(|(memberOf=<firstDN> )(memberOf=<secondDN>)). Add extra (memberOf=<groupDN>) sub-expressions as needed.
Example: &(objectClass=person)(isMemberOf=cn=project‐x,dc=example,dc=com)
For any version of the Sun Directory Servers, it defaults to objectClass=person.
For a Sun Java System Directory Server version 6 and later, the same effect can be achieved by using a search expression with the pattern &(objectClass= person)(isMemberOf=<groupDN>). If the users are divided among multiple groups, use the pattern &(objectClass=person)(|(isMemberOf=<firstDN> )(isMemberOf=<secondDN>)). Add extra (isMemberOf=<groupDN>) sub-expressions as needed.
Example: &(objectClass=person)(isMemberOf=cn=project‐x,dc=example,dc=com)
For the Directory Server product family, access can be restricted to only those users having certain specific roles. The search expression for role filtering must match the pattern &(objectClass=person)(nsRole=<roleDN>). If multiple roles are of interest, use the pattern &(objectClass=person)(|(nsRole=<firstDN>))(nsRole=<secondDN>) ). Add extra (nsRole=<roleDN>)) sub-expressions as needed.
Example: &(objectClass=person)(isMemberOf=cn=project‐x,dc=example,dc=com)

The syntax of LDAP search expression filters is specified by RFC 4515. Consult this specification for information about more advanced filters.

Referral Mode

This argument specifies how LDAP referrals should be handled. Valid arguments are follow (automatically follow any referrals), ignore (ignore referrals) and throw (fail with an error). The default and recommended value is follow.

Username Attribute

Specifies the name of the LDAP attribute containing the user account names. For Active Directory servers the value defaults to sAMAccountName. For the Directory Server product family with a default configuration, it defaults to uid.

Custom LDAP Properties

Multiple key-value pairs specifying additional JNDI environment properties to be used when connecting to the LDAP server. For instance, specifying the key java.naming.security.authentication and the value simple have the same result as setting the Security Authentication option to "simple".

Request Control

This option determines the type of LDAP controls to be used when executing search queries to the LDAP server. Valid controls are Probe, PagedResultsControl, VirtualListViewControl, and none.

The default behavior is to probe the LDAP server for the best supported request control. The paged results control is always preferred, since it provides the most efficient way of retrieving the result of the query. The virtual list view control can also be used to retrieve a large number of users, if the paged results control is not supported. The virtual list view control will automatically be used together with a sort control. Both the paged results control and the virtual list view control support a configurable page size, as specified by the page size option.

Page Size

This argument specifies the page size to be used with the paged results control or the virtual list view control when performing search queries to the LDAP server. The page size value defaults to 1000 for both the paged results control and the virtual list view control.

Import Limit

This argument specifies a threshold that limits the number of users that can be imported from an LDAP server to Spotfire Server in one query. This can be used to prevent accidental flooding of Spotfire Server's User Directory when integrating with an LDAP server with tens or even hundreds of thousands of users. By setting an import limit, the administrator can be sure that an unexpected high number of users won't affect the server's performance. By default, there is no import limit. To explicitly request unlimited import, set the parameter value to ‐1. All positive numbers are treated as an import limit. Leave this parameter untouched. in most cases.

Group Synchronization Enabled

Specifies whether or not group synchronization should be enabled for this LDAP configuration.

Group Names

Specifies the groups to be synchronized. Groups can be specified with either their account names or their distinguished names (DNs). The account names and the distinguished names may contain an asterisk (*) as a wildcard character. This wildcard behaves just like the asterisk wildcard in standard LDAP search filters. Wildcards work for both account names and distinguished names.

It is also possible to specify the distinguished name of an LDAP container containing multiple groups and thereby synchronizing all those groups. Wildcards can also be used for specifying group containers.

It is possible to mix all variants above. Consider the following when specifying a group to be synchronized:

Specify either the group's account name or its distinguished name (DN). The account name must match the value of the configured group name attribute.
It is possible to use an asterisk (*) as a wildcard character s in the account names when specifying group names. If a configured group name contains wildcard characters and matches multiple groups in the directory, all those groups will be synchronized.
It is also possible to specify the distinguished name of an LDAP container containing one or more groups. All those groups will then be synchronized.
It is possible to mix all variants.

Note: If the enable group synchronization configuration property is set and the list of group names is empty, then all groups that can be found in the configured context names in the LDAP directory will be synchronized.

Synchronization Schedules

Specifies a list of schedules for when the group synchronization task should be performed. The schedules are specified in the cron format, where each schedule consists of either five fields or one shorthand label.

The five fields are, from left to right, with their valid ranges:

minute (0‐59)
hour (0‐23)
day of month (1‐31)
month (1‐12)
day of week (0‐7, where both 0 and 7 indicate Sunday)

A field may also be configured with the wildcard character (*), indicating that any moment in time matches this field. A group synchronization is triggered when all fields match the current time. If both day of month and day of week have non-wildcard values, then only one of them has to match.

There are also the following shorthand labels that can be used instead of the full cron expressions:

@yearly or @annually: run once a year (equivalent to 0 0 1 1 *)

@monthly: run once a month (equivalent to 0 0 1 * *)

@weekly: run once a week (equivalent to 0 0 * * 0)

@daily or @midnight: run once a day (equivalent to 0 0 * * *)

@hourly: run once an hour (equivalent to 0 * * * *)

@minutely: run once a minute (equivalent to * * * * *)

@reboot or @restart: run every time Spotfire Server is started

Refer to the Wikipedia overview article on the cron scheduler.

Group Search Filter

This parameter specifies an LDAP search expression filter to be used when searching for groups.

For Active Directory servers, the parameter value defaults to objectClass=group
For Oracle Directory Servers and Sun Java System Directory Servers, it defaults to objectClass=groupOfUniqueNames
For Sun ONE Directory Servers, it defaults to &(|(objectclass= nsManagedRoleDefinition)(objectClass=nsNestedRoleDefinition))(objectclass= ldapSubEntry)

Group Name Attribute

Specifies the name of the LDAP attribute containing the group account names:

For Active Directory servers the value defaults to sAMAccountName
For any version of the Sun directory servers with a default configuration, it defaults to cn

Supports memberOf

Specifies whether or not the LDAP servers support a memberOf-like attribute on the user accounts that contain the names of the groups or roles that the users are members of. In general, this is true for all Microsoft Active Directory servers and the Directory Server product family.

For some LDAP servers with configurations of type Custom, there is no memberOf-like attribute. This is declared by setting the supports memberOf configuration property to "false".

Member Attribute

This parameter value can be set to: memberOf, nsRole, or isMemberOf.

For LDAP configurations with the supports memberOf option set to false, the member attribute option specifies the name of the LDAP attribute on the group accounts that contains the distinguished names (DNs) of its members. In general, this includes LDAP servers with configurations of type Custom and any Sun ONE Directory Servers (version 5 and earlier) when used with group-based synchronization.

For LDAP configurations with the supports memberOf option set to "true", the member attribute option specifies the name of the LDAP attribute on the user accounts that contain the names of the groups or roles that the users are members of. In general, this includes all Microsoft Active Directory servers and all types of Sun Directory Servers version 6 and later. For Sun ONE Directory Servers (version 5 and older), this also applies for roles.

For Microsoft Active Directory servers, the member attribute value defaults to memberOf.
For Sun ONE Directory Servers, the member attribute option defaults to nsRole.
For Sun Java System Directory Server version 6.0 or later, the member attribute option defaults to isMemberOf. To use the roles with the Sun Java System Directory Server or later, it is recommended to use the SunONE configuration template instead.

Note: All configurations with the memberOf option set to "false" will use a far less efficient group synchronization algorithm that will generate more traffic to the LDAP servers, because Spotfire Server will first have to search for the distinguished names (DNs) of the group members within the groups, and then perform repeated lookups to translate the member DN to the correct account name.

Ignore Member Groups

This argument determines whether or not the group synchronization mechanism should recursively traverse the synchronized groups' non-synchronized subgroups and include their members in the search result.

For Microsoft Active Directory servers, the parameter value defaults to "false" so that all inherited group memberships are correctly reflected. For any version of the Sun Directory Servers, it defaults to "true" because the role and groups mechanisms in those servers automatically include those members.