4.1.12 Kerberos Authentication

Kerberos is an authentication method that allows users to log in to an Active Directory domain. This authentication method provides a token. You can configure Identity Server to use this token as a contract. This provides single sign-on for the user between Active Directory and Identity Server.

Kerberos authentication is achieved using SPNEGO with GSS-API (JGSS). SPNEGO (RFC 2478 - Simple and Protected GSSAPI Negotiation implementation in Microsoft Windows 2000/XP/2k3/2k8) is a GSSAPI mechanism for extending a Kerberos single-sign-on environment to web transactions and services. It enables peers determine which GSSAPI mechanisms are shared and enables them select one and establish a security context with it. SPNEGO's most visible use is in Microsoft's HTTP Negotiate authentication mechanism.

The Kerberos module for Access Manager is implemented as an additional out-of-the-box authentication mechanism to securely negotiate and authenticate HTTP requests for protected resources. This makes it possible to seamlessly authenticate (single sign-on) to Identity Server from enterprise-wide Microsoft Windows Domain Logon.

This section explains how to configure Active Directory, Identity Server, and Access Gateway for Kerberos authentication to a protected web server.

Figure 4-4 Example Kerberos Configuration

  1. A user logs in to the computer.

  2. The client computer gets a ticket granting ticket.

  3. The user sends a request to the protected resource.

  4. Access Gateway redirects the request to Identity Server for authentication.

  5. The client sends a request to Identity Server.

  6. Identity Server sends the 401 unauthorized response.

  7. The client sends a request with the Kerberos service ticket.

  8. Identity server decrypts the Kerberos ticket using the key tab file and then it performs an LDAP search with user principal name.

  9. Identity Server receives the success status for the LDAP search, and then the user authentication is completed successfully.

  10. Identity Server redirects the response to Access Gateway.

  11. The user gets access to the protected resource.

Perform the following tasks to configure Kerberos authentication:

  1. Configure Active Directory. See Configuring Active Directory.

  2. Configure Identity Server. See Configuring Identity Server.

  3. Configure clients. See Configuring the Clients.

  4. Configure Access Gateway. See Configuring Access Gateway for Kerberos Authentication.

Prerequisites for Configuring Kerberos Authentication

  • Clients must be running on Windows with Internet Explorer, Chrome, or Firefox.

    To make Kerberos work with Internet Explorer, you need to enable integrated Windows authentication. For information about how to enable this feature, see “Authentication Uses NTLM instead of Kerberos”.

    IMPORTANT:You must perform the following tasks:

    • Configure Internet Options of the web browser to trust the URL of Identity Server.

    • Configure the keytab file to trust more than DES encryption. If you created your keytab file for an earlier version of Access Manager where only DES was supported, you need to recreate the keytab file. For information, see Configuring the Keytab File.

    For more information, see TID 7006036.

  • Active Directory must be configured to contain entries for both users and their machines.

  • Active Directory and Identity Server must be configured to use a Network Time Protocol server. If time is not synchronized, authentication fails.

  • If a firewall separates the Active Directory Server from Identity Server, ports TCP 88 and UDP 88 are opened. So that Identity Server can communicate with Key Distribution Centre (KDC) on the Active Directory Server.

Configuring Active Directory

Perform the following tasks:

Creating and Configuring the User Account for Identity Server

  1. In Administrative Tools on your Windows server, click Active Directory users and computers.

  2. Select to create a new user.

  3. Specify the following details:

    Field

    Description

    First name

    Specify the hostname of Identity Server. This is the username. For the example configuration, this is amser.

    You can verify the hostname by running the hostname command on Identity Server.

    User logon name

    Specify HTTP/<Identity_Server_Base_URL>.

    For example, if base URL of Identity Server is amser.nam.example.com, specify the following:

    HTTP/amser.nam.example.com

    The realm is displayed next to the User logon name.

    User logon name (pre Windows 2000)

    Specify the hostname of Identity Server.

    The default value must be modified. For example, amser.

    (Complete this step regardless of the Windows version you are using.)

  4. Click Next, configure the password, and perform the following actions:

    Field

    Description

    User must change password at next logon

    Deselect this option.

    Password never expires

    Select this option.

  5. Click Next > Finish.

    This creates an Identity Server user. You need to remember the values you assigned to this user for First name and User logon name.

  6. Set the servicePrincipalName (spn) attribute for this user. Open the command prompt or PowerShell and run the following command as an administrator:

    setspn -A HTTP/<userLogonName> <userName>

    IMPORTANT:This command is case-sensitive.

    For this configuration example, run the following command:

    setspn -A HTTP/amser.nam.example.com@AD.EXAMPLE.COM amser

    This adds the servicePrincipalName attribute to the user specified with the value specified in the -A parameter.

    NOTE:For Domain Services for Windows, set HOST spn also by using this command: setspn -A HOST/<userLogonName> <userName>

  7. (Optional) Verify that the user has the required servicePrincipalName attribute with a valid value. Enter the following command:

    setspn -L <userName>

    For this configuration example, enter the following command:

    setspn -L amser

