6.2 Configuring Single Sign-On Through Access Manager

Access Manager allows users to log in to Active Directory and launch a Web browser to automatically access the Role Mapping Administrator. The user does not need to enter a username or password.

The single sign-on process is as follows:

  1. A user logs in to an Active Directory workstation and is issued a Kerberos ticket.

  2. Access Manager accepts the Kerberos ticket issued by Active Directory and extracts the userPrincpalName of the Active Directory user from the ticket.

  3. Access Manager maps the userPrincpalName (from the Kerberos ticket) to user object attribute in the Identity Vault as defined by the Access Manager Kerberos class. For example, use the mail attribute.

    This attribute can be any attribute in the Identity Vault, including a custom attribute, as long as the value in the attribute matches the userPrincipalName attribute value in Active Directory.

  4. When the user launches a Web browser and navigates to the Role Mapping Administrator URL, the configured Access Manager Proxy Service forwards the username and password, via a SAML assertion, to the Role Mapping Administrator. If the username and password match a user in the Identity Vault, the user is automatically authenticated without needing any additional credentials.

The following sections contain the steps required to configure Access Manager to allow the single sign-on to occur for the users.

6.2.1 Prerequisites

  • Install and configure Access Manager 3.1 or later. For more information, see Novell Access Manager 3.1 SP2 Installation Guide.

  • Make sure that time is synchronized among the Access Manager Identity server, the Role Mapping Administrator, and the Identity Vault.

  • Add a DNS record for the Role Mapping Administrator to your DNS server. Access Manager uses the DNS name to handle requests.

6.2.2 Configuring Active Directory to Assign Kerberos Tickets

Complete the following sections to enable Active Directory to assign Kerberos tickets. When users log in to Active Directory they are automatically issued a Kerberos ticket.

Installing the spn and ktpass Utilities

The spn and ktpass utilities must be installed on the Active Directory domain controller. These utilities are not installed by default. You need both of these utilities to configure the Access Manager Identity Server for Kerberos authentication.

  1. Insert the Windows 2003 disk into the CD drive.

  2. To install the utilities, run \SUPPORT\TOOLS\SUPTOOLS.MSI on the CD.

    The utilities are installed in C:\Program Files\Support Tools.

Creating a User Account in Active Directory for the Identity Server

Creating this account allows the Identity Server from Access Manager to run as a service.

  1. In the user management tool, using the following information to create the user account:

    firstname: Specify a name for the Identity Server.

    lastname: Specify a name for the Identity Server.

    userPrincipalName: Specify the userPrincipalName. The format is HTTP/your.idp.fqdn@YOUR.DOMAIN.

    For example: HTTP/amser.provo.novell.com@AD.NOVELL.COM

    samAccountName: Specify the samAccountName for the user. It consists of the firstname-lastname (required for the setspn utility).

    password: Specify a password for this user account.

    Deselect the option User must change password at next logon and select the option Password never expires. The user account needs a password, but it must never expire or be changed.

  2. Set the servicePrinicpalNames on the user object.

    This sends the Kerberos token to the Identity Server instead of directly to the managed system Portal, so the single sign-on can occur.

    1. At a command line, enter:

      setspn -a HTTP/amserv.provo.novell.com@AD.NOVELL.COM samAccountName

    2. At a command line, enter:

      setspn -a HTTP/amserv.provo.novell.com samAccountName

  3. Export the keytab file by using the ktpass utility.

    ktpass /out nidp.keytab /princ HTTP:///amserv.provo.novell.com@AD.NOVELL.COM /mapuser samAccountName@AD.NOVELL.COM /pass secret +DesOnly /crypto DES-CBC-MD5 /ptype KRB5_NT_PRINCIPAL

  4. Copy the keytab file to jre directory on the Identity Server. The default location is:

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

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

Creating a 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 the 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

    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 the 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 the Identity Server user and the Active Directory domain to which the user belongs.

    /pass

    <userPassword>

    Specify the password for this user.

    For this configuration example, you would enter the following command to create a keytab file named nidkey:

    ktpass /out nidkey.keytab /princ HTTP/amser.provo.novell.com@AD.NOVELL.COM /mapuser/ amser@AD.NOVELL /pass novell

  2. Copy the keytab file to the Identity Server.

    The default location for the keytab file on the Identity Server is:

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

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

6.2.3 Configuring the Access Manager Identity Server to Consume the Kerberos Tickets

