Chapter 18 Using the Windows Desktop Single Sign-On Authentication Module

The OpenSSO Enterprise Windows Desktop SSO Authentication module is a Kerberos-based plug-in you can use with a Windows domain controller to achieve single sign-on (SSO). The plug-in enables a Windows client user, who has already authenticated to a Kerberos Distribution Center (KDC), to authenticate to OpenSSO Enterprise without re-submiting user credentials.

This chapter provides high-level instructions for configuring the OpenSSO Enterprise Windows Desktop SSO Authentication module, the Kerberos domain controller, and Windows Active Directory to achieve single sign-on using the Simple and Protected GSS-API Negotiation Mechanism (SPNEGO) protocol. The following topics are included in this chapter:

• About Kerberos Authentication and the SPNEGO Protocol

• About the OpenSSO Windows Desktop SSO Authentication Module

• Analyzing the Deployment Architecture

• Considering Dependencies and Constraints

• Understanding Typical Business Use Cases

• Evaluating Benefits and Tradeoffs

• Configuring Basic Windows Desktop SSO Authentication

• Complex Configurations

• Using the Debugging Tools

• Troubleshooting Windows Desktop SSO Authentication Issues

About Kerberos Authentication and the SPNEGO Protocol

Kerberos is an authentication protocol developed by the Massachusetts Institute of Technology. The Key Distribution Center (KDC) is the component of Kerberos that is responsible for issuing credentials. A credential is a packet of information that includes a ticket-granting ticket (TGT) and a matching session key. A ticket is an information packet that is used to securely pass the identity of a user to a server or service. After a ticket has been issued, it can be reused until the ticket expires. The session key contains information that is specific to the user and the service that is being accessed. The session key is shared between the client and service to secure transactions between them. The credential is encrypted with the requesting principal's key. For more information about Kerberos authentication, see Kerberos V5 Administrator's Guide.

The SPNEGO protocol is described in the abstract IETF RFC 2478. The SPNEGO protocol is intended to be used in environments where multiple GSS-API mechanisms are available to the client or server, and neither side knows what mechanisms are supported by the other.

About the OpenSSO Windows Desktop SSO Authentication Module

The Windows Desktop SSO Authentication Module enables OpenSSO Enterprise to work with Kerberos tokens. The user presents the Kerberos token, previously issued by a Kerberos Distribution Center, to OpenSSO Enterprise using the SPNEGO protocol. The client browser sends back a SPNEGO token embedded with a Kerberos token. The OpenSSO Windows Desktop SSO Authentication module retrieves the Kerberos token and authenticates the user using the Java GSS API. If authentication is successful, the OpenSSO Windows Desktop SSO Authentication module returns an SSOToken to the client.

Analyzing the Deployment Architecture

The following figure illustrates a basic deployment architecture that includes the OpenSSO Windows Desktop SSO Authentication module.

Figure 18–1 Deployment Architecture for OpenSSO Windows Desktop SSO Authentication Module

An OpenSSO Windows Desktop SSO Authentication deployment includes the following components:

Windows 2003 Server with Domain Controller

The Windows Domain Controller contains configuration information for the Windows XP workstation and the workstation users. If the configured domain-user authenticates to the domain with proper user principal and credentials, the Windows Domain Controller generates a TGT Kerberos ticket and sends the ticket to the authenticated user account.

Windows XP with SPNEGO-supported Browser

When the user accesses a resource that is protected with an authentication, an Authenticate:Negotiate response is sent to the browser. The browser obtains the Keberos Service ticket with the TGT that was generated in authentication time. This Service Kerberos ticket can be validated by the OpenSSO Enterprise server.

Sun Directory Server 6.3

Contains user profile information.

OpenSSO Windows Desktop SSO Authentication Module

The OpenSSO Windows Desktop SSO Authentication module is a server-side SPNEGO implementation that uses the Java GSS-API to process a Kerberos token sent by a SPNEGO-supported browser.

The following figure illustrates a typical process flow for Kerberos authentication using the Windows Desktop SSO Authentication module.

Figure 18–2 Process Flow for Windows Desktop SSO Authentication

Considering Dependencies and Constraints

In order to perform Kerberos-based single sign-on to OpenSSO Enterprise, the user client must support the SPNEGO protocol. Any client that supports the SPNEGO protocol should be compatible with the OpenSSO Windows Desktop SSO Authentication module. For example, Microsoft Internet Explorer (5.01 or later) running on Windows 2000 (or later) currently supports the SPNEGO protocol. Additionally, Mozilla 1.5 (or later) and Safari 2.0 (or later) also support SPNEGO.

The current implementation of the Windows Desktop SSO Authentication module supports only Kerberos tokens using on the SPNEGO protocol, and does not support the Windows Challenge/Response (NTLM) token at all. If the user's browser submits an NTLM token instead of a Kerberos token, the Windows Desktop SSO Authentication module returns a 401 error back to the browser.

Understanding Typical Business Use Cases

You can use the OpenSSO Enterprise Windows Desktop SSO Authentication module in any environment where end-users are using Windows clients, such as desktop or laptop computers, with SPNEGO-enabled browsers. The most common use of this authentication module is to implement single sign-on within an intranet for Windows client users. Once the user has successfully authenticated against OpenSSO Enterprise, the user can keep the intranet session open all day without having to re-authenticate.

