create-ldap-config

Creates a new LDAP configuration for authentication and/or the user directory LDAP provider.

create-ldap-config 
[-c value | --configuration=value] 
[-b value |--bootstrap-config=value] 
<--id=value> 
[--discover] 
[-t value |--type=value] 
[-s value | --servers=value] 
[-n value |--context-names=value] 
[-u value | --username=value] 
[-p value |--password=value] 
[--schedules=value] 
[--user-search-filter=value]
[--user-name-attribute=value] 
[--authentication-attribute=value]
[--security-authentication=value] 
[--referral-mode=value]
[--referral-mode-root-dse=value]
[--request-control=value] 
[--page-size=value] 
[--import-limit=value]
[--user-display-name-attribute=value]
[--group-display-name-attribute=value] 
{-Ckey=value}
{-Rvalue}
{-Svalue}
[--connection-timeout=value] 
[--read-timeout=value]

Overview

Use this command to create a new LDAP configuration for authentication and/or user directory back-end.

Options


Option	Optional or Required	Default Value	Description
`-c value --configuration=value`	Optional	configuration.xml	The path to the server configuration file.
`-b value --bootstrap-config=value`	Optional	none	The path to the bootstrap configuration file. See Bootstrap.xml file for more information about this file.
`--id=value`	Required	none	Specifies the identifier for the LDAP configuration to be created.
`--discover`	Optional	none	Specifies whether to attempt to automatically create an LDAP configuration based on the information available from the DNS service. The discover mode works only when the desired LDAP server has registered SRV records in the DNS service used by the computer where this command is being invoked. This is typically the case for Active Directory LDAP servers. This argument is mutually exclusive with the `-t/ --type`, `-s/--servers`, and `-n/--context-names` arguments.
`-t value --type=value`	Required, unless the `--discover` option is used	none	The type of LDAP server. The following names are valid types: ActiveDirectory SunOne SunJavaSystem Custom If you specify any of the first three types, a type-specific configuration template is automatically applied in runtime, so that the most fundamental configuration options are automatically configured. If you specify a "Custom" LDAP server type, there is no such configuration template, and you must specify explicitly all the configuration options. When you use a custom LDAP configuration for authentication or with the User Directory LDAP provider, you must specify the arguments `--user-search-filter` and `--user-name-attribute`. If you use such an LDAP configuration for group synchronization, you must also specify additional parameters when running the config-ldap-group-sync command. See the help topic for that command for more information.
`-s value --servers=value`	Required, unless the `--discover` option is used	The LDAP protocol port number defaults to 389. The LDAPS protocol port number defaults to 636. Active Directory LDAP servers also provide a Global Catalog containing forest-wide information, instead of domain-wide information only. By default, the Global Catalog LDAP service listens on port number 3268 (LDAP) or 3269 (LDAPS).	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>`: Optional. Indicates the port number that the LDAP service is listening on. Spotfire Server does not expect 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: 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
`-n value --context-names=value`	Required, unless the `--discover` option is used	none	A list of distinguished names (DNs) of the containers holding the LDAP accounts to be visible within the Spotfire Server. When you specify more than one DN, you must separate the DNs using pipe characters (\|). If the specified containers contain a large number of users, of which only a few should be visible in Spotfire Server, you can specify a custom user search filter to include only the designated users (see the `--user-search-filter` argument). Examples: `CN=users,DC=example,DC=com` `OU=project-x,DC=research,DC=example,DC=com`
`-u value --username=value`	Required	none	The name of the LDAP service account to use when searching for users (and optionally also groups) in the LDAP server. This service account does not need to have write permissions, but it must 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` and `name@dnsdomain`. Examples: `CN=spotsvc,OU=services,DC=research,DC=example,dc=COM` `RESEARCH\spotsvc` (Note: Active Directory only) `spotsvc@research.example.com` (Note: Active Directory only)
`-p value --password=value`	Optional	none	The password for the LDAP service account.
`--schedules=value`	Optional	@daily, @restart	A comma-separated list of schedules for when the LDAP synchronization should be performed. The schedules are given in a cron-compatible format, where each schedule consists of either five fields or one shorthand label. Make sure you enclose the value in double quotes. 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) and day of week (0-7, where both 0 and 7 indicate Sunday). You can also configure a field with the wildcard character , indicating that any moment in time matches this field. An LDAP 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. You can also use following shorthand labels 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 the Spotfire Server is started Refer to the Wikipedia overview article on the cron scheduler.
`--user-search-filter=value`	Optional, but it must be specified for custom LDAP configurations, either when running this command or the update-ldap-config command.	For Active Directory servers, the parameter value defaults to '(&(objectClass=user)(!(objectClass=computer)))'. For any version of the Sun Directory Servers, it defaults to 'objectClass=person'.	Specifies an LDAP search expression filter to use when searching for users. If you need to identify a subset of users in the specified LDAP containers who should be allowed access to Spotfire Server, you can specify a more detailed user search filter. For example, the search expression can be expanded so that it also puts restrictions on which groups the users belong to, or which roles they have. 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 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. Active Directory example: `&(objectClass=person)(isMemberOf=cn=project-x,dc=example,dc=com)` For a Sun Java System Directory Server version 6 and later, you can achieve the same effect 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. Sun Java System Directory Server example: `&(objectClass=person)(isMemberOf=cn=project‐x,dc=example,dc=com)` For Sun ONE Directory Servers and newer Sun Java System Directory Servers or the older iPlanet Directory Server, you can restrict access 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=<roletDN>)` sub-expressions as needed. Sun ONE Directory Servers example: `&(objectClass=person)(isMemberOf=cn=project‐x,dc=example,dc=com)` The syntax of LDAP search expression filters is specified by the RFC 4515 document. Consult this documentation for information about more advanced filters.
`--user-name-attribute=value`	Optional, unless the LDAP server type is set to "Custom" using the `--type` parameter.	For Active Director servers, the value defaults to sAMAccountName. For a Sun Java System Directory Server or any older Sun ONE Directory Server or iPlanet Directory Server with a default configuration, it defaults to 'uid'.	Specifies the name of the LDAP attribute containing the user account names.
`--authentication-attribute=value`	Optional; use only for advanced setups. It is not set by default.	none	Specifies the name of the LDAP attribute containing a user identity that can be used for binding (authenticating) to the LDAP server. This attribute fills no purpose in most common LDAP configurations, but it 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. If you set up SASL with DIGEST-MD5 in an Active Directory environment, the DN does not work for authentication, and the `userPrincipalName` attribute must be used instead. The `--authentication-attribute` argument should then be set to "userPrincipalName" and the `--user-name-attribute` argument should be set to "sAMAccountName". (The latter value is the default value for an Active Directory LDAP configuration, so there is no need to set it explicitly.) See also the `--security-authentication` argument. When you set up SASL with GSSAPI in an Active Directory environment, the DN does not work for authentication and the sAMAccountName or userPrincipalName attribute must be used instead. The `--authentication-attribute` argument should be set to "sAMAccountName" or "userPrincipalName", and the `--user-name-attribute` argument should be set to "sAMAccountName". (The latter value is the default value for an Active Directory LDAP configuration, so there is no need to set it explicitly.) See also the `--security-authentication` argument. Example: If you set the `--user-name-attribute` argument to "cn" and the `--authentication-attribute` argument to "userPrincipalName" in an Active Directory environment, the users can log in to Spotfire Server using their CN attribute values, but underneath the hood, Spotfire Server actually uses the `userPrincipalName` attribute value of the LDAP account with the matching CN for the actual authentication.
`--security-authentication=value`	Optional; use only in advanced setups.	`simple`	Specifies the security level to use when binding to the LDAP server: To enable anonymous binding, it should be set to "none". To enable plain username/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, for instance "DIGEST‐MD5" or "GSSAPI". Use multiple `-C` arguments to set the additional JNDI environment properties that the SASL authentication mechanism typically requires. If you set up SASL with DIGEST-MD5 in an Active Directory environment, all accounts must use reversible encryption for their passwords. This is typically not the default setting for the domain controller. The `--authentication-attribute` argument must also be used to specify the `userPrincipalName` attribute for the actual authentication to work correctly. If you set up SASL with GSSAPI in an Active Directory environment, the `--authentication-attribute` argument must be used to specify either the `sAMAccountName` or the `userPrincipalName` attribute, and the custom property `kerberos.login.context.name` must be mapped to the JAAS application configuration `SpotfireGSSAPI`. This, in turn, requires a fully working Kerberos configuration file at <server installation dir>/tomcat/spotfire-config/krb5.conf.
`--referral-mode=value`	Optional	follow	Specifies how LDAP referrals should be handled. Valid arguments: follow (automatically follow any referrals). Recommended. ignore (ignore referrals) throw (fail with an error)
`[--referral-mode-root-dse=value]`	Optional	If not explicitly set, the value for `--referral-mode` is used.	Specifies how LDAP referrals should be handled when looking up the RootDSE. Valid arguments are: follow (automatically follow any referrals) ignore (ignore referrals) throw (fail with an error)
`--request-control=value`	Optional	probe	Determines the type of LDAP controls to be used for executing search queries to the LDAP server. The default behavior is to probe the LDAP server for the best supported request control. The paged results control is always preferred, because it provides the most efficient way of retrieving the query result set. You can use the virtual list view control for the same purpose if the paged results control is not supported. The virtual list view control is used automatically, together with a sort control. Both the paged results control and the virtual list view control support a configurable page size, set by the `--page-size` argument. To explicitly configure the server for probing, set the argument value to "probe". To configure the server for the paged results control, set the argument value to "PagedResultsControl". To request the virtual list view control, set the argument value to "VirtualListViewControl". To completely disable request controls, set the argument value to "none".
`--page-size=value`	Optional	2000 for both the paged results control and the virtual list view control.	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.
`--import-limit=value`	Optional	No 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. This can be used to prevent accidentally flooding the Spotfire user directory when you integrate with an LDAP server with tens or even hundreds of thousands of users. By setting an import limit, you can be sure that an unexpected high number of users will not affect server performance. To request unlimited import explicitly, set the parameter value to "-1". All positive numbers are treated as an import limit. For most cases it is recommended that you leave this parameter untouched.
`--user-display-name-attribute=value`	Optional	none	Specifies the name of the LDAP attribute containing the user display names.
`--group-display-name-attribute=value`	Optional	none	Specifies the name of the LDAP attribute containing the group display names.
`-Ckey=value`	Optional; can be specified multiple times with different keys.	none	Specifies additional JNDI environment properties to use when connecting to the LDAP server. Example: The equivalent of specifying the `--security-authentication=DIGEST-MD5` argument is `-Cjava.naming.security.authentication=DIGEST-MD5`.
`-Rvalue`	Optional; can be specified multiple times with different values.	If this argument is not specified, the Java defaults are used.	Specifies the protocols to be used for LDAPS when connecting to the LDAP server. Example: To enable only TLSv1.2 `> -RTLSv1.2`
`-Svalue`	Optional; can be specified multiple times with different values.	If this argument is not specified, the Java defaults are used.	Specifies the cipher suites to be used for LDAPS when connecting to the LDAP server. Example: To enable only these two cipher suites `> -STLS_DHE_RSA_WITH_AES_128_GCM_SHA256 -STLS_DHE_RSA_WITH_AES_256_GCM_SHA384`
`--connection-timeout=value`	Optional	No timeout (see description)	Specifies the connection timeout. The value must be a non-negative integer representing the timeout in milliseconds. A value less than or equal to zero results in no timeout, effectively waiting until the connection times out on the TCP network level.
`--read-timeout=value`	Optional	No timeout (see description)	Specifies the read timeout. The value must be a non-negative integer representing the timeout in milliseconds. A value less than or equal to zero results in no timeout, effectively waiting until the connection times out on TCP network level.

EXAMPLES

Create an LDAP configuration for Active Directory:

create-ldap-config --id="ldap1" --type="ActiveDirectory" 
  --servers="ldap://dc01.research.example.com:3268 ldap://dc02.research.example.com:3268" --context-names="OU=project-x,DC=research,DC=example,DC=com|OU=phbs,DC=management,DC=example,DC=com"
  --username="ldapadmin@research.example.com" --password="s3cr3t"
  --schedules="@daily"

Create an LDAP configuration for SunONE:

create-ldap-config --id="ldap1" --type="SunONE" 
  --servers="ldap://directory.research.example.com:389" --context-names="OU=project-x,DC=research,DC=example,DC=com|OU=phbs,DC=management,DC=example,DC=com"
  --username="ldapadmin" --password="s3cr3t"
  --schedules="@daily"

Create an LDAP configuration for Sun Java System Directory:

create-ldap-config --id="ldap1" --type="SunJavaSystem" 
  --servers="ldaps://directory.research.example.com:636" --context-names="OU=project-x,DC=research,DC=example,DC=com|OU=phbs,DC=management,DC=example,DC=com"
  --username="ldapadmin" --password="s3cr3t"
  --schedules="@daily"

Create an LDAP configuration for a custom LDAP server:

create-ldap-config --id="ldap1" --type="Custom" 
  --servers="ldap://directory.research.example.com" --context-names="OU=project-x,DC=research,DC=example,DC=com|OU=phbs,DC=management,DC=example,DC=com"
  --user-name-attribute="cn" --search-filter="&(objectClass=person)(isMemberOf=cn=projectX,dc=example,dc=com)"
  --username="ldapadmin" --password="s3cr3t"
  --schedules="@daily"

Create an LDAP configuration using the discover mode:

create-ldap-config --id="ldap1" --discover
  --username="ldapadmin@research.example.com" --password="s3cr3t"
  --schedules="@daily"