You must configure Access Manager to consume the Kerberos tickets from Active Directory. Access Manager can use the authentication information in the Kerberos tickets to enable single sign-on for the Role Mapping Administrator.

Enabling Logging for Kerberos Transactions

This helps with troubleshooting authentication issues.

  1. In the Access Manager Administration Console, click Devices > Identity Server > Edit > Logging.

  2. Select the File Logging and Echo to Console options to enable these options.

  3. Under the Component File Loggers Levels heading, set the Application option to debug.

  4. Enable Trace Logging, then select Application, Configuration, and User Store as Component Content Filters.

  5. Click OK, then update the Identity Server.

Creating the bcsLogin.conf File

The bcsLogin.conf file is an authentication file for Java authentication and authorization service (JAAS).

  1. In an text editor, type the following lines:

    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";
};

    The file cannot contain any white space, only end-of-line characters.

    ticketCache: The location of the cache file where the Kerberos ticket is stored. In the example, this is the default location on SLES 10. If you are using Windows, the default location is:

    C:\\Program Files\\Novell\\jre\\lib\\security\\spnegoTicket.cache

    The path must contain double slashes.

    principal: Specify the service principal name for the Access Manager Identity Server. This value is unique to your configuration.

    keyTab: Specify the location of the keytab you created in Creating a Keytab File. This value is unique to your configuration. In the example, this is the default location on SUSE Linux Enterprise Server (SLES) 10. If you are using Windows, the default location is:

    C:\\Program Files\\Novell\\jre\\lib\\security\\nidpkey.keytab

    The path must contain double slashes.

  2. Save this file with the name bcsLogin.conf.

  3. Copy this file to the directory where the keytab file is stored.

  4. Make sure that the permissions are set to 644.

  5. Restart Tomcat.

    Linux: /etc/init.d/novell-tomcat5 restart

    Windows: Stop and start the Tomcat service from the control panel.

    When a change is made to the bcsLogin.conf file, Tomcat must be restarted.

Creating a User Store for the Active Directory Domain

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 to view your 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.

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

    Name: Specify a name for 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.

    Directory Type: Select Active Directory.

    Server replica: (Conditional) For a new Active Directory user store, click New to add a replica. Fill in the following fields:

    • Name: Specify a name of the replica for reference. This can be the name of the 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.

    • Port: Specify the port that the Active Directory server uses to communicate to the Identity Server. This communication occurs over LDAP. The default non-secure port is 389. The default secure port is 636.

    Search Context: 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. Add a context if it is missing.

  4. Click OK to save the changes.

Creating a Kerberos Authentication Class for the Identity Server

  1. In the Local tab of the Identity Server, click Classes > New.

  2. Fill in the following fields:

    Display name: Specify a name to identify this class.

    Java Class: Select KerberosClass.

  3. Click Next.

  4. Fill in the following fields:

    Service Principal Name: Specify the value of the servicePrincipalName attribute of the Identity Server user. This is the user created in Creating a User Account in Active Directory for the Identity Server.

    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 uppercase. The value in this field is case sensitive.

    JAAS config file for Kerberos: Specify the path to the bcsLogin.conf file. This is the created in Creating the bcsLogin.conf File.

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

    User Attribute: Specify the attribute in the Identity Vault that contains the userPrincipalName from Active Directory. For example, the mail attribute in the Identity Vault can store the userPrincipalName from Active Directory.

    If this attribute does not contain the userPrincipalName from Active Directory, the authentication to the Role Mapping Administrator fails.

  5. Click Finish to save the authentication class.

Creating a Kerberos Method for the Identity Server

  1. In the Local tab of the Identity Server, click Method > New.

  2. Fill in the following fields:

    Display name: Specify a name to identify this method.

    Class: Select the Kerberos class created in Creating a Kerberos Authentication Class for the Identity Server.

    User stores: Move the user store for the Identity Vault to the list of User stores. This must be the Identity Vault user store, not the Active Directory user store.

  3. Click Finish to save the method.

Creating a Kerberos Contract for the Identity Server

  1. In the Local tab of the Identity Server, click Contract > New.

  2. Fill in the following fields:

    Display name: Specify a name to identify this contract.

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

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

    Methods: From the list of available methods, move the Kerberos method you created in Creating a Kerberos Method for the Identity Server to the Methods list.

  3. Click Finish to save the contract.

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 the keytab file

    For the example configuration, the file contains 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.

Creating a SAML Identity Injection Policy

