LDAP Configuration Options
Contents
This section describes the configuration options used to configure LDAP 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 tab of the Configuration Server or Configuration Server Proxy Application object
- In a multi-tenant and distributed environment, on the Annex tab 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 option enforce-external-auth (see enforce-external-auth) is set to true.
You can also fine-tune your LDAP configuration throughout your system by configuring some or all options in the Tenant object’s Annex. Refer to Using LDAP in a Multi-Tenant Configuration for more information.
Mandatory Options
Mandatory LDAP configuration options 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 |
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.
enforce-external-auth
- Default Value: false
- Valid Values: true, false
- Changes Take Effect: Immediately
- Description: Optional. Enforces external authentication for every user. If you omit this parameter, LDAP AM performs authentication only if external ID is specified in the Person object.
If this option is set to true in the database, but a newly installed Configuration Server reads its configuration file and finds the option set to false, Configuration Server sets it to false in the database. This ensures that all users are authenticated internally, including those without an External ID.
This option applies only at the server level.
library
Default Value: No default value
Valid Values: Depends on type configuration option, as follows:
| gauth_ldap | All |
| gauth_radius | All |
| gauth_ldap, gauth_radius | Configuration Server, Configuration Server Proxy |
| gauth_radius, gauth_ldap | 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.
- Description: 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
Each of these sections contains information about one LDAP Authentication Module. If you are using RACF, or if there is only one LDAP server, the section is called gauth_ldap. This section is mandatory. If you are using more than one LDAP Server, you must identify one in the gauth_ldap section, and the rest in individual gauth_ldap_n sections.
Configuration Server supports up to ten LDAP authorization servers. You can have up to nine of these sections, one section for each 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>
commit-timeout=<value>
chase-referrals=<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.
An LDAP Server is defined using the following options, described in this section:
- ldap-url
- app-user
- password
- ca-cert-path
- cert-path
- key-path
- idle-timeout
- retry-attempts
- retry-interval
- connect-timeout
- chase-referrals
To define an LDAP server, set these options on the Options tab of the object, in the gauth_ldap section. If you are using multiple LDAP servers, define the options for the additional servers in the appropriate gauth_ldap_n section.
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. If you are using multiple LDAP servers, define the rest of your LDAP servers (a maximum of nine) in the gauth_ldap_n section in the Configuration Server or Configuration Server Proxy Application object’s Options.
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 a sample of an LDAP URL parsed into its parameters (as listed in ldap-url parameters). Note that the URL contains no spaces and is a single expression that must be entered on a single line.
|
Parameter |
Definition of value |
|---|---|
|
1 Protocol type |
Required. Range: ldaps (SSL/TLS secure) or ldap (unsecure). |
|
2 LDAP server host name |
Optional. Default is the local host. 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 represents a risk. Genesys strongly advises using a secure connection. |
|
4 Base DN |
Required. Defines the node in the LDAP tree to use as base for the LDAP search. 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). Range: 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, 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)
Person object > Configuration tab > General section > External ID
|
For examples of LDAP URLs, see LDAP URL.
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 AM to search for the user's information that is needed to authenticate.
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 parameter is set.
cacert-path
- Default Value: Empty string
- Valid Value: Valid path.
- Changes Take Effect: Immediately
Full path to the file containing a certificate of a trusted Certificate Authority, which is used to negotiate a secure LDAP connection to the server. Required for a secured connection.
If mutual authentication is required on connections to LDAP servers, Configuration Server must be provisioned (using the cert-path and key-path [key-path]options) 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 of the LDAP client's private key.
If mutual authentication is required on connections to LDAP servers, Configuration Server must be provisioned (using the cert-path and key-path [key-path]options) 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 an LDAP client's private key.
If mutual authentication is required on connections to LDAP servers, Configuration Server must be provisioned (using the cert-path and key-path [key-path]options) 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 – MAX_INTEGER
- Changes Take Effect: Immediately
- Description: 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 – 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 ofretry-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 – 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
- Description: 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:
|
|
|
|
|
|
- Changes Take Effect: At the next authentication request
- Description: Specifies how Configuration Server handles a referral returned by a configured LDAP server.