A second business use case is to implement cross-domain single sign-on (CDSSO) or internet single sign-on. CDSSO is not possible with Kerberos authentication alone. But by using the OpenSSO Enterprise SSO Token with the SPNEGO protocol, the SSO Token can be passed to multiple domains without the user having to re-authenticate. This enables a user to enjoy the benefit of single sign-on among trusted domains within an extranet.

Evaluating Benefits and Tradeoffs

The main benefits in using the OpenSSO Enterprise Windows Desktop SSO Authentication module are described in the Understanding Typical Business Use Cases above. There is no alternative that enables you to integrate Kerberos authentication for Windows users with OpenSSO Enterprise.

Configuring Basic Windows Desktop SSO Authentication

The following is an overview of steps you must complete to achieve single sign-on using the OpenSSO Enterprise Windows Desktop SSO Authentication module:

1. Configure a Kerberos Domain Controller in Windows or UNIX.

2. Synchronize OpenSSO Enterprise and the Kerberos Domain Controller Clocks.

3. Configure DNS (Windows Platform Only)

4. Configure a Windows XP Workstation to join the Kerberos Domain Controller Realm if the Kerberos Controller is on UNIX.

5. Configure an Windows XP Workstation to join an Active Directory Domain Controller if the Kerberos Controller is on Windows.

6. Create the Windows XP User's Local Account.

7. Configure an Existing Windows XP Workstation to join an Active Directory Controller Domain if the Kerberos Controller is on Windows.

8. Configure an Existing Window XP Workstation to join a UNIX Kerberos Domain Controller Domain if the Kerberos Controllers is on UNIX.

9. Configure the Browser.

10. Configure the OpenSSO Enterprise Windows Desktop SSO Authentication Module.

The basic configuration instructions described in this document are based on the components described in the following table.

Configuring a Kerberos Domain Controller on Windows or UNIX

The Kerberos Key Distribution Center issues security keys, also called tickets, for authentication. A Kerberos domain controller recognizes the tickets issued by the Key Distribution Center, and extends Kerberos authentication to multiple resources within an intranet. A Kerberos domain controller must be running on a UNIX system, or on a Windows 2000 or Windows 2003 system that supports the Kerberos Domain Controller within the intranet. Microsoft Windows Active Directory and a Windows Domain Controller together form the Windows equivalent of the UNIX Kerberos domain controller. An administrator can use the Active Directory Domain Controller wizard to create a domain controller realm on a Windows server host. Once the administrator completes creates a working Kerberos realm, both Windows and Unix computer systems can participate as clients in the single sign-on environment. The following instructions are included in this document:

For detailed information about installing and configuring Kerberos components, see the Kerberos V5 Installation Guide and the Kerberos V5 Administrator's Guide .

To Configure a UNIX Kerberos Domain Controller

Edit the krb5.conf and kdc.conf files to specify where and how the Kerberos Domain Controller is running.

1. Modify the krb5.conf file.

   For detailed information about the krb5.conf, see the Kerberos V5 Administrator's Guide.

   Example:

   [logging] default = FILE:/var/log/krb5libs.log kdc = FILE:/var/log/krb5kdc.log admin_server = FILE:/var/log/kadmind.log [libdefaults] dns_lookup_realm = false dns_lookup_kdc = false default_keytab_name = /etc/krb5/krb5.keytab default_realm = DEMO.IDENTITY.COM default_tkt_enctypes = des-cbc-md5 default_tgs_enctypes = des-cbc-md5 default_checksum = rsa-md5 kdc_timesync = 0 kdc_default_options = 0x40000010 clockskew = 300 check_delegate = 0 ccache_type = 3 kdc_timeout = 60000 [realms] DEMO.IDENTITY.COM = { kdc = demo1.identity.com:88 admin_server = demo1.identity.com:749 default_domain = identity.com } [domain_realm] .identity.com = DEMO.IDENTITY.COM identity.com = DEMO.IDENTITY.COM [appdefaults] pam = { debug = true ticket_lifetime = 36000 renew_lifetime = 36000d forwardable = true krb4_convert = false }

2. Modify the kdc.conf file.

   For detailed information about the kdc.conf file, see the Kerberos V5 Administrator's Guide.

   Example:

   [kdcdefaults] acl_file = /var/kerberos/krb5kdc/kadm5.acl dict_file = /usr/share/dict/words admin_keytab = /var/kerberos/krb5kdc/kadm5.keytab v4_mode = nopreauth [realms] DEMO.IDENTITY.COM = { master_key_type = des-cbc-crc supported_enctypes = arcfour-hmac:normal arcfour-hmac:norealm arcfourhmac: onlyrealm des3-hmac-sha1:normal des-hmac-sha1:normal des-cbcmd5: normal des-cbc-crc:normal des-cbc-crc:v4 des-cbc-crc:afs3 }

3. Create the Kerberos Domain Controller database using the kdb5_util command.

   This database will store information about all the principals and associated secrets contained in the realm.

   Example:

   /etc/krb5/% kdb5_util create -s Initializing database '/var/krb5/principal' for realm 'DEMO.IDENTITY.COM', master key name 'K/M@DEMO.IDENTITY.COM' You will be prompted for the database Master Password. It is important that you NOT FORGET this password. Enter KDC database master key: Re-enter KDC database master key to verify:

