Contents
External Authentication Process
This section introduces the concept of external authentication and describes how Configuration Server communicates with a third-party authentication server in this schema. It also highlights the procedure for activating external authentication.
Genesys software allows you to integrate it with a third-party authentication system. That is, you can deploy a third-party authentication system to control user access to Genesys applications. This way, you can benefit from your established security system, which can be fairly sophisticated and can provide functions that Genesys does not provide. Using an existing authentication system saves you from creating an additional security schema in your Genesys configuration environment.
To enable and configure RADIUS external authentication, see RADIUS External Authentication. To enable and configure LDAP Authentication, see LDAP External Authentication.
User Verification
To verify the identity of a user who logs in to a Genesys application, Configuration Server can:
- Check the user’s permission in the Configuration Database.
- Pass the user’s login information to a third-party server and perform the permission verification in the Configuration Database only in case of positive authentication results from the external system.
This document explains the authentication process that involves a third-party authentication server.
Starting in release 8.1, only users with a valid External ID will be considered for external authentication, unless the option enforce-external-auth is set to true. Genesys recommends that the default user not be configured with an External ID, to allow for system access if all external authentication servers are down.
When an external system handles the authentication process, Configuration Server communicates with the external authentication server by means of a pluggable module that Genesys has developed for a particular third-party server.
Authentication Architecture Involving an External System
Enabling External Authentication
External authentication works with Configuration Server. If you are installing Genesys software for the first time, you must first set up the Configuration Layer following the instructions in the Framework Deployment Guide .
By default, Configuration Server does not communicate with an external authentication server.
The following table summarizes how to enable external authentication.
|
Objective |
Related Procedures and Information |
|---|---|
|
Set up the external authentication system. |
Refer to the system documentation for your RADIUS or LDAP system. |
|
Deploy the external authentication module during the installation of Configuration Server. |
Do one of the following, as appropriate: To deploy RADIUS, follow the instructions in Deploying RADIUS Authentication. To deploy LDAP, follow the instructions in Deploying LDAP. |
|
Configure Configuration Server to run the selected external authentication systems: |
Do one of the following, as appropriate: For RADIUS, follow the instructions in Modifying the RADIUS Configuration Files. For LDAP, follow the instructions in Configuring LDAP Servers |
|
Start Configuration Server. |
Refer to the Framework Deployment Guide for information about starting Configuration Server. |
At startup, when external authentication is activated, Configuration Server verifies the presence of both the configuration option that points to the pluggable module, and the pluggable module itself. If either one of these is not found, Configuration Server considers external authentication to be disabled.
Configuring the Master Configuration Server
A new installation of the Master Configuration Server at its first startup reads values from its configuration file and saves those values in the Configuration Database. On all subsequent starts, it reads all values from the database and ignores those in its configuration file. (The backup Master Configuration Server, if configured, saves the information when the first switchover is completed.) As a result, you must make any changes to server-level external authentication parameters in the Options tab of the Configuration Server and Configuration Server Proxies. Any changes you make in the configuration file are ignored.
The only exception to this is the option enforce-external-auth (see enforce-external-auth). 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.
Synchronizing User Accounts
For Configuration Server to verify user permissions in the Configuration Database, you must synchronize the user accounts in the Configuration Database with the accounts in the external authentication system. In other words, you must create a Person object in the Configuration Database for each user who will operate in the Genesys environment. The properties of that object must correspond to the user’s parameters in the external authentication system.
To simplify the synchronization of user accounts, use the Genesys Configuration Import Wizard. For information about the wizard, refer to the Framework 8.0 Imported Configuration Data Formats Reference Manual.
Person Objects and External IDs
To be considered for external authentication, a Person must be configured with an ExternalID . In the simplest case, the External ID , it could be equal to the person's account name.
Customizing External Authentication Configuration
You can customize the configuration of external authentication for specific Person and Tenant objects. Values specified in the Configuration Server options enable External Authentication and are the default; but values defined at the Person or Tenant level can override them.
Establishing the Defaults
The authentication section in Configuration Server options enables External Authentication, and defines the default External Authentication values for all Person objects within the configuration. For details, see Modifying the RADIUS Configuration Files or Configuration Server Options.
The library option in the authentication section must specify a value for each External Authentication provider that your implementation supports:
The value gauth_ldap enables LDAP authentication.
The value gauth_radius enables RADIUS authentication.
The value gauth_ldap , gauth_radius or gauth_radius , gauth_ldap enables both LDAP and RADIUS.
The value gauth_kerberos enables Kerberos authentication. This applies only to the server on which it is configured; it cannot be customized at the tenant or user level.
The value internal , available only for setting at the Tenant or Person level, means that all users associated with the object in which the option is set to this value must validate internally.
Overriding the Defaults by Tenant
Use the following procedure to override the defaults for all Person objects belonging to a specific Tenant.
Overriding defaults for Person objects by Tenant
Start
- Create an authentication section in that Tenant's Annex Property. You must do this for all Tenants if you specify both provider types (LDAP and RADIUS) in the Configuration Server options.
- In the authentication section, create the option library, and assign it one of the values in Tenant-specific External Authentication Providers.
- If the Tenant is using LDAP external authentication (library=gauth_ldap ), create a gauth_ldap section for the first LDAP server and a gauth_ldap_n section for each additional server on the Tenant’s Annex tab, and assign appropriate values to the options in each section. Refer to Configuring LDAP Servers for detailed information about configuring multiple LDAP servers, and to Configuration Options for detailed descriptions of the options.
|
Value of library |
Description |
|---|---|
|
internal |
Authentication is performed internally, using the passwords stored in the Genesys database. Do not specify any additional options. |
|
gauth_radius |
All users of this Tenant are authenticated using the RADIUS access parameters specified in the local radiusclient.conf configuration file. Do not specify any additional options. Note that you cannot assign different Tenants to different RADIUS servers. |
|
gauth_ldap |
All users of this Tenant are authenticated through one or more LDAP server, each defined in a gauth-ldap or gauth_ldap_n (see Configuring LDAP Servers) and specified in the additional option ldap-url. You must specify at least one ldap-url option. You can specify other LDAP-related options, such as password, or more ldap-url options to specify a specific set of LDAP servers. You must define all valid LDAP-specific options in the Annex of the Tenant object. Important You cannot override the global option verbose or the content of ldaperrors.txt
. In addition, settings defined at the Tenant level can be overridden for individual users at the Person level. |
If you have existing Tenant, server, or Person objects that use legacy options (listed in Legacy Tenant-specific External Authentication Servers—LDAP) in the authentication section, Genesys recommends that you migrate to the gauth_ldap[_n] (where n is 1 to 9 )] section format as soon as possible, for security reasons. If you have both current options (in gauth-ldap[_n] sections) and legacy options (in the authentication section) configuration, the legacy options will be ignored.
End
|
|
Option Name |
Option Value |
Description |
|---|---|---|---|
|
First LDAP server |
ldap-url
|
<value>
|
URL of first LDAP server |
|
app-user
|
<value>
|
Distinguished name of application user for first LDAP server. | |
|
password
|
<value>
|
Application user password for first LDAP server | |
|
cacert-path
|
<value>
|
Path to CA certificate for first LDAP server | |
|
cert-path
|
<value>
|
Path to certificate of client’s key for first LDAP server | |
|
key-path
|
<value>
|
Path to client’s private key for first LDAP server | |
|
idle-timeout |
<value>
|
Time interval that the LDAP connection to the first LDAP server will be kept open if there are no more requests | |
|
retry-attempts |
<value>
|
Number of authorization retries that will be generated by Configuration Server if the first LDAP server does not respond | |
|
retry-interval |
<value>
|
Time that Configuration Server waits for an authorization reply from the first LDAP server. | |
|
connect-timeout |
<value>
|
Time that Configuration Server waits after initial connection before deeming first LDAP server to be unavailable. | |
|
Second LDAP server |
ldap-url1
|
<value>
|
URL of second LDAP server |
|
app-user1
|
<value>
|
Distinguished name of application user for second LDAP server. | |
|
password1
|
<value>
|
Application user password for second LDAP server | |
|
cacert-path1
|
<value>
|
Path to CA certificate for second LDAP server | |
|
cert-path1
|
<value>
|
Path to certificate of client’s key for second LDAP server | |
|
key-path1
|
<value>
|
Path to client’s private key for second LDAP server | |
|
idle-timeout2 |
<value>
|
Time interval that the LDAP connection to the second LDAP will be kept open if there are no more requests. | |
|
retry-attempts2 |
<value>
|
Number of authorization retries that will be generated by Configuration Server if the second LDAP server does not respond. | |
|
retry-interval2 |
<value>
|
Time that Configuration Server waits for an authorization reply from the second LDAP server. | |
|
connect-timeout2 |
<value>
|
Time that Configuration Server waits after initial connection before deeming second LDAP server to be unavailable. | |
|
Third LDAP server |
... |
... |
... |
|
... |
... |
... | |
|
Continue configuring groups of options for each LDAP server, as required, up to a maximum of 10 servers. | |||
Overriding the Defaults by Person Object
To override the default or Tenant-specific LDAP access parameters for any individual Person object, specify one or more partial LDAP URLs in the External User ID field in the General section of the Configuration tab of the Person object.
You can also override the list of servers specified by default or by the Tenant by specifying LDAP servers in the Annex , in the same way as you do for a Tenant (see See If the Tenant is using LDAP external authentication (library=gauth_ldap), create a gauth_ldap section for the first LDAP server and a gauth_ldap_n section for each additional server on the Tenant’s Annex tab, and assign appropriate values to the options in each section. Refer to “Configuring LDAP Servers” on page 36 for detailed information about configuring multiple LDAP servers, and to “Configuration Options” on page 46 for detailed descriptions of the options.).
These settings override both default and Tenant-specific settings, and do not require that you restart Configuration Server.
The scope of the override depends on whether there is an LDAP server address included in the LDAP URL given in the External User ID field. Generally:
If the LDAP URL in the External User ID field includes a server address, the LDAP server given by this address is considered part of the set of servers specified in the Annex . In this case, the LDAP search parameters specified in the External User ID field URL apply only to this LDAP server.
If the LDAP URL in the External User ID field does not contain a server address (only search and scope parameters), these search parameters are used to customize the search using the current set of LDAP servers, regardless of where, or at what level, they are defined.
Examples
Example 1
The External User ID field contains only a username.
For example: user1
The username is used for authorization. If LDAP servers have been configured in the Person object’s Annex
, the username will be used for authorization with only those servers.
Example 2
The External User ID field contains an LDAP URL consisting of only the server address.
For example: ldaps://luxor.us.int.vcorp.com:1636/
The server address in the External User ID field is used as the authentication server for this Person. Additional properties of the server can be specified in the Person object’s Annex
.
Additional LDAP servers can also be specified in the Annex . In this case, the options for the first LDAP server (url_ldap ) are ignored, as they are overridden by the server specified in the External User ID field. Only the subsequent servers (such as ldap-url1, ldap-url2, and so on) are used.
Example 3
The External User ID field contains an LDAP URL consisting of the search parameters but no server address.
For example: ldap:///???(mail=test@vcorp.com)
The specified search parameters override the corresponding parameters for all servers used by the Person
, whether they are default or defined at the Tenant or Person level.
High-Availability External Authentication Configurations
You can configure multiple external authentication servers to add to the reliability and efficiency of your system, as follows:
For LDAP, redundant configurations are supported with each additional servers configured in [gauth_ldap_n] sections. This can be done at all levels–server, tenant, and user.
For RADIUS, redundant authentication servers are configured in the redisuclient.conf configuration file of Configuration Server. This can be done only at the server level.
For Kerberos, redundant configurations are not supported, each configuration applies only to the server for which it is configured.
Disabling External Authentication
To disable external authentication at the Tenant or Person level, set the library option in the authentication section to internal in the object. For Configuration Server or Configuration Server Proxy, set the option to an empty value, and then restart the server to unload the authentication module and stop the authentication.
Refer to library (for RADIUS) or library (for LDAP) for information about the library option.).
Troubleshooting the External Authentication Connection
To obtain debugging information about the connection between any Configuration Server, including Configuration Server Proxy, and the RADIUS or LDAP server, use the configuration option verbose described in this section.
[authentication] Section
- Description: This section must be called authentication.
verbose
- Default Value: 0
- Valid Values:
|
0
|
Disables this feature. |
|
1
|
Produces debug information involving only unexpected situations, data, or internal states. |
|
2 |
Produces debug information without OpenLDAP library output. (The newer OpenLDAP contains a much larger internal debug size, which reduces system performance. This is the recommended level. |
|
3 |
Produces debug information, including all OpenLDAP library output. |
- Changes Take Effect: If switching of OpenLDAP output occurs, the changes take effect when the next connection is created (after disconnection, timeout expiry, or switch to a new LDAP server). Otherwise, the changes take effect immediately, when the next authentication request is processed.
- Specifies the output level for debugging information for the external authentication server. This information is used to troubleshoot the connection between Configuration Server and the RADIUS or LDAP server, from the Configuration Server side.
For any Configuration Server, including Configuration Server Proxy, add this section and option to the options of the Application object.
Example
The following is an example of the authentication section, with the value set to the recommended maximum:
- [authentication] verbose=2
Specific log events may also help you determine the state of the connection between Configuration Server and those external authentication servers in your configuration. This is in addition to the troubleshooting functionality described elsewhere in this document.
The following log events provide information about connections between Configuration Server and external authentication servers:
24100—Indicates that the connection between Configuration Server and the specified external authentication server has failed, and to which alternate external authentication server Configuration Server is trying to connect.
24101—Identifies that no external authentication servers are available. In other words, the connections between Configuration Server and all external authentication servers have failed.
24102— Indicates that connection to the specified external authentication server has been restored, and that the server is available for processing authentication requests.
For more information about these log events, refer to Framework Combined Log Events Help.