Jump to: navigation, search

Kerberos External Authentication

This chapter describes how Configuration Server supports Kerberos external authentication for Genesys user interface applications.

Overview

Configuration Server and Configuration Server Proxy support the use of the Kerberos authentication protocol for user authentication in Genesys user interface applications. Kerberos enables secure communication between nodes over a non-secure network, using tickets to enable the nodes to prove their identity to each other in a secure manner.

Configuration Server uses Windows Active Directory and MIT key distribution centers to implement Kerberos authentication.

Kerberos vs RADIUS/LDAP

Kerberos, RADIUS, and LDAP are all types of external authentication. However, Kerberos differs from the existing external authentication protocols (RADIUS, LDAP, and others) by when the authentication is performed, as follows:

  • Existing external authentication protocols operate in “in behind” mode. That is, the authentication is carried out when the interface application sends the request to Configuration Server, which then forwards it to the authentication system.
  • Kerberos operates in “in front” mode. The authentication is activated on the client side before a connection to Configuration Server is made. When the actual connection to Configuration Server is made, the interface gets an authentication ticket (a Kerberos token) that is already authenticated. This ticket is sent to Configuration Server with the login request to assert that authentication is already done.

Kerberos runs independently of RADIUS and LDAP, and can run even when internal authentication is enforced (when library=internal).

Supported Environments

Configuration Server supports Kerberos authentication on the following operating systems:

  • Red Hat Enterprise Linux (RHEL) version 5 and later
  • Windows 2008 and later
  • Solaris version 10 and later
  • AIX version 5.3 and later

The following versions of MIT Kerberos are used:

  • krb5-1.11 for supported UNIX platforms
  • kfw-4.0.1 for Windows

Deploying Kerberos External Authentication

To deploy Kerberos, do the following:

1. Configure Kerberos on Configuration Server or Configuration Server Proxy. In the options of the Configuration Server or Configuration Server Proxy Application object, create the gauth_kerberos section, and set the following options:
2. Install Kerberos on the host on which that Configuration Server or Configuration Server Proxy is running. Follow the steps corresponding to the operating system of the host on which the Configuration Server or Configuration Server is running.

Prerequisite

  • Kerberos must be configured on the Configuration Server or Configuration Server Proxy as described in Step 1.
[+] Show steps

Kerberos Initialization File

When Kerberos is installed on the host of the Configuration Server or Configuration Server Proxy, it creates an initialization file that contains information about the realms used by Kerberos. This file has different names depending on the platform on which Kerberos is installed, but contains two or, optionally three, sections, as follows:

  • [libdefaults]—This section is required by Kerberos, and must contain the name of the realm used for authentication. For Windows Active Directory, that default realm must match the name of the Windows domain. By default, this name is the same as the DNS zone where "A" records of all Windows computers in this domain reside. Alternatively, this is the actual name of the Windows Domain in Active Directory only if the domain and DNS namespaces are disjoined. The name of the realm must be in upper case (that is, UPPER_CASE) characters only.
  • [realms]—This section must contain subsections keyed by Kerberos realm names. Each subsection describes realm-specific information, especially the kdc key with the key distribution center host.
  • [domain_realm]—(Optional) You can specify mandatory conversion from DNS zone names to realm names, to ensure that only upper-case realm names are being handled by Configuration Server.

The following is a sample of a Kerberos initialization file: 

[libdefaults]
default_realm = ROOTDOMAIN.CONTOSO.COM

[realms]
KRBTEST.GENESYSLAB.COM= {
   kdc = rh5qa64-1.genesyslab.com
   admin_server = rh5qa64-1.genesyslab.com
   }
ROOTDOMAIN.CONTOSO.COM = {
   kdc = 135.225.51.144
   admin_server = 135.225.51.144
   }

[domain_realm]
.rootdomain.contoso.com=ROOTDOMAIN.CONTOSO.COM

For more information, see http://web.mit.edu/Kerberos/krb5-1.5/krb5-1.5/doc/krb5-admin/krb5.conf.html.

For an initialization file on Windows, consult release notes about Windows distribution of Kerberos, at http://web.mit.edu/kerberos/kfw-4.0/kfw-4.0.html to determine the content and location of it.

Service Principal Name

You must define the Service Principal Name (SPN) according to the rules set out by your key distribution center, and provision it in Configuration Server using the SPN option. You must use the same SPN as used during keytab file creation by the key distribution center.

