Contents
LDAP Configuration Options
This section describes the configuration options used to configure LDAP external authentication on Configuration Server and Configuration Server Proxy.
Setting Configuration Options
Unless otherwise specified, you set LDAP configuration options at any of the following locations:
- In the options of the Configuration Server or Configuration Server Proxy Application object
- In a distributed environment, in the annex of a Tenant object
- In the annex of individual Person objects
This will turn on external authentication for all users enabled with External IDs, or for all users if the enforce-external-auth option is set to true.
You can also fine-tune your LDAP configuration throughout your system by configuring some or all options in the annex of Tenant objects. Refer to Using LDAP in a Configuration with More Than One Tenant for more information.
Mandatory Options
The following table lists the options that are mandatory for LDAP external authentication on Configuration Server and Configuration Server Proxy. Both options are set automatically during the installation of Configuration Server and Configuration Server Proxy.
| Section | Option Name | Option Value |
|---|---|---|
| authentication | library | gauth_ldap |
| gauth_ldap | ldap-url | Valid URL of LDAP authentication module |
authentication Section
This section is mandatory on the Server level to enable external authentication. It can, however, appear in other locations as mentioned in Setting Configuration Options.
This section must be called authentication.
authentication-queue-threshold
Default Value: 1000
Valid Values: 0 or any positive integer
Changes Take Effect: Immediately
Specifies the number of login requests that can be enqueued in the LDAP authentication queue. When the number of login requests in the LDAP queue waiting to be sent to the LDAP server goes above the configured limit, the subsequent login requests are rejected with CFGForcedDisconnect error stating that request to LDAP server failed. Configuration Server will start accepting the LDAP request only after the queue size is reduced by 10% below the configured limit.
When set to 0 (zero), queue length will not be restricted and all the requests are added to the queue. The login requests expire based on the existing policies.
enforce-external-auth
Default Value: false
Valid Values: true, false
Changes Take Effect: Immediately
Optional. Enforces external authentication for every user. If you omit this parameter, LDAP AM performs authentication only if an External ID is specified in the Person object.
This option applies at the server level, and starting in release 8.5.1, also at the Tenant level.
If this option is configured at the server level as true in the database, but Configuration Server reads its configuration file and finds the option set to false, the value from the configuration file will override the value in the database, allowing all users of the Environment tenant to log in internally.
enforce-internal-auth
Default Value: false
Valid Values: true, false
Changes Take Effect: Immediately
Optional. Specifies if all users are to be authenticated internally.
This option is set in the options of the Application object. If set to true, all users are authenticated internally by Configuration Server or Configuration Server Proxy, regardless of having a value in the External ID field. If set to false (the default), only those users with a value in the External ID field are authenticated by the LDAP AM.
ldap-cache-time
Default Value: 0
Valid Values: 0 to 65536
Changes Take Effect: Immediately
Specifies the time interval, in seconds, during which Configuration Server caches the LDAP username and password after successful authentication of a user.
The cache is reset after the time specified by this option elapses. Also, the cache is reset when the Person object is changed or when any option is changed in the authentication or gauth_ldap section of the Configuration Server object.
When set to 0 (the default), this feature is disabled.
ldap-negative-cache-time
Default Value: 0
Valid Values: 0 to 65536
Changes Take Effect: Immediately
Specifies the time interval, in seconds, during which Configuration Server caches the username and password after unsuccessful authentication of a user. When a user enters incorrect login credentials multiple times, Configuration Server caches only the last invalid password entered for the LDAP user account.
The cache is reset after the time specified by this option elapses. Also, the cache is reset when the Person object is changed or when any option is changed in the authentication or gauth_ldap section of the Configuration Server object.
When set to 0 (the default), this feature is disabled.
library
Default Value: No default value
Valid Values: Depends on type configuration option, as follows:
| gauth_radius | All |
| gauth_ldap | All |
| gauth_radius, gauth_ldap | Configuration Server, Configuration Server Proxy |
| gauth_ldap, gauth_radius | Configuration Server, Configuration Server Proxy |
| internal | Tenant, Person |
Changes Take Effect: Upon restart of Configuration Server or Configuration Server Proxy; immediately for Tenants and Persons.
Specifies the section that specifies the external authentication parameters. This option is mandatory, and its value is set automatically during installation. If this Configuration Server or Configuration Server Proxy was previously configured for another type of authentication, such as RADIUS, you must manually add , gauth_ldap to the value of this option.
When set to internal, all users associated with the object in which the object is set to this value are validated internally.
gauth_ldap and gauth_ldap_<n> Sections
The gauth_ldap and gauth_ldap_<n> sections were added in release 8.1 to provide a more secure and easier method of configuring LDAP servers. They were designed to replace the legacy configuration structure and options (described in the table in Overriding the Defaults by Tenant). Instead of having all LDAP servers defined by sets of uniquely-named options in the authentication section, this new structure requires that each LDAP server be defined in its own section, making it easier to set up and maintain the configuration.
Configuration Server connects to the next LDAP server only if the connection fails and not when the LDAP URL responds with a message such as No user DN found. The expectation is that there is only one LDAP source and many servers to connect with it. Therefore, if a user is not found in gauth_ldap_1, then it is expected that the user is not be found in gauth_ldap_2, as well. Forced switching of the LDAP server is currently not supported by Configuration Server.
Each gauth_ldap and gauth_ldap_<n> section contains information about one LDAP Authentication Module. The gauth_ldap section is mandatory.
If you are using more than one LDAP Server, you must identify the rest in individual gauth_ldap_<n> sections. Configuration Server supports up to ten LDAP authorization servers, so you can have up to nine of these sections, one section for each additional LDAP server. The name of each section must be unique, and Genesys recommends that they be in the same order as they are indexed. Each section must be named gauth_ldap_<n>, where n is a numeric index in the range of 1 to 9 for each LDAP server, as follows:
[gauth_ldap_<n>]
ldap-url=<value>
app-user=<value>
password=<value>
cacert-path=<value>
cert-path=<value>
key-path=<value>
idle-timeout=<value>
retry_attempts=<value>
retry-interval=<value>
connect-timeout=<value>
chase-referrals=<value>
keepalive-enable=<value>
keepalive-time=<value>
keepalive-probes=<value>
keepalive-interval=<value>When you add a new section, it takes effect immediately. But if you remove a section, you must restart Configuration Server or Configuration Server Proxy to take the LDAP Server out of use.
LDAP Server Parameters
To define an LDAP server, set the parameters described in this section in the options of the object, in the gauth_ldap or gauth_ldap_<n> section, as appropriate.
ldap-url
Default Value: Empty string
Valid Value: URL in RFC 2255 format, as described below
Changes Take Effect: Immediately
This URL contains the information needed to access the LDAP server and directory from which it retrieves the user's distinguished name. Enter the URL of one LDAP server in this field.
The LDAP URL contains default settings that are common to all Users in the Genesys Configuration Database. However, these settings may be overridden if the User's record in the Configuration Database also contains an LDAP URL with access parameters. The priorities used to obey configuration parameters, from highest to lowest, are:
- LDAP URL in the user's record of the configuration database.
- LDAP URL specified in the authentication section of the Tenant’s Annex.
- LDAP URL in the configuration file (at first start only), or the Configuration Server or Configuration Server Proxy Application object.
- AM default parameters, which cannot be changed by the user.
The following is an example of an LDAP URL parsed into its parameters, followed by a table describing them. Note that the URL contains no spaces and is a single expression that must be entered on a single line.
| Parameter | Definition |
|---|---|
| 1 Protocol type | Required. Valid values: ldaps (SSL/TLS secure) or ldap (unsecure) |
| 2 LDAP server host name | Optional. Default is the local host; for example, fram.us.int.vcorp.com |
| 3 LDAP server port | Optional. The default (636 for a secure connection and 389 for unsecured) is used if you omit this parameter. Unsecure means a simpler configuration, but also presents a risk. Genesys strongly advises that you use a secure connection. |
| 4 Base DN | Required. Defines the node in the LDAP tree to use as base for the LDAP search; for example, ou=Engineering,o=vcorp,c=us |
| 5 Search scope | Optional. Default: sub. Defines the scope of the search operation (according to the RFC 2251 format).
Valid ValuesA: base, one, sub |
| 6 Search filter | Optional. Limits the search by searching for a match with a specified field. Default: empty string. In the example URL above, X is a parameter that will be substituted with the value of the user’s External ID. The filter expression must conform to the standard RFC 2251 format specification. Example:
(displayName=X) |
For examples of LDAP URLs, see Examples.
app-user
Default Value: Empty string
Valid Value: Valid path
Changes Take Effect: Immediately
Distinguished name (which includes location in the directory tree and in any containers) of the application account used by the LDAP AM to search for the User's information that is needed to authenticate the user. For an example of the app-user parameter for RACF, see gauth_ldap Section Using IBM RACF.
password
Default Value: Empty string
Valid Value: A valid password
Changes Take Effect: Immediately
Password of the application account; required if app-user is set. This password is masked by default in all logs.
cacert-path
Default Value: Empty string
Valid Value: Valid path
Changes Take Effect: Immediately
Full path to the file containing a certificate from a trusted Certificate Authority, which is used to negotiate a secure LDAP connection to the server. Required for a secure connection. Refer to Configuring Server Authentication for more information about using this option when configuring secure connections.
If mutual authentication is required on connections to LDAP servers, Configuration Server must be provisioned (using cacert-path and key-path) with the same local certificate that is accepted by all LDAP servers.
Genesys does not support specifying different client certificates (and/or certificate authority certificates), for different connections.cert-path
Default Value: Empty string
Valid Value: Valid path
Changes Take Effect: Immediately
Full path to the file containing a certificate for Configuration Server to connect to a remote LDAP Server that requires mutual authentication. Refer to Configuring Server Authentication for more information about using this option when configuring secure connections.
If mutual authentication is required on connections to LDAP servers, Configuration Server must be provisioned (using cacert-path and key-path) with the same local certificate that is accepted by all LDAP servers.
Genesys does not support specifying different client certificates (and/or certificate authority certificates), for different connections.key-path
Default Value: Empty string
Valid Values: Valid path
Changes Take Effect: Immediately
Full path to the file containing the key for the Configuration Server certificate specified by cert-path. Refer to Configuring Server Authentication for more information about using this option when configuring secure connections.
If mutual authentication is required on connections to LDAP servers, Configuration Server must be provisioned (using cacert-path) with the same local certificate that is accepted by all LDAP servers.
Genesys does not support specifying different client certificates (and/or certificate authority certificates), for different connections.idle-timeout
Default Value: 0
Valid Values: 0 to MAX_INTEGER
Changes Take Effect: Immediately
Defines how long (in seconds) the LDAP connection to the server defined in this section will be kept open if there are no more requests to send. When set to zero (0), this connection will be kept open indefinitely. Genesys recommends that it be set to a value that does not exceed the idle timeout of the LDAP server.
retry-attempts
Default Value: 3
Valid Values: 0 to MAX_INTEGER
Changes Take Effect: Immediately
The number of authorization retries that Configuration Server will generate if the current LDAP server does not respond. Specify a value for this parameter if you are using multiple LDAP servers. If Configuration Server does not receive a reply within this number of retries, it sends the request to the next LDAP authentication server specified in the object’s options.
If you are using only one LDAP server, requests will always be sent to that server regardless of the value of retry-attempts.
If Configuration Server has tried all the LDAP servers without getting a response, an error is generated. See Error Handling.
retry-interval
Default Value: 10
Valid Value: 0 to MAX_INTEGER
Changes Take Effect: Immediately
The amount of time, in seconds, that Configuration Server waits for an authorization reply. If Configuration Server does not receive a reply from the current LDAP server during that time, it sends the request again, either to the same LDAP server or, if you are using multiple LDAP servers, to the next LDAP server, after the number of tries specified in retry-attempts.
connect-timeout
Default Value: 10
Valid Values: 0 to MAX_INTEGER
Changes Take Effect: Immediately
Defines the initial connection timeout (in seconds), after which Configuration Server deems the specified LDAP server to be unavailable. When set to zero (0), the default value (10) is used.
chase-referrals
Default Value: 0
Valid Values:
| 0 | Configuration Server chases (follows) referrals and uses anonymous bind to connect to the referred servers. The user is bound to the original server to which the authentication request was sent (as specified by the LDAP configuration in Configuration Server). |
| 1 | Configuration Server chases referrals and uses the same login credentials specified in the configuration of the original LDAP server (in the gauth_ldap section). The user is bound to the server at which authentication occurs. |
| 2 | Configuration Server does not chase referrals, and returns an error if a referral is returned. |
Changes Take Effect: At the next authentication request
Specifies how Configuration Server handles a referral returned by a configured LDAP server.
keepalive-enable
Default Value: false
Valid Values: true, false
Changes Take Effect: Immediately
Specifies the Keep-Alive setting for Configuration Server. If set to true, Configuration Server will disconnect from the LDAP Server if the server has not responded within the limits set by the other Keep-Alive parameters—time, probes, and interval.
- The Keep-Alive functionality can be enabled only on UNIX.
- If this option is not set, or set to false the related options keepalive-time, keepalive-probes, and keepalive-interval are ignored.
keepalive-time
Default Value: 10
Valid Values: 1 to MAXINTEGER
Changes Take Effect: Immediately
The number of seconds a connection must remain idle before TCP starts to send Keep-Alive probes.
- The Keep-Alive functionality can be enabled only on UNIX.
- This option is ignored if keepalive-enable is set to false.
keepalive-probes
Default Value: 3
Valid Values: 1 to MAXINTEGER
Changes Take Effect: Immediately
The maximum number of Keep-Alive probes that will be sent before Configuration Server disconnects from the LDAP Server.
- The Keep-Alive functionality can be enabled only on UNIX.
- This option is ignored if keepalive-enable is set to false.
keepalive-interval
Default Value: 10
Valid Values: 1 to MAXINTEGER
Changes Take Effect: Immediately
The time interval, in seconds, between individual Keep-Alive probes.
- The Keep-Alive functionality can be enabled only on UNIX.
- This option is ignored if keepalive-enable is set to false.
tls-target-name
Default Value: No default value
Valid Values: Any string
Changes Take Effect: Will be reflected from next LDAP connection attempt. No restart/switch is required.
Specifies the target host name to which the name in remote certificate will be checked against, regardless of whether IP address or FQDN is used for the connection. When establishing secure connection, this option enables Subject Name Indication (SNI) extension support to the original request that Configuration Server sends to the external LDAP server.