4. Create a new user account.

   1. Add a user principal with kadmin.localcommand.

      # kadmin.local Authenticating as principal admin/admin@DEMO.IDENTITY.COM with password. kadmin.local: addprinc demouser1 WARNING: no policy specified for demouser1@ DEMO.IDENTITY.COM; defaulting to no policy Enter password for principal "demouser1@ DEMO.IDENTITY.COM ": Re-enter password for principal "demouser1@ DEMO.IDENTITY.COM ": Principal "demouser1@ DEMO.IDENTITY.COM " created.

   2. Verify that the user account is added correctly to the database.

      Authenticate the user to the Kerberos domain. Example:

      # kinit demouser1 Password for demouser1@ DEMO.IDENTITY.COM:

   3. Validate the user's Kerberos ticket in the ticket cache.

      # klist Ticket cache: FILE:/tmp/krb5cc_0 Default principal: demouser1@ DEMO.IDENTITY.COM Valid starting Expires Service principal 06/22/07 11:10:16 06/23/07 11:10:16 krbtgt/ DEMO.IDENTITY.COM @ DEMO.IDENTITY.COMM

5. Create a new user account for the Kerberos service user.

   1. Add a service principal for OpenSSO Enterprise.

      Example:

      # kadmin.local: addprinc -randkey HTTP/amserver.identity.com WARNING: no policy specified for HTTP/amserver.identity.com@DEMO.IDENTITY.COM; defaulting to no policy Principal "HTTP/amserver.identity.com@ DEMO.IDENTITY.COM" created.

   2. Generate a keytab file for OpenSSO Enterprise.

      # kadmin.local: ktadd -k amserver1.HTTP.keytab HTTP/amserver.identity.com Entry for principal HTTP/amserver.identity.com with kvno 4, encryption type ArcFour with HMAC/md5 added to keytab WRFILE:amserver1.HTTP.keytab. Entry for principal HTTP/amserver.identity.com with kvno 4, encryption type Triple DES cbc mode with HMAC/sha1 added to keytab WRFILE:amserver1.HTTP.keytab. Entry for principal HTTP/amserver.identity.com with kvno 4, encryption type DES with HMAC/sha1 added to keytab WRFILE:amserver1.HTTP.keytab. Entry for principal HTTP/amserver.identity.com with kvno 4, encryption type DES cbc mode with RSA-MD5 added to keytab WRFILE:amserver1.HTTP.keytab.

   3. Verify that the Kerberos service account is added correctly to the database.

      Use the kinit and klist commands to validate the Kerberos service account. Authenticate the service principal to the Kerberos domain with the keytab file. Example:

      - # kinit ?k ?t amserver1.HTTP.keytab HTTP/amserver.identity.com

   4. Validate the keytab file for the Kerberos service principal.

      Example:

      # klist -k amserver1.HTTP.keytab Keytab name: FILE:amserver1.HTTP.keytab KVNO Principal ------------------------------------------------ 4 HTTP/amserver.identity.com@DEMO.IDENTITY.COM 4 HTTP/amserver.identity.com@DEMO.IDENTITY.COM 4 HTTP/amserver.identity.com@DEMO.IDENTITY.COM 4 HTTP/amserver.identity.com@DEMO.IDENTITY.COM

To Configure Windows Active Directory and Domain Controller

1. Log in as an administrator to the Windows 2000 or 2003 server host.

2. From the Start menu, go to Administrative Tools > Manage Your Server.

   1. On the Manage Your Server wizard, choose Adding Roles to Your Sever.

   2. In the Server Role window, choose Domain Controller (Active Directory).

   3. Accept the default values by clicking Next.

   4. Continue to accept the default values and clicking Next until the Report DNS Issue window is displayed.

   5. This window is displayed when no properly configured DNS exists for Active Directory. Choose “Install and Configure DNS” to proceed to the next window.

   6. Continue to accept the default values and clicking Next until the Summary window is displayed, then click Next.

      The Active Directory Installation wizard is invoked.

3. Install the Active Directory Domain Controller.

   For detailed instructions, see Install Active Directory Domain Services on the Windows Server 2008-Based Member Server

4. Install Windows Support Tools.

   Windows Support Tools contains the ktpass Kerberos tool you need to map a service principal with an Active Directory account. For information about ktpass, see the Ktpass Overview. For detailed instructions on installing Windows Support Tools, see How to install the Windows 2000 Support Tools to a Windows 2000 Server-based computer.

5. Create a new user account.

   1. From the Start menu, go to Programs > Administration Tools.

   2. Choose “Active Directory Users and Computers.”

   3. Enter a user name and password for the new user, and create the user.

   4. Verify that the Kerberos ticket is returned by the Kerberos Authentication Server properly.

      Log into the new domain account from any Windows XP workstation belonging to the domain. You can use the Windows Support Tools to verify that the Kerberos ticket is returned by the Kerberos Authentication Server and cached into the ticket cache. For information about Windows Support Tools, see Windows Support Tools.