When you are using a Windows-based key distribution center and you want to enable Windows-based Genesys client applications, such as Agent Workspace Desktop Edition, or your custom applications written using Genesys PSDK, to use Kerberos with Configuration Server, make sure that you register this SPN in Windows Active Directory, as described in Genesys PSDK documentation and/or documentation for the particular Genesys product that supports Kerberos.

Keytab File

A keytab file is a part of the Kerberos infrastructure. It contains information that is required by Configuration Server to validate user passwords indirectly using Kerberos. When you deploy Configuration Server with Kerberos enabled, you must obtain this file from your key distribution center (as discussed in the following paragraph) and put it in the path specified by the keytab configuration option of Configuration Server.

Obtaining the Keytab File

When Kerberos starts, the local host on which Kerberos is installed sends a request to the Key Distribution Center to generate the keytab file with the name that you specify. The KDC generates the keytab file, and stores it in the same folder as the Kerberos initialization file. It must be created before you start to use Kerberos. To configure keytab file creation, use the procedure relevant to the type of Kerberos you are using.

Important
You must have the Inquire administrator privilege to create the keytab file using MIT Key Distribution Center.

To generate the keytab file:

  1. Change to the kadmin folder. For example, on UNIX enter: 
    cd /usr/local/bin/krb5-testinst/bin/kadmin
  2. Use the ktadd command to create the keytab file call inside the kadmin folder: 
    ktadd -k <path to resulting keytab> <SPN name>
    For more details about the syntax of the ktadd comment, see http://web.mit.edu/kerberos/krb5-1.5/krb5-1.5.4/doc/krb5-admin/Adding-Principals-to-Keytabs.html.

Example:

Path to resulting keytab file: /home/user/genesys_sample_keytab
SPN name: confserver/somehost 

ktadd -k /home/user/genesys_sample_keytab confserver/somehost

Important
You must have domain administrator rights to create the keytab file using Windows Active Directory.

Use the setspn command to map the SPN to a user: 

setspn -A <SPN> <username>

Use the ktpass command to create the keytab file, specifying the realms in upper-case: 

ktpass /princ <SPN>@<REALM> /mapuser <User name>@<REALM /pass <password> /out <Keytab file name> /crypto all /ptype KRB5_NT_PRINCIPAL /mapop set

For more details about the ktpass command, refer to https://technet.microsoft.com/en-us/library/cc776746(v=ws.10).aspx.

Example:

User name (known by Key Distribution Center): rootUser2 with password genesys
SPN: confserver/somehost
Keytab file name: c:\genesys-rootdomain.keytab
Realm: ROOTDOMAIN.CONTOSO.COM

Mapping of SPN "confserver/somehost" to rootUser2: 

setspn -A confserver/somehost rootUser2

To create the Keytab file: 

ktpass /princ confserver/somehost@ROOTDOMAIN.CONTOSO.COM /mapuser rootUser2@ROOTDOMAIN.CONTOSO.COM /pass genesys /out c:\genesys-rootdomain.keytab /crypto all /ptype KRB5_NT_PRINCIPAL /mapop set

Sample Kerberos Configurations

This section contains examples of how to configure Kerberos for integration with an MIT Key Distribution Center implementation, and for a Microsoft Active Directory implementation.

[+] Show examples

Character Case Considerations

When an instance of Configuration Server or Configuration Server Proxy is configured for Kerberos authentication, user objects are located by comparing the Windows login name provided by the Kerberos ticket with the user names of Person objects defined in Configuration Server. These searches are done on a case-sensitive basis. You can override this and make the search case-insensitive. This is especially useful if your system is using Microsoft Windows Active Directory as the Key Distribution Center, in which case, the Windows login names are case-insensitive.

To override the default behavior of the comparison, and make it a case-insensitive search, set the ignore-case-username option to true. If the search results in more than one user object with the same username regardless of case, Configuration Server will not authenticate the user. Instead, it will generate the CFGAccessDenied error.

This functionality does not apply if the username and password are provided directly in the registration request.

Redundant Configuration Servers

When primary and backup Configuration Servers are running on separate hosts, they can both use the same principal name (the SPN option). Each Configuration Server must be configured to use Kerberos, as described in this section; otherwise, no special configuration is required.

If the two servers are running on the same host and using the same SPN, the server applications must run under different system user accounts. That is, they must use a different user name in the Windows Services property—the Log in as field on the Log on tab.