You must create a SAML identity injection policy for Access Manager to use. This allows the authentication information in the Kerberos tickets to be passed to the Role Mapping Application.

  1. In the Administration Console, click Policies > Policies > Master_Container.

    The policy must reside in the master container.

  2. Click New to create a new policy.

  3. Specify a name to identify the policy.

  4. For the policy type, select Access Gateway: Identity Injection.

  5. Click OK.

  6. Fill in the following fields to define the policy:

    Description: Specify a description for the policy.

    Priority: Leave the priority to the default level of 1.

    Actions: Click New > Inject into Authentication Header.

    • User Name: Select Credential Profile, then select LDAP Credentials:LDAP User Name for the user name.

    • Password: Select Credential Profile, then select SAML Credentials:SAML Assertion.

    • Multi-Value Separator: Leave the default separator as a comma.

    • DN Format: Leave the default DN format as LDAP.

  7. Click OK twice to save the policy.

Refreshing the Identity Server

In order for the changes to the Identity Server to take effect, you must refresh the Identity Server.

  1. In the Administration Console, select Devices > Identity Servers.

  2. Select your Identity Server, then click Refresh.

  3. Click Close.

Creating a Protected Resource for the Role Mapping Administrator

You must configure the Role Mapping Administrator as a protected resource in the Access Gateway.

  1. In the Administration Console, click Devices > Access Gateways, then click the name of your Access Gateway.

  2. (Conditional) If you have a Proxy Service defined for the Role Mapping Administrator, skip to Step 3. Otherwise, complete the following steps to create the Proxy Service for the Role Mapping Administrator:

    1. Click New in the Proxy Service List.

    2. Fill in the following fields:

      Proxy Service Name: Specify a name to identify the Role Mapping Administrator as a Proxy Service.

      Multi-Homing Type: Select Domain-Based.

      Published DNS Name: Specify the DNS name for the Role Mapping Administrator server.

      Path: Specify the Role Mapping Administrator’s application context. The default context is IDMRMAP. There should be two entries For example:

      /*

      /IDMRMAP/*

      Web Server IP Address: Specify the IP address of the Web server.

      Host Header: Select Web Server Host Name to publish the DNS name that the user sent in the request to be replaced by the DNS name of the Web server.

      Web Server Host Name: Specify the DNS name of the Web server.

    3. Click OK to create the Proxy Service for the Role Mapping Administrator.

  3. Click the display name of the Role Mapping Administrator Proxy Service.

  4. Click the Protected Resources tab, then click New.

  5. Specify the name of the protected resource, then click OK.

  6. Fill in the following fields on the Overview tab:

    Description: Specify a description for the protected resource.

    Contract: Select the Kerberos contract created in Creating a Kerberos Contract for the Identity Server.

    URL Path: Click the /* path, then define the application context for the Role Mapping Administrator. For example:

    /* /IDMRMAP/*

  7. Click the Identity Injection tab, then click Manage Policies.

  8. Select the policy created in Creating a SAML Identity Injection Policy, then click Apply Changes.

  9. Click Close to close the policies window.

  10. Click OK twice to save the changes to the protected resource.

Refreshing the Access Gateway

In order for the changes for the protected resource to take affect, you must refresh the Access Gateway.

  1. In the Administration Console, select Devices > Access Gateways.

  2. Select your Access Gateway, then click Refresh.

  3. Click Close.

6.2.4 Configuring the User’s Web Browser

Each user’s Web browser must be configured to trust the Access Manager Identity Server.

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

    For instructions, see your Active Directory documentation.

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

  3. Configure the Web browser to trust the Identity Server:

    For Internet Explorer version 7 and later: Click Tools > Internet Options > Security > Local intranet > Sites > Advanced. (For Internet Explorer version 6, click Tools > Internet Options > Security > Trusted sites > Sites.)

    In the Add this website to the zone text box, specify the Base URL for the Identity Server, then click Add.

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

    Click Close.

    For Firefox: In the URL field, specify about:config. In the Filter field, specify network.n. 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, you would add http://amser.provo.novell.com to the list.

    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 authorization to the server. Specify a comma-delimited list of trusted domains or URLs.

    For this example configuration, you would add http://amser.provo.novell.com to the list.

  4. Click OK. The configuration appears as updated.

    Restart your Firefox browser to activate this configuration.

  5. In the URL field, enter the base URL of the Identity Server with port and application. For this example configuration:

    http://amser.provo.novell.com:8080/nidp

    The Identity Server authenticates the user without prompting the user for authentication information.