6. Create a user account to map to the Kerberos service.

   1. From the Start menu, go to Programs > Administration Tools.

   2. Choose “Active Directory Users and Computers.”

   3. Crete a new user with a name that is meaningful to you.

      In this example, the name is openSSOhost.

   4. Use the ktpass command to associate this user account with a service principal.

      Example:

      C:\Documents and Settings\Administrator>ktpass /pass password /mapuser openSSOhost /princ HTTP/openSSOhost.identity.com@OPENSSOHOST.EXAMPLE.COM +DesOnly /ptype KRB5_NT _PRINCIPAL /Target OPENSSOHOST.EXAMPLE.COM Using legacy password setting method Successfully mapped HTTP/openSSOhost.example.com to openSSOhost. Key created. Account openSSOhost has been set for DES-only encryption.

      If OpenSSO Enterprise is configured with Java version 1.5_ 08 or higher, you don't need to specify the +DesOnly parameter here.

   5. Export the keytab file and copy it to the system where OpenSSO Enterprise is installed.

      Example:

      C:\Documents and Settings\Administrator>ktpass /out demo1.HTTP.keytab /princ HTTP/demo1.identity.com@DEMO.IDENTITY.COM /ptype KRB5_NT_PRINCIPAL /crypto DES-CBC-CRC /Target DEMO.IDENTITY.COM NOTE: creating a keytab but not mapping principal to any user. For the account to work within a Windows domain, the principal must be mapped to an account, either at the domain level (with /mapuser) or locally (using ksetup) If you intend to map HTTP/demo1.identity.com@DEMO.IDENTITY.COM to an account through other means or don't need to map the user, this message can safely be ignored. Key created. Output keytab to demo1.HTTP.keytab: Keytab version: 0x502 keysize 70 HTTP/demo1.identity.com@DEMO.IDENTITY.COM ptype 1 (KRB5_NT_PRINCIPAL) vno 1 etype 0x1 (DES-CBC-CRC) keylength 8 (0xa1c4e6203e3b0d34)

      If OpenSSO Enterprise is configured with Java version 1.5 or higher, you don't need to specify the /crypto DES-CBC-CRC parameter here.

      You can test if this keytab file will work for OpenSSO Enterprise by using the Windows Support Tools, and specifying the /crypto DES-CBC-CRC parameter.

To Synchronize the OpenSSO Enterprise and Kerberos Domain Controller Clocks

Set the clocks on the OpenSSO Enterprise host and on the Kerberos Domain Controller host so that they both display the same time. Without time synchronization, the OpenSSO Enterprise Windows Desktop SSO Authentication module may fail to authenticate to the Kerberos domain.

Configuring the Domain Controller

Depending upon the domain controller you are using, do one of the following:

• Configure DNS Mapping on the Windows Domain Controller

• Configure a Windows XP Workstation to Join the Kerberos Domain Controller Realm

Configuring DNS Mapping on the Windows Domain Controller

• Configure valid forward and reverse DNS mapping for the computer systems in your domain.

  For example OpenSSO Enterprise and the Kerberos Domain Controller must have proper A (IP-Name lookup) and PTR (Reverse IP-Address lookup) records in the DNS database.

• If you use the /etc/hosts file instead of using DNS, all host names point to real, network-accessible IP addresses.

  For example, if the IP address for host1.example.org is 15.168.120.15, then the /etc/hosts file should contain the following entries:

  127.0.0.1 localhost openSSOhost 15.168.120.15 openSSOhost.example.com openSSOhost

Configuring a Windows XP Workstation to Join the Kerberos Domain Controller Realm

A Window XP workstation must be configured to work with a UNIX Kerberos Domain Controller or Windows 2003 Domain Controller. You can add the workstation to the Kerberos or Windows Domain Controller when installing Windows XP, or when modifying the network configuration that already exists on the Window XP workstation.

• To Configure an Windows XP Workstation to Join an Active Directory Domain Controller During Installation

• To Configure an Existing Window XP Workstation to Join a UNIX Kerberos Domain

To Configure an Windows XP Workstation to Join an Active Directory Domain Controller During Installation

1. Follow the instructions in How to install or upgrade to Windows XP to start the Windows XP Setup wizard.

2. Follow the onscreen instructions in the Windows XP Setup wizard until you get to the “Workgroup or Computer Domain” window.

   • Enter the Active Directory domain you want the Windows XP workstation to join, then click Next.

   • If the Windows XP Setup wizard cannot find the domain controller for this domain, enter the IP address of the domain controller in the Internet Protocol (TCP/IP) Properties window.

     1. From the Start menu, choose Control Panel. Go to Network and Internet Connections > Network Connections.

     2. Right-click the local area connection that you want to modify, and then click Properties.

     3. On the General tab, in the “This connection uses the following items list,” click Internet Protocol (TCP/IP), and then click Properties.

   For more information, see How to troubleshoot TCP/IP connectivity with Windows XP.

3. Continue to follow the onscreen instructions in the Windows XP Setup wizard until all steps are completed.

To Create the Windows XP User's Local Account

Before you begin, be sure the user has already been added to the Active Directory domain.

Follow the instructions for creating the user's local account in How to create and configure user accounts in Windows XP.

To Configure an Existing Windows XP Workstation to Join an Active Directory Controller

Follow the instructions in

How to change a computer name, join a domain, and add a computer description in Windows XP or in Windows Server 2003.

To Configure an Existing Window XP Workstation to Join a UNIX Kerberos Domain

Once the host account is added successfully, you can change the network configuration for the Window XP workstation. You must be logged into Windows XP as an administrator to run the following commands.

1. Run the kadmin.local command to add the host account for Window XP workstation first on the UNIX side.

   Example:

   kadmin.local addprinc -pw password -policy hosts -e des-cbc-crc:normal host/demoxp. openSSOhost.example.com