Using Kerberos with Multiple Windows Active Directory Domains

You must specify Configuration Server SPN in Active Directory so that Kerberos-enabled Windows applications can get the proper ticket in a realm that matches the Configuration Server keytab. You can do this in one of two ways:

  • Have the Configuration Server SPN (and keytab) defined in the same Windows domain (Active Directory service) as any client accounts that will be used to obtain tickets.
  • In a forest of Windows Active Directory domains, you must set up a two-way transitive trust between domains if you want to use an account in one domain to access a Configuration Server for which its SPN (and keytab) are defined in another domain. Example:
    • Agents are in Active Directory Domain A.
    • Servers are in Active Directory Domain B. This includes Configuration Server Proxy, so Configuration Server Proxy SPN (SPN1) is also in AD Domain B.
    • Workspace Desktop Edition (WDE) is deployed with SPN1 in its settings.
    • Agents log in to WDE using accounts in Active Directory Domain A.

    As a result of the trust relationship, tickets that are obtained by agents in Active Directory Domain A to access the service defined by SPN1 are accepted by Configuration Server with the keytab generated for SPN1 in Active Directory Domain B.

    Refer to https://technet.microsoft.com/en-us/library/cc731335.aspx for detailed information about trusts in Microsoft Windows Active Directory.

Configuration Options

This section describes the configuration options used to configure Kerberos on Configuration Server and Configuration Server Proxy.

Warning
Configuration section names, configuration option names, and predefined option values are case-sensitive. Type them in Genesys Administrator exactly as they are documented here.

Setting Configuration Options

Unless otherwise specified, set Kerberos configuration options in the options of the Configuration Server or Configuration Server Proxy Application object. This will allow clients, such as Workspace Desktop Edition, to negotiate Kerberos authentication with Configuration Server or Configuration Server Proxy, when Kerberos is available on the client side.

Mandatory Options

The following options are mandatory, and must be set before using Kerberos.

gauth_kerberos Section

This section is mandatory, and contains information about the Kerberos installation on this Configuration Server or Configuration Server Proxy.

This section must be called gauth_kerberos.

SPN

Default Value: Empty string
Valid Value: Any valid name
Changes Take Effect: Immediately

The Service Principal Name, in the format service/hostname, the same as that used by a client in the service parameter. This name must be registered with the key distribution center to which this configuration is pointing (as defined by the platform-specific configuration).

realm

Default Value: Empty string
Valid Value: Any valid name
Changes Take Effect: Immediately

The name of the Kerberos infrastructure, as known by the MIT client library and/or the key distribution server being used. The value must be specified in all upper-case letters in the form of a domain address (ENTITY.SUBDOMAIN.ROOTDOMAIN).

keytab

Default Value: Empty string
Valid Value: Any valid name
Changes Take Effect: Immediately

The name of the keytab file that is generated by the key distribution center and propagated to the host on which this Configuration Server or Configuration Server Proxy is running. This file must exist in the installation directory of this Configuration Server (primary or backup) or Configuration Server Proxy.

krb-max-ticket-length

Default Value: 12000
Valid Values: Integer between 12000 and 64000 inclusive
Changes Take Effect: Immediately

Specifies the maximum length (in bytes) of the Kerberos ticket or GSS token to be validated by the Kerberos/GSS authentication library. A ticket/token with a length greater than the value of this option is rejected. If this option is not specified, or the value is less than 12000 or greater than 64000, the default value (12000) is used.

ignore-case-username

Default Value: false
Valid Value: true, false
Changes Take Effect: Immediately

When locating the authenticated user object based on its login name, this option specifies whether the comparison of the login name of the objects with the username specified in the Kerberos ticket is made on a case-insensitive (true) or case-sensitive (false) basis. If this option is set to true, and the search results in more than one user object with a username matching the provided login name, Configuration Server will not authenticate the user. Instead, it will generate the CFGAccessDenied error.

This option is useful if the environment is using Microsoft Windows Active Directory as the Key Distribution Center, in which case the usernames are case-insensitive. This option does not apply if the username and password are provided directly in the registration request.

Troubleshooting

If you have Kerberos authentication issues on the Configuration Server side, enable additional logging from the MIT Kerberos implementation by adding the environment variable KRB5_TRACE=<log file name and path> and make this environment variable available to the Configuration Server process. Be sure to restart Configuration Server.

This page was last edited on June 5, 2017, at 17:52.
Comments or questions about this documentation? Contact us for support!