Configuring the Keytab File

The keytab file contains the secret encryption key that is used to decrypt the Kerberos ticket. You need to generate the keytab file and copy it to Identity Server.

  1. On the Active Directory server, open a command window and enter a ktpass command with the following parameters:

    ktpass /out value /princ value /mapuser value /pass value /pType KRB5_NT_PRINCIPAL

    The command parameters require the following values:

    Parameter

    Value

    Description

    /out

    <outputFilename>

    Specify a name for the file, with .keytab as the extension. For example: nidpkey.keytab

    /princ

    <servicePrincipalName> @<KERBEROS_REALM>

    Specify the service principal name for Identity Server, then @, followed by the Kerberos realm. The default value for the Kerberos realm is the Active Directory domain name in all capitals. The Kerberos realm value is case sensitive.

    /mapuser

    <identityServerUser>@<AD_DOMAIN>

    Specify the username of Identity Server user and the Active Directory domain to which the user belongs.

    /pass

    <userPassword>

    Specify the password for this user.

    /pType

    <principalType>

    Specify the principal type as KRB5_NT_PRINCIPAL.

    For this configuration example, specify the following command to create a keytab file named nidpkey:

    ktpass /out nidpkey.keytab /princ HTTP/amser.nam.example.com@AD.
EXAMPLE.COM /mapuser amser@AD.EXAMPLE.COM /pass example /pType KRB5_NT_PRINCIPAL

  2. Copy the file to the default location on Identity Server:

    Linux: /opt/novell/java/jre/lib/security

    Windows Server: C:\Program Files\Novell\jre\lib\security

  3. If the cluster contains multiple Identity Servers, copy the keytab file to each member of the cluster.

Adding Identity Server to the Forward Lookup Zone

  1. In Administrative Tools on your Windows server, click DNS.

  2. Click Forward Lookup Zone.

  3. Click the Active Directory domain.

  4. In the right pane, right click, and select New Host (A).

  5. Specify the following details:

    Name: Specify the hostname of Identity Server.

    IP Address: Specify the IP address of Identity Server.

  6. Click Add Host.

Configuring Identity Server

Perform the following tasks:

  • Configure Identity Server to use the Active Directory server as a user store.

  • Configure a Kerberos authentication class, method, and contract.

  • Create a configuration file.

  • Enable logging to verify the configuration.

These instructions assume that you have installed and configured an Identity Server cluster configuration.

See Installing Access Manager in the NetIQ Access Manager 4.5 Installation and Upgrade Guide and Configuring Identity Servers Clusters.

Topics include:

Enabling Logging for Kerberos Transactions

Enabling logging is highly recommended. If Kerberos authentication does not function after you complete the configuration tasks, you can check the reasons in the log file (catalina.out on Linux or stdout.log on Windows).

  1. Click Devices > Identity Servers > Edit > Auditing and Logging.

  2. Select File Logging and Echo To Console options.

  3. In the Component File Logger Levels section, set Application to debug.

  4. Click OK, then update Identity Server.

Configuring Identity Server for Active Directory