2. Run the ksetup command.

   ksetup /SetRealm OPENSSOHOST.EXAMPLE.COM ksetup /AddKDC openSSOhost.example.com

3. Set the local computer system password.

   This password must match the password you specified when you ran kadmin.local in step 1.

   ksetup /SetComputerPassword password

4. Set up user mapping.

   Example:

   ksetup /mapuser * *

Configuring the Browser

Any client browser used in the intranet must be configured to work with the Kerberos Domain Controller.

To Configure Microsoft Internet Explorer

1. In the Tool menu, go to Internet Options > Security.

2. Choose Local Intranet, and then click Site.

3. Mark the “Automatically detect intra network” checkbox, and then click Advanced.

4. Add the OpenSSO Enterprise URL to the Websites list if the URL is not already on the list.

   Example: http:/openSSOhost.example.com

   For pre-6.0 Internet Explorer versions, be sure the Identity Server is in the browser's intranet zone and that native Windows Authentication is enabled. For more information, see Enabling Windows Authentication.

To Configure Mozilla or FireFox

1. Open the Firefox browser, and enter about:config in the address bar.

   This will display a large number of configuration entries, called Preference Names, for Firefox .

2. Double-click the Preference Name network.negotiate-auth.trusted-uris.

3. Enter http://, https://.

To Configure Apple Safari

Safari has built-in native support for Kerberos single sign on and no configuration is needed.

To Configure the OpenSSO Enterprise Windows Desktop SSO Authentication Module

1. Copy the keytab files you created in the sectionTo Configure a UNIX Kerberos Domain Controller or the section To Configure Windows Active Directory and Domain Controller.

   Place the copied files in the OpenSSO Enterprise host, in a directory such as /etc/opt/SUNWam/config.

2. Log into the OpenSSO Enterprise administration console as amadmin.

3. Go to Access Control > Default Realm > Authentication.

4. In the Module Instances page, click New.

5. Enter a name for the new login module, and then select Windows Desktop SSO. Click OK.

6. In the Module Instances page, click the name of the new login module and provide the following information:

   Service Principal

   HTTP/ openSSOhost.example.com@EXAMPLE.COM

   Keytab File Name

   /etc/opt/SUNWam/config/openSSOhost.HTTP.keytab

   Kerberos Realm

   OPENSSOHOST.EXAMPLE.COM

   Kerberos Server Name

   Kerberos.example.com

   If multiple Kerberos Domain Controllers exist for failover purposes, all Kerberos Domain Controllers can be set using a colon (:) as the separator.

   Return Principal with Domain Name

   False

   Authentication Level

   0

7. Restart the OpenSSO Enterprise server.

   • If OpenSSO Enterprise is deployed on IBM Websphere, then Keytab File Name has to be specified in FILE:// format. Example: FILE:///etc/opt/SUNWam/config/openSSOhost.HTTP.keytab.

   • If OpenSSO Enterprise is deployed on IBM Websphere, the keytab file has to use the DES-CBC-MD5 crypto option. After restarting the server, the administrator can access the module with a browser pointing to this URL: http://openSSOhost.example.com/amserver/UI/Login?module=WinSSO.The browser should no longer prompt the user for userid and password.

Complex Configurations

Once you've set up and verified that basic Windows Desktop SSO Authentication works, you can deploy the module in more complex configurations:

• Chaining Multiple Authentication Modules

• To Use the Windows Desktop SSO Authentication Module with a Load Balancer

• Using the Windows Desktop SSO Authentication Module with Multiple Kerberos Domain Controllers

Chaining Multiple Authentication Modules

You can use the administration console to chain multiple authentication modules to work together as single a authentication service . When multiple authentication modules are chained together, the end-user must authenticate at least one of authentication modules in defined in the authentication group. Or the user may be required to authenticate to all of the modules, depending upon on how authentication chaining is configured.

The following instructions demonstrate chaining the DataStore Authentication module and Windows Desktop SSO Authentication module to work together as an authentication service. Using this configuration, an end-user can access OpenSSO Enterprise using the authentication service name. Example: http://openSSO.example.com/amserver/UI/Login?service=WinSSOService.

To Configure Authentication Chaining

1. Log in to the OpenSSO Enterprise admnistration console as amadmin.

2. Go to Access Control > Default Realm > Authentication.

3. Define a new instance of the Windows Desktop SSO Authentication module.

4. Go to Access Control? > Default Realm > Authentication.

5. Define new instance of Authentication Chaining.

   1. Click the New button for Authentication Chaining.

      Provide a name for this chain, and then click OK. Example name: WinSSOService.

   2. Click Add, and then choose the first authentication module to be executed in this chain.

      In this example, Windows Desktop SSO is the first module to be executed.

   3. For Criteria, choose Sufficient.

   4. Click Add, and then choose the next authentication module in the chain to be executed.

      In this example, Data Store is the next module to be executed.

   5. For Criteria, choose Sufficient.

6. Go to Access Control > Default Realm> Authentication, and save this new chaining configuration.

To Test Authentication Chaining

1. Log in to a Windows XP Domain Controller and start any browser that is enabled for the SPNEGO protocol.

