5.3 Configuring the Identity Server

You need to configure the 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, then restart Tomcat. These instructions assume that you have installed and configured an Identity Server cluster configuration. If you have not, see the Novell Access Manager 3.1 SP2 Installation Guide and the Novell Access Manager 3.1 SP2 Setup Guide.

This section covers the following tasks:

5.3.1 Enabling Logging for Kerberos Transactions

Enabling logging is not required, but it is highly recommended. If Kerberos authentication does not function after you have finished the configuration tasks, the first step in solving the problem is to look at the catalina.out (Linux) or the stdout.log (Windows) file.

  1. In the Administration Console, click Devices > Identity Servers > Edit > Logging.

  2. Enable the File Logging and Echo To Console options.

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

  4. Click OK, then update the Identity Server.

5.3.2 Configuring the Identity Server for Active Directory

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

  1. In the Administration Console, click Devices > Identity Servers > Edit.

  2. Click Local.

  3. View your installed user stores.

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

    If you haven’t configured a user store for the Active Directory server, click New.

  4. For a new user store, fill in the following fields. For an existing Active Directory user store, verify the values.

    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. In the Server replicas section, click New.

    1. Fill in the following fields:

      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 the Identity Server to use when communicating with the Active Directory server.

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

    3. Click OK.

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

  7. To save your changes, click OK or Finish.

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

5.3.3 Creating the Authentication Class, Method, and Contract

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

  2. Fill in the following fields:

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

    Java class: Select KerberosClass.

    The Java class path field displays the name of the KerberosClass.

  3. Click Next.

  4. Fill in the following fields:

    Service Principal Name (SPN): Specify the value of the servicePrincipalName attribute of the Identity Server user. For this example configuration, this is HTTP/amser.provo.novell.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.NOVELL.COM.

    JAAS config file for Kerberos: Verify the default path. This should 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

    Instructions for creating this file are in Creating the bcsLogin Configuration File.

    Kerberos KDC: Specify the IP address of the Active Directory server.

    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 should 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. Fill in the following fields:

    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 is dependent upon having 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. Fill in the following fields:

    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.

    The URI cannot begin with a slash, and it must uniquely identity the contract. For example: kerberos/contract

    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, you need to make the Active Directory user store the default user store. In the Local page, click Defaults.

    1. Fill in the following fields:

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

      Authentication Contract: Select the name of your Kerberos contract.

    2. Click OK.

      This allows you to log in directly to the 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 the 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 have Access Gateways or J2EE Agents that you want to configure to use the Kerberos contract, update these devices so that the Kerberos contract is available.

  16. Continue with Creating the bcsLogin Configuration File.

5.3.4 Creating the bcsLogin Configuration File

If you are upgrading from 3.0.4 to 3.1 SP2, the syntax of the bcsLogin.conf file has changed. For details, see Upgrading the SP4 Identity Servers in the Novell Access Manager 3.1 SP2 Installation Guide.

To create the file:

  1. Open a text editor.

  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 principle name for the 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.provo.novell.com@AD.NOVELL.COM"
    useKeyTab="true"
    keyTab="/opt/novell/java/jre/lib/security/nidpkey.keytab"
    storeKey="true";
    };
    

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

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

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

    Windows Server 2008: The path in the keyTab line should be C:\\Program Files (x86)\\Novell\\jre\\lib\\security\\nidpkey.keytab

    The path in the ticketCache line should be C:\\Program Files (x86)\\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. Make sure the file permissions are set correctly. They should be set to 644.

  6. Restart Tomcat.

    • Linux Identity Server: Enter the following command:

      /etc/init.d/novell-tomcat5 restart

    • Windows Identity Server: Enter the following commands:

      net stop Tomcat5

      net start Tomcat5

    Whenever you make changes to the bcsLogin.conf file, you need to 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.

5.3.5 Verifying the Kerberos Configuration

To view the catalina.out (Linux) or the stdout.log (Windows) file of the Identity Server:

  1. In the Administration Console, click Auditing > General Logging.

  2. In the 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.provo.novell.com@AD.NOVELL.COM
    Added server's keyKerberos Principal HTTP/amser.provo.novell.com@AD.NOVELL.COMKey Version 3key EncryptionKey: keyType=3 keyBytes (hex dump)=0000: CB 0E 91 FB 7A 4C 64 FE
    
    [Krb5LoginModule] added Krb5Principal HTTP/amser.provo.novell.com@AD.NOVELL.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 should contain lines with text similar to the following:

    Principal is HTTP/amser.provo.novell.com
    KeyTab is /usr/lib/java/jre/lib/security/nidpkey.keytab
    
  7. (Conditional) If you make any modifications to the configuration, either in the Administration Console or to the bcsLogin file, restart Tomcat on the Identity Server.