You need to configure Identity Server to use Active Directory as a user store or verify your existing configuration for your Active Directory user store.

  1. Click Devices > Identity Servers > Edit.

  2. Click Local.

  3. View installed user stores.

    If you have already configured Identity Server to use the Active Directory server, click its name.

    If you have not configured a user store for the Active Directory server, click New.

  4. For a new user store, specify the following details. For an existing Active Directory user store, verify the values.

    Field

    Description

    Name

    Specify a name of the user store for reference.

    Admin name

    Specify the name of the administrator of the Active Directory server. Administrator-level rights are required for setting up a user store. This ensures read/write access to all objects used by Access Manager.

    Admin password and Confirm password

    Specify the password for the administrator of the Active Directory server and confirm the password.

    Directory Type

    Select Active Directory.

    Search Contexts

    For a new user store, click New and specify the context of the administrator of the Active Directory server. For an existing user store, verify that you have an entry for the context of the administrator and add one if it is missing.

  5. (Conditional) For a new Active Directory user store, add a replica.

    1. In the Server replicas section, click New.

    2. Specify the following details:

      Name: Specify a name of the replica for reference. This can be the name of your Active Directory server.

      IP Address: Specify the IP address of the Active Directory server and the port you want Identity Server to use when communicating with the Active Directory server.

    3. Configure the other fields to fit your security model.

    4. Click OK.

  6. (Optional) Specify values for the other configuration options.

  7. Click OK or Finish.

  8. Continue with Creating the Authentication Class, Method, and Contract.

Creating the Authentication Class, Method, and Contract

Ensure that Prerequisites for Configuring Kerberos Authentication are met.

  1. In the Local page, click Classes > New.

  2. Specify the following details:

    Display name: Specify a name that you can use to identify this class.

    Java class: Select KerberosClass.

  3. Click Next.

  4. Specify the following details:

    Field

    Description

    Service Principal Name (SPN)

    Specify the value of the servicePrincipalName attribute of the Identity Server user.

    For this example configuration, this is HTTP/amser.nam.example.com.

    Kerberos Realm

    Specify the name of the Kerberos realm. The default value for this realm is the domain name of the Active Directory server, entered in all capitals. The value in this field is case-sensitive.

    For this example configuration, this is AD.EXAMPLE.COM.

    JAAS config file for Kerberos

    Verify the default path. This must be the same path to which you copied the keytab file (see Step 2 in Configuring the Keytab File) and end with the name of the configuration file, bcsLogin.conf.

    For Windows, the path needs to contain double slashes, for example: C:\\Program Files\\Novell\\jre\\lib\\security

    For information about creating this file, see Creating the bcsLogin Configuration File.

    Kerberos KDC

    Specify the IP address of KDC. If multiple KDCs are present for fail-over support, then specify the IP addresses separated by colon (:). You can configure up to four IP addresses.

    If a L4 switch is configured for load balancing among KDCs, then specify the virtual IP address of the L4 switch in this field.

    User Attribute

    Specify the name of the Active Directory attribute that combines the cn of the user with the DNS domain name to form its value.

    It is an alternate name for user login. Accept the default value unless you have set up a different attribute.

  5. (Conditional) If you have configured your users to have multiple User Principal Names (UPN) so they can log in using different names (such as jdoe@abc.com, jdoe@bcd.com, and jdoe@cde.com), click New, specify the suffix (such as @abc.com), then click OK.

  6. Click Finish.

    IMPORTANT:You must create only one Kerberos class. This is caused by a limitation in the underlying Sun JGSS.

  7. On the Local page, click Methods > New.

  8. Specify the following details:

    Field

    Description

    Display name

    Specify a name that you can use to identify this method.

    Class

    Select the class that you created for Kerberos.

    User stores

    Move the Active Directory user store to the list of User stores.

    If you have only one installed user store, <Default User Store> can be used.

    If you have multiple user stores, the Active Directory user store must be in this list (or if it is configured to be the default user store, <Default User Store> must be in this list).

    NOTE:The testing procedure to verify Kerberos authentication depends on whether the Active Directory user store configured as the default user store. See Step 13.

    You do not need to configure properties for this method.

  9. Click Finish.

  10. In the Local page, click Contracts > New.

  11. Specify the following details:

    Field

    Description

    Display name

    Specify a name that you can use to identify this method.

    URI

    Specify a value that uniquely identifies the contract from all other contracts.

    Methods

    From the list of Available methods, move your Kerberos method to the Methods list.

    You do not need to configure the other contract options.

  12. Click Finish.

  13. (Optional) To use the procedure that verifies the authentication configuration, make the Active Directory user store as the default user store.

    1. In the Local page, click Defaults.

    2. Specify the following details:

      User Store: Select the name of your Active Directory user store.

      Authentication Contract: Select the name of your Kerberos contract.

    3. Click OK.

      This allows you to log in directly to Identity Server by using the Kerberos contract. If you have already logged in to the Active Directory domain on the Windows machine, single sign-on is enabled and you are not prompted to log in to Identity Server.

  14. On the Identity Servers page, click Update.

    Wait until the Health icon turns green. Click Refresh to update the page.

  15. If you want to configure Access Gateways to use the Kerberos contract, update these devices so that the Kerberos contract is available.

  16. Continue with Creating the bcsLogin Configuration File.