2. Go to the OpenSSO Enterprise URL configured with the authentication service name.

   Example : http://am.demo.identity.com/amserver/UI/Login?service=WinSSOService.

   If a user can log into Windows XP Domain Controller successfully, the browser sends a Kerberos ticket to the OpenSSO Enterprise server, and the user is successfully authenticated using the Windows Desktop SSO Authentication module. .

   If the user cannot authenticate to the first authentication module, then OpenSSO Enterprise prompts for user name and password and tries to authenticate using the Data Store Authentication module. If authentication fails, then the administrator should troubleshoot the authentication failure. For a short list of solutions for the most common error messages related to Windows Desktop SSO Authentication, see Troubleshooting Windows Desktop SSO Authentication Issues.

To Use the Windows Desktop SSO Authentication Module with a Load Balancer

All OpenSSO Enterprise authentication modules, including the Windows Desktop SSO Authentication module, can be accessed through a load balancer. The Windows Desktop SSO Authentication module requires some special configuration.

1. Create an Active Directory domain account in Windows 2003 or in the Kerberos service principal.

2. When you generate the keytab file for he Windows Desktop SSO Authentication, you have to specify the load balancer FQDN.

   Example: HTTP://opensso-lb.example.com. If you don't specify the fully-qualified domain name, authentication will fail.

3. Copy the keytab file to all OpenSSO Enterprise servers, and put place in under the same directory in each server.

   Example location: /etc/ SUNWam/config.

4. Create a new Windows Desktop SSO Authentication module and Configure it with the newly copied keytab file.

5. Restart all the OpenSSO Enterprise servers and test the new module through the load balancer.

Using the Windows Desktop SSO Authentication Module with Multiple Kerberos Domain Controllers

You can configure the Windows Desktop SSO authentication module to work with multiple Kerberos Domain Controllers. This is useful for deploying a failover Kerberos server.

When you configure the Windows Desktop SSO authentication module with a keytab file from one of the trusted domain controllers, any user belonging to any of the trusted domains can authenticate through the Windows Desktop SSO authentication module. Administrators can configure and manage trust relationships in environments containing multiple Active Directories.

To make the Windows domain controller a part of the trusted nodes, and to make the Windows domain controller work with the Windows Desktop SSO authentication module, the following conditions must be met:

• You must use Windows 2003 or a later version.

• The domain controller functional level must be set at Windows Server 2003.

• Trust must be configured.

Trust configuration is beyond the scope of this document. The following links provide useful related information:

• Configuring KDC Servers in System Administration Guide: Security Services

• Configuring Cross-Realm Authentication in System Administration Guide: Security Services

The following procedures will help you navigate to the configuration areas of the Windows domain controller:

• To Locate the Trust Configuration Window

• To Promote the Domain Controller Functional Level

To Locate the Trust Configuration Window

1. From the Windows Start menu, choose Administrative Tools > Active Directory Domains and Trusts.

2. In the Active Directory Domains and Trusts window, right-click the domain name and click Properties.

3. Click the Trusts tab.

4. Click New.

   

To Promote the Domain Controller Functional Level

1. From the Windows Start menu, go to Administrative Tools > Active Directory Domains and Trusts.

2. In the Active Directory Domains and Trusts window, right-click the domain name, and choose the Raise Domain Functional Level menu.

3. Choose windows Server 2003 as the new functional level.

   

Using the Debugging Tools

After you configure the UNIX Kerberos Domain Controller or the and Windows 2003 Active Directory Domain Contoller are configured, you can test them with various tools to validate that they are configured properly.

Network Identity Manager

Network Identity Manager is a graphical tool designed by MIT to simplify the management of network identities and their credentials. When Network Identity Manger is used with Kerberos v5, each network identity is a unique Kerberos principal name, and the credentials are Kerberos version 5 tickets. Network Identity Manger enables you to manage any Kerberos ticket returned from a Kerberos Domain Controller. For detailed information, see the Network Identity Manager 1.3.1 User Documentation.

kinit

An administrator can obtain an initial Kerberos ticket for a specified principal using the kinit command, and then cache the initial ticket into the ticket cache. Once kinit is executed successfully, any existing tickets for the principal are overwritten. You can use the kinit command to verify that a generated keytab file is working with the Kerberos and Active Directory Domain Controllers. Usage:

kinit [-5] [-4] [-V] [-l lifetime] [-s start_time]
[-r renewable_life][-f | -F] [-p | -P] [-A] [-v] [-R] [-k [-t keytab_file]] 
[-c cachename] [-S service_name] [principal] 

klist

Theklist command displays the contents of a Kerberos credentials cache or key table. You can use the klist command to verifty that the generated keytab file has the right principal for OpenSSO Enterprise. Usage:

klist [-5] [-4] [-e] [[-c] [-f] [-s] [-a [-n]]] [-k [-t] [-K]] [name] -5

ktpass

You can use the ktpass command to configure services running on UNIX systems to work with with service instance accounts in Active Directory. You can also use the ktpass command to generate Kerberos keytab files for services. Before you map an Active Directory user account with OpenSSO Enterprise, first check the Java version that is configured for OpenSSO. If the Java version is 1.5_08 or higher, you can generate the Kerberos keytab file using all default values for account encryption and cryptosystem. Java versions 1.5_08 or higher support the RC4-HMAC crypto system that is default for the Windows Kerberos Domain Controller. If the Java version is lower than 1.5_08, you have must use the DesOnly option. Options:

ksetup

Use these commands to create the configuration entries in the Windows host's registry for the Kerberos realm. The registry entries function similarly to the krb5.conf file used by Unix Kerberos to define the Kerberos Domain Controller information for Kerberos realms.

Troubleshooting Windows Desktop SSO Authentication Issues

If you have trouble accessing the Windows Desktop SSO Authentication module, first inspect the debug log files amAuthWindowsDesktopSSO or amAuth file. Errors or exceptions that users may encounter when Windows Desktop SSO Authentication doesn't work properly include the following:

• Error Message: Unauthorized Access

• Error Message: Service Login Error

• LoginException: Clock skew too great

• LoginException: kdc.example.com

• LoginException: Client not found in Kerberos database

• GSSException: Failure unspecified at GSS-API level

• Exception: Pre-authentication information was invalid

• Error Message: Cannot establish context

• Error Message: Authentication failed

• Error Message: User has no profile in this organization

• Authentication Doesn't Work with Load Balancer

Error Message: Unauthorized Access

The problem occurs when you try to access Windows Desktop SSO Authentication module directly. Example URL: http://openSSOhost.domain/UI/Login?module=WinSSO. An “Unauthorized Access” message is displayed. The message may also indicate that “The Kerberos token is not valid.” The following is displayed in the server-side debug log amAuthWindowsDesktopSSO:

06/20/2007 11:06:03:974 AM PDT: Thread[WebContainer : 1,5,main] 
WindowsDesktopSSO params: 
principal: HTTP/veet.red.iplanet.com@RED.IPLANET.COM 
keytab file:///tmp/keytab/veet.HTTP.keytab 
realm : RED.IPLANET.COM kdc 
server: cerberus.red.iplanet.com domain 
principal: false 
auth level: 0 
06/20/2007 11:06:03:977 AM PDT: Thread[WebContainer : 1,5,main] 
Retrieved config params from cache. 
06/20/2007 11:06:04:000 AM PDT: Thread[WebContainer : 1,5,main] 
SPNEGO token: 4e 54 4c 4d 53 53 50 00 01 00 00 00 07 82 08 a2 00 
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 05 01 28 0a 00 00 00 0f 
06/20/2007 11:06:04:000 AM PDT: Thread[WebContainer : 1,5,main] 
token tag:4e 06/20/2007 11:06:04:006 AM PDT: Thread[WebContainer : 1,5,main] 
kerberos token is not valid.

• Be sure that the browser is configured correctly.

• Be sure that your XP domain login has the Kerberos ticket from the Kerberos Domain Controller.

Error Message: Service Login Error

When attempting the log in, the message “LoginException: Unable to obtain password from user” is displayed. The following is displayed in the server-side debug log amAuthWindowsDesktopSSO:

06/20/2007 01:08:08:614 PM PDT: Thread[service-j2ee,5,main] 
ERROR: Service Login 
Error: 06/20/2007 01:08:08:614 PM PDT: Thread[service-j2ee,5,main] 
Stack trace: javax.security.auth.login.LoginException: 
Unable to obtain password from user at com.sun.security.auth.module.
Krb5LoginModule.promptForPass(Krb5LoginM odule.java:745) 
at com.sun.security.auth.module.Krb5LoginModule.attemptAuthentication
(Kr b5LoginModule.java:624) at com.sun.security.auth.module.
Krb5LoginModule.login(Krb5LoginModule.ja va:512) 
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) ..... 

• Be sure the appropriate cryptosystem is being used for generating the keytab file.

• Be sure the appropriate version of Java is configured for the OpenSSO Enterprise server.

• Be sure the configured service principal is identical to the principal in the keytab file. You can use klist command view the keytab file information.

LoginException: Clock skew too great

The following is displayed in the server-side debug log amAuthWindowsDesktopSSO :

ERROR: Service Login Error: 06/20/2007 02:04:33:181 PM PDT: 
Thread[service-j2ee,5,main] Stack trace: javax.security.auth.login.LoginException: 
Clock skew too great (37) 
at com.sun.security.auth.module.Krb5LoginModule.attemptAuthentication
(Kr b5LoginModule.java:696)
at com.sun.security.auth.module.Krb5LoginModule.login(Krb5LoginModule.ja va:542) 
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) 
at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl. java:39) 
at sun.reflect.DelegatingMethodAccessorImpl.invoke
(DelegatingMethodAcces sorImpl.java:25) 
at java.lang.reflect.Method.invoke(Method.java:585) 
at javax.security.auth.login.LoginContext.invoke(LoginContext.java:769) 
at javax.security.auth.login.LoginContext.access$000(LoginContext.java:1 86)  

Be sure that the clocks of OpenSSO Enterprise server host and the Kerberos or Active Directory Domain Controller host are synchronized properly.

LoginException: kdc.example.com

The following will be display in the server-side debug log amAuthWindowsDesktopSSO :

ERROR: Service Login Error:
06/20/2007 04:42:16:265 PM PDT: Thread[service-j2ee,5,main]Stack trace:
javax.security.auth.login.LoginException: kdc.red.iplanet.com: kdc.red.iplanet.com
at com.sun.security.auth.module.Krb5LoginModule.attemptAuthentication
 (Krb5LoginModule.java:700)
at com.sun.security.auth.module.Krb5LoginModule.login(Krb5LoginModule.java:542)

Be sure the Kerberos Server Name is configured using the FQDN for the Kerberos Domain Controller host. Use the ping command to verify that the Kerberos Domain Controller host is accessible from the OpenSSO host.