Creating the bcsLogin Configuration File

The bcsLogin.conf file defines the Login module used for Kerberos implementation, service principal name for Identity server, location of the keytab file, and other configuration options.

Perform the following steps to create the file:

  1. Open a text editor. A sample editable bcsLogin.con file called bcsLogin.conf.template is included. Open this file.

  2. Enter the following lines.

    The file cannot contain any white space, only end-of-line characters. Two lines (principal and keyTab) need to specify unique information for your configuration. The principal line needs to specify the service principal name for Identity Server. The keyTab line needs to specify the location of the keytab file. The following file uses the values of the example configuration for the principal and keyTab lines. The keyTab and ticketCache lines use the default path for SUSE Linux Enterprise Server (SLES).

    com.sun.security.jgss.accept {
com.sun.security.auth.module.Krb5LoginModule required
debug="true"
useTicketCache="true"
ticketCache="/opt/novell/java/jre/lib/security/spnegoTicket.cache"
doNotPrompt="true"
principal="HTTP/amser.nam.example.com@AD.EXAMPLE.COM"
useKeyTab="true"
keyTab="/opt/novell/java/jre/lib/security/nidpkey.keytab"
storeKey="true";
};

    Identity Server checks the Kerberos server for each user transaction. When you set the isInitiator value to false (isInitiator="false") in the bcsLogin.conf file after the keyTab="/opt/novell/java/jre/lib/security/nidpkey.keytab" line, Identity Server does not communicate to the Kerberos server.

    Path of bcsLogin.conf on SLES and Red Hat is /opt/novell/java/jre/lib/security/.

    NOTE:Before setting the value to false, it is recommended that you access the protected site via https and the keytab file is secure.

    For Windows, the path needs to contain double slashes: C:\\Program Files\\Novell\\jre\\lib\\security

    Windows Server: The path in the keyTab line must be C:\\Program Files\\Novell\\jre\\lib\\security\\nidpkey.keytab

    The path in the ticketCache line must be C:\\Program Files\\Novell\\jre\\lib\\security\\spnegoTicket.cache

  3. Save this file with a name of bcsLogin.conf.

  4. Copy this file to the location specified in the JAAS config file for Kerberos field of Step 4 in Creating the Authentication Class, Method, and Contract.

  5. Ensure that the file permissions are set to 644.

  6. Restart Identity Server.

    • Linux Identity Server: Specify the following command:

      /etc/init.d/novell-idp restart

    • Windows Identity Server: Specify the following commands:

      net stop Tomcat8

      net start Tomcat8

    Whenever you make changes to the bcsLogin.conf file, restart Tomcat.

  7. If the cluster contains multiple Identity Servers, copy the bcsLogin.conf file to each member of the cluster, then restart Tomcat on that member.

Verifying the Kerberos Configuration

To view catalina.out (Linux) or stdout.log (Windows) of Identity Server, perform the following steps:

  1. Click Auditing > General Logging.

  2. In Identity Servers section, select the catalina.out or stdout.log file.

  3. Download the file and open it in a text editor.

  4. Search for Kerberos and verify that a subsequent line contains a Commit Succeeded phrase. For the configuration example, the lines look similar to the following:

    principal's key obtained from the keytab
principal is HTTP/amser.nam.example.com@AD.EXAMPLE.COM
Added server's keyKerberos Principal HTTP/amser.nam.example.com@AD.EXAMPLE.COMKey Version 3key EncryptionKey: keyType=3 keyBytes (hex dump)=0000: CB 0E 91 FB 7A 4C 64 FE