LoginException: Client not found in Kerberos database

The following will be displayed in the server-side debug log amAuthWindowsDesktopSSO :

ERROR: Service Login Error:
02/24/2009 11:17:37:212 PM JST: Thread[service-j2ee-1,5,main]
Stack trace:
javax.security.auth.login.LoginException: Client not found in Kerberos database (6)
at
com.sun.security.auth.module.Krb5LoginModule.attemptAuthentication(Krb5LoginModule.jav
a:696)
at com.sun.security.auth.module.Krb5LoginModule.login(Krb5LoginModule.java:542)
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
at
sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
at java.lang.reflect.Method.invoke(Method.java:585)

Test the keytab file with kinit command. The keytab file may have been generated or mapped improperly.

GSSException: Failure unspecified at GSS-API level

The following is displayed in the server-side debug log amAuth:

09/14/2005 05:41:58:182 PM SGT: 
Thread[service-j2ee-3,5,main]Exception
com.sun.identity.authentication.spi.AuthLoginException(1):null
com.sun.identity.authentication.spi.AuthLoginException(2):null
java.security.PrivilegedActionException(3):null
java.security.PrivilegedActionException: GSSException: Failure unspecified at
GSS-API level (Mechanism level: Integrity check on decrypted field failed(31))
at java.security.AccessController.doPrivileged(NativeMethod)
at javax.security.auth.Subject.doAs(Subject.java:396)
at com.sun.identity.authentication.modules.windowsdesktopsso.WindowsDesktopSSO.process
   (WindowsDesktopSSO.java:156)
at com.sun.identity.authentication.spi.AMLoginModule.wrapProcess
   (AMLoginModule.java:723)
at com.sun.identity.authentication.spi.AMLoginModule.login(AMLoginModule.java:871)
at sun.reflect.NativeMethodAccessorImpl.invoke0(NativeMethod) 
at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
at sun.reflect.DelegatingMethodAccessorImpl.invoke
  (DelegatingMethodAccessorImpl.java:25)
at java.lang.reflect.Method.invoke(Method.java:585)
at com.sun.identity.authentication.jaas.LoginContext.invoke(LoginContext.java:215)

JDK1.5_08 and higher support RC4-HMAC, and earlier JDK versions support 3DES and DES enctypes only. Be sure to select +DesOnly encryption for mapping the account with the service principal in the Windows Kerberos Domain Controller. Also, be sure to use DES-CBC-CRC or DES-CBC-MD5 for cryptosystem when generating the service principal keytab file

Be sure the appropriate crypto system is used for generating keytab file. Be sure the appropriate version of Java is configured for OpenSSO Server.

Exception: Pre-authentication information was invalid

Java may not be handling the Kerberospre-auth correctly. This can occur if the principal name does not match what is stored in Active Directory, and what the principal name was when the password was last changed. This mismatch is not a problem for Active Directory, but it is a problem for Kerberos or a renamed account where the password has not been changed. Java 1.6 is reported to have a fix for this problem. The fix will accept the pre-authentication hint from the Kerberos Domain Controller as to what "salt" to use when doing the string to key function. The "salt" is derived from the principal name at the time the password was changed. Older Java versions assumed they know the salt and tried to skip the first step in the pre-authentication.

Error Message: Cannot establish context

See the information at the end of the procedure To Configure the OpenSSO Enterprise Windows Desktop SSO Authentication Module about using IBM WebSphere.

Error Message: Authentication failed

The following message is displayed in the server-side debug log amAuthWindowsDesktopSSO :

06/20/2007 03:49:20:704 PM PDT: Thread[service-j2ee,5,main]
WindowsDesktopSSO params:
principal: HTTP/am-v1280-01.red.iplanet.com@RED.IPLANET.COM
keytab file: /tmp/keytab/wsso.HTTP.keytab
realm : RED.IPLANET.COM
kdc server: cerberus.red.iplanet.com
domain principal: false
auth level: 0
06/20/2007 03:49:20:704 PM PDT: Thread[service-j2ee,5,main]
Init WindowsDesktopSSO.

This should not happen often. Be sure the keytab file uses the same filename and directory as specified in the user account.

Error Message: User has no profile in this organization

Kerberos Authentication is successful, but OpenSSO Enterprise cannot find the user profile. This is a configuration issue. Be sure the user exists in the user repository.

Authentication Doesn't Work with Load Balancer

The Windows Desktop SSO Authentication module worked fine. Then it stopped working after the OpenSSO Enterprise server was configured as a server in a site configuration with a load balancer. .

The following message trace is displayed in the server-side debug log amAuthWindowsDesktopSSO:

......
02 a6 ff 1d 1c 3c e2 dc d4 89 66 b0 70 dd 6b b0
c1 a4 69 bd 29 29 54 05 04 e8 75
06/25/2007 09:13:56:559 AM PDT: Thread[service-j2ee,5,main]
In authenticationToken ...
06/25/2007 09:13:56:561 AM PDT: Thread[service-j2ee,5,main]
Context created.
06/25/2007 09:13:56:565 AM PDT: Thread[service-j2ee,5,main]
Authentication failed with GSSException.

You will also see a bigger Kerberos token than a normal token. Be sure the defined principal for the OpenSSO Enterprise server has load balancer fully-qualified domain name (FQDN). Example: HTTP/amlb. openSSOhost.example.com.