[Krb5LoginModule] added Krb5Principal HTTP/amser.nam.example.com@AD.EXAMPLE.COM to Subject
Commit Succeeded

  5. If the file does not contain any lines similar to these, verify that you have enabled logging. See Enabling Logging for Kerberos Transactions.

  6. If the commit did not succeed, search backward in the file and verify the following values:

    • Service Principal Name

    • Name of keytab file

    For the example configuration, the file must contain lines with text similar to the following:

    Principal is HTTP/amser.nam.example.com
KeyTab is /usr/lib/java/jre/lib/security/nidpkey.keytab

  7. (Conditional) If you make any modifications to the configuration in Administration Console or in the bcsLogin file, restart Tomcat on Identity Server.

(Optional) Excluding Kerberos Authentication for Specific IP Addresses

You can configure the IP address or the range of IP addresses of the clients for which Kerberos authentication must be skipped or performed using the kerberos.exclude or kerberos.include keywords respectively.

NOTE:You can specify only kerberos.exclude or kerberos.include argument in the kerb.properties file not both.

To configure this option, add the following entry in the kerb.properties file:

  • kerberos.exclude=IP Address/Range separated by comma.

  • kerberos.include=IP Address/Range separated by comma.

For example:

kerberos.exclude=1.1.1.1-9.255.255.255,10.50.1.1 - 10.50.1.50,11.1.1.1-255.255.255.255

or

kerberos.include=10.1.1.1-10.49.255.255,10.50.1.51-10.255.255.255

For the clients coming from the IP addresses specified in kerberos.exclude, Kerberos authentication will be skipped and will fall back to the custom authentication class. See (Optional) Configuring the Fall Back Authentication Class.

For the clients coming from the IP addresses that are not specified in kerberos.include, kerberos authentication will be skipped and will fall back to the custom authentication class. See (Optional) Configuring the Fall Back Authentication Class.

The kerb.properties file is available in /opt/novell/nam/idp/webapps/nidp/WEB-INF/classes/.

(Optional) Configuring the Fall Back Authentication Class

You can configure an optional authentication class that is executed when either kerberos authentication fails or when kerberos authentication has to be skipped.

For information about how to skip the Kerberos authentication for certain IP addresses, see (Optional) Excluding Kerberos Authentication for Specific IP Addresses.

To configure the fall back authentication class, perform the following steps:

  1. Go to Identity Server Cluster > Edit > Local > Methods > (Kerberos Method) > Properties.

  2. Add a new property /value pair with name as FALLBACK_AUTHCLASS and set the property value to be the qualified class name, such as com.novell.nidp.authentication.local.PasswordClass.

    The class name value must be same as the value configured in the Java class path of the class at Identity Server Cluster > Edit> Local > Classes> (Authentication class).

NOTE:If your authentication class requires a custom JSP file for seeking credentials, add the property JSP and specify the name of the jsp file. When the JSP property is not specified, Identity Server uses the default login.jsp for seeking the credentials.

If you want to fall back to basic authentication, configure any one of the following properties: Property Name: FALLBACK_AUTHCLASS

Property Value: Basic or com.novell.nidp.authentication.local.BasicClass

IMPORTANT:The property name is case-sensitive.

For example, if you want to fall back to RADIUS, configure the following properties for the kerberos method:

FALLBACK_AUTHCLASS=com.novell.nidp.authentication.local.RadiusClassJSP=radiusloginServer=<<radius IPs with comma separate>>SharedSecret=<<secret string>>Port=<<port>>ReplyTime=7000 (in milli seconds, this is optional)ResendTime=2000 (in milli seconds, this is optional)Retry=5 (this is optional)Password=false

You can configure fall back to other mechanism based on the incoming header. In the kerberos method, add property as NO_NEGO_HEADER_NAME in Property and specify the header that needs to be ignored for the kerberos authentication in value.

For example, you have configure the name as NO_NEGO_HEADER_NAME with the value X-NovINet in the kerberos method properties. Then, if the client comes with header X-NovINet, the kerberos class will not be executed and it will fall back to the name password form by default or to the configured fall back mechanism.

(Optional) Modifying the LDAP Query Parameter of the Kerberos Method

You can modify the LDAP query parameter of the Kerberos method by using the SearchQuery property. For example, if you want to use the SearchQuery property for emails, perform the following steps:

  1. Navigate to Identity Servers > Edit > Local > Methods.

  2. Click the Kerberos method.

  3. Click Properties > New.

  4. Specify the following details:

    Property Name: SearchQuery

    Property Value: Specify one of the following parameters:

    • (&(objectclass=person)(mail=%Email%))

    • (&(objectclass=person)(givenName=%<Kerberos Realm>%))

      NOTE:Let us assume the UPN suffix is configured as AMTEST.COM and the Active Directory givenName is configured as user191. The LDAP search query will be (&(objectclass=person)(givenName=user191@AMTEST.COM)).

    • (&(objectclass=person)(name=%Ecom_User_ID%))

    • (&(objectclass=person)(CN=%Ecom_User_ID%))

Configuring the Clients

  1. Add the computers of the users to the Active Directory domain.

    For instructions, see the Active Directory documentation.

  2. Log in to the Active Directory domain, rather than the machine.

  3. (Conditional) If you are using Internet Explorer, perform the following steps to trust Identity Server:

    1. Click Tools > Internet Options > Security > Local intranet > Sites > Advanced.

    2. In Add this website to the zone, specify Base URL of Identity Server, then click Add.

      In the configuration example, this is http://amser.nam.example.com.

    3. Click Close > OK.

    4. Click Tools > Internet Options > Advanced.

    5. In the Security section, select Enable Integrated Windows Authentication, then click OK.

    6. Restart the browser.

  4. (Conditional) If you are using Firefox, perform the following steps to trust Identity Server:

    1. In URL, specify about:config.

    2. In Filter, specify network.n.

    3. Double click network.negotiate-auth.trusted-uris.

      This preference lists the sites that are permitted to engage in SPNEGO Authentication with the browser. Specify a comma-delimited list of trusted domains or URLs.

      For this example configuration, add amser.nam.example.com to the list.

    4. If the deployed SPNEGO solution is using the advanced Kerberos feature of Credential Delegation, double-click network.negotiate-auth.delegation-uris. This preference lists the sites for which the browser can delegate user to the server. Specify a comma-delimited list of trusted domains or URLs.

      For this example configuration, add amser.nam.example.com to the list.

    5. Click OK, then restart your Firefox browser.

  5. (Conditional) If you are using Chrome, perform the following steps to trust Identity Server:

    1. Click Control Panel > Network and Internet > Internet Options > Security > Local intranet > Sites > Advanced.

    2. In Add this website to the zone, specify Base URL of Identity Server, then click Add.

      In the configuration example, this is http://amser.nam.example.com.

    3. Click Close > OK.

    4. Select Advanced.

    5. In the Security section, select Enable Integrated Windows Authentication, then click OK.

    6. Restart the browser.

    NOTE:If you have configured Internet Explorer settings, then you do not need to perform these steps. Chrome in Windows uses the Internet Explorer settings.

  6. In URL, specify Base URL of Identity Server with port and application. For this example configuration, specify the following:

    http://amser.nam.example.com:8080/nidp

    Identity Server must authenticate the user without prompting the user for authentication information. If a problem occurs, check for the following configuration errors:

    • Verify the default user store and contract. See Step 13.

    • View Identity Server logging file and verify the configuration. See Verifying the Kerberos Configuration.

    • If you make any modifications to the configuration in Administration Console or to the bcsLogin file, restart Tomcat on Identity Server.

  7. (Conditional) Users who are outside the firewall cannot use Kerberos. SPNEGO by default first uses NTLM, then to HTTPS basic authentication. Access Manager does not support NTLM, so the NTLM prompt for username and password fails. The user is then prompted for a username and password for HTTPS basic authentication, which succeeds if the credentials are valid.

    To avoid these prompts, you can have your users enable the Automatic logon with current user name and password option in Internet Explorer 7.x. To access this option, click Tools >Internet Options >Security >Custom Level, then scroll down to User Authentication.

Configuring Access Gateway for Kerberos Authentication

If you want to configure Kerberos authentication for a web server, set up a protected resource for this web server, and select the name of the Kerberos contract for the authentication procedure. For instructions, see Section 2.6.5, Configuring Protected Resources.

When using Kerberos for authentication, the LDAP credentials are not available. If you need LDAP credentials to provide single sign-on to some resources, see Section 4.1.10, Password Retrieval.