Implementing Windows desktop single sign-on for InfoSphere Business Glossary

Configure SPNEGO-based authentication for InfoSphere Business Glossary, Version 9.1

IBM® InfoSphere® Business Glossary 9.1 uses the Simple and Protected GSS-API Notification (SPNEGO) support provided by WebSphere® Application Server to enable configuration of a seamless single sign-on environment for InfoSphere Business Glossary and InfoSphere Business Glossary Anywhere users. Deploying this feature requires correct configuration of several interlocking components, including some synchronization details that might not be immediately apparent. This article provides a step-by-step walkthrough of the configuration for a scenario that includes using a Microsoft™ Active Directory domain controller for the external user registry, Windows™ Server 2008 on the WebSphere Application Server tier and for the domain controller, and Windows 7 on the client tier. The article also includes troubleshooting tips and references for some common pitfalls.

Share:

Srinivasa Rao Kuchi (srinukuchi@in.ibm.com), System Engineer, IBM

Photo of Srinivasa Rao KuchiSrinivasa Rao Kuchi is a Java developer and has extensive experience with Java web and enterprise applications. He has broad exposure to many different IBM products, and for the past 2.5 years he has worked on InfoSphere Information Server. He is an Oracle Certified Professional Java SE6 Programmer.



Nancy L. Navarro (nancyn@il.ibm.com), Advisory Information Developer, IBM

Photo of Nancy NavarroNancy Navarro is an Advisory Information Developer for IBM who has worked on InfoSphere Information Server and InfoSphere Business Glossary products for the past 4 years. She has extensive information development experience for IBM and other companies.



Subhrata Parichha (psubhrat@in.ibm.com), Advisory Software Engineer, IBM

Photo of Subhrata ParichhaSubhrata Parichha is an IBM Senior Quality Assurance Engineer and has worked on IBM InfoSphere Information Server since 2008. She has worked in the IBM India Software Lab for twelve years and has wide exposure to different IBM products. She is a Certified Scrum Master and currently leads an InfoSphere Information Server QA team.



Ilan Prager (ilanp@il.ibm.com.ibm.com), Technical Architect, IBM

Photo of Ilan PragerIlan Prager is the Technical Architect for the IBM Business Glossary and IBM Metadata Workbench. With over 12 years of experience in software architecture and development, Ilan has led the design and implementation for a wide range of end to end enterprise solutions and products, incorporating expertise in databases, middleware, and web technologies.



21 February 2013

Also available in Chinese

Introduction

With a feature introduced in IBM InfoSphere Information Server 9.1, you can configure IBM InfoSphere Information Server to automatically log users into InfoSphere Business Glossary or InfoSphere Business Glossary Anywhere when they log into the Microsoft Windows desktop—without having to authenticate.

You accomplish this using the Simple and Protected GSS-API Negotiation Mechanism (SPNEGO) protocol. SPNEGO is a standard specification that is used to securely negotiate and authenticate HTTP requests. (See Resources for a link to the SPNEGO specification.) Configuration and support of SPNEGO occurs in WebSphere Application Server, which underlies InfoSphere Information Server.

When WebSphere Application Server global and application security are enabled, and SPNEGO web authentication is enabled, SPNEGO is initialized when processing a first inbound HTTP request. The web authenticator component then interacts with SPNEGO, which is defined and enabled in the security configuration repository. When the criterion is met, SPNEGO is responsible for authenticating access to the secured resource that is identified in the HTTP request.


Scenario

In the scenario described in this article, the secured resource is InfoSphere Business Glossary. Security is provided by Microsoft Active Directory, configured as an external user registry to InfoSphere Information Server. (See Resources for a link to information about how to configure an external user registry.) Active Directory uses the MIT-developed Kerberos protocol as its authentication underpinning.

In this scenario, when a user logs in to Windows, he is really logging in to the Active Directory domain controller with an identity known to Active Directory. The user then accesses InfoSphere Business Glossary, and the user’s identity is propagated to WebSphere Application Server. This identity is mapped, in turn, to Active Directory.


Prerequisites

The following software and hardware is required for this scenario:

  • One computer running Microsoft Windows Server with Active Directory enabled
  • One computer running InfoSphere Information Server, with InfoSphere Business Glossary installed
  • One client computer running Microsoft Windows

The client computer must have connectivity to both the computer that is running Active Directory and to the computer that is running InfoSphere Information Server. The computer that is running InfoSphere Information Server must have connectivity to the computer that is running Active Directory.

Figure 1. System topology
Depicts 3 systems as described in prerequistes, with arrows to indicate connectivity between each system and the other two

Overview of the steps

To implement the scenario, the following steps are required:

  1. Create a Kerberos Service Principal name (SPN) and keytab file on the Microsoft Active Directory domain controller.
  2. Create a Kerberos configuration file.
  3. Configure WebSphere Application Server to use SPNEGO.
  4. Configure Information Server to use Lightweight Directory Access Protocol (LDAP).
  5. Configure the web browser.
  6. Configure InfoSphere Business Glossary Anywhere.

(Note: Either step 5 or step 6 is required, depending on whether the user will access InfoSphere Business Glossary from a web browser or from InfoSphere Business Glossary Anywhere.)


Step 1: Creating a Kerberos SPN and keytab file on the Microsoft Active Directory domain controller

In this step, you will create a Kerberos SPN and keytab file.

  1. First, you must create an Active Directory user account that maps to the Kerberos SPN name for WebSphere Application Server. A service principal name is the name used by a Kerberos client to uniquely identify an instance of a service for a given Kerberos target computer. To do this, perform the following steps:
    1. Log in as administrator to the Windows Server system that serves as the Active Directory domain controller.
    2. Invoke the Microsoft Active Directory users and computers snap-in.
    3. Click Start > Run.
    4. Type the following command: dsa.msc /server=localhost, then click OK.
    5. Create a user account for WebSphere Application Server. In this scenario, an account iis_sso is created.
  2. Next, you must create the Kerberos keytab file. To do this, use the –ktpass command, while you are still on the Active Directory domain controller system. An example of the command is:
    C:\>ktpass -out c:\iis_sso.keytab -princ HTTP/was_host@JKENTERPRISES
    -mapUser iis_sso –mapop set -pass * -crypto RC4-HMAC-NT

    where:

    iis_sso.keytab is the name of the keytab file.

    was_host is the name of the computer that hosts WebSphere Application Server.

    JKENTERPRISES is the Active Directory domain.

    iis_sso is the Active Directory user account created in Step 1.

    -mapop set sets the value for Data Encryption Standard (DES)-only encryption for the specified local user name.

    -pass * specifies that you will be prompted for a password.

    -crypto RC4-HMAC-NT specifies 128-bit encryption.

    See Resources for a link to information on the parameters of the ktpass command.

    Listing 1 shows the output of the ktpass command.

    Listing 1. ktpass command output
    Targeting domain controller: ad_host.jkenterprises.com
    Using legacy password setting method
    Successfully mapped HTTP/was_host.JKENTERPRISES.com to iis_sso.
    Type the password for HTTP/was_host.JKENTERPRISES.com:
    Type the password again to confirm:
    WARNING: pType and account type do not match. This might cause problems.
    Key created.
    Output keytab to C:\iis_sso.keytab:
    Keytab version: 0x502
    keysize 71 HTTP/xxxx@JKENTERPRISES.COM ptype 0 <KRB5_NT_UNKNOWN >vno8
    etype 0x17 (RC4-HMAC) keylength 16 (0xf6dc56b4c038eb083f5689c837e3783f)
  3. Use the setspn –l command to verify the SPN. The output should reflect what was entered in the ktpass command. For example:
     C:\>setspn.exe -l iis_sso
  4. You might also want to verify the SPN user account by using the assigned user, in this case iis_sso , to log in to the Windows client computer with the password assigned to it in step 1 of this section.

Step 2: Creating a Kerberos configuration file for WebSphere Application Server

In this step, you will create the Kerberos configuration file.

  1. Log in as administrator to the system that hosts WebSphere Application Server.
  2. Copy the keytab file from the Active Directory server to the computer that is running WebSphere Application Server. In this scenario, copy the file to c:\iis_sso.keytab on the WebSphere Application Server system.
  3. Use the wsadmin command to create a Kerberos configuration file.
    1. Change to the directory containing the wsadmin executable:
      cd c:\IBM\WebSphere\AppServer\bin\
    2. Type wsadmin and press Enter to start the wsadmin command.
    3. Enter the WebSphere Administrative Server administrator user name and password when prompted.
    4. Type a command such as the following at the wsadmin> prompt:
      $AdminTask createKrbConfigFile {-krbPath C:\krb5.conf -realm JKENTERPRISES
      -kdcHost ad_host  -dns  ibm.com|was_host –keytabPath c:\iis_sso.keytab

      This creates the text file krb5.conf.


Step 3: Configuring WebSphere Application Server to use SPNEGO

To use SPNEGO, you must configure WebSphere Application Server.

  1. Log in to the WebSphere Application Server Integrated Solutions Console as administrator. (In this scenario, the user name is was_admin.)
  2. Configure Active Directory and LDAP: In the left pane, select Security > Global Security.
  3. In the right pane (Global Security page), under the User Account Repository section, Available realm definitions, select Standalone LDAP registry from the pull-down menu.
    Figure 2. Configuring the user registry to be Standalone LDAP
    Screen capture of WebSphere Application Server Global Security page, with Standalone LDAP registry circled

    See larger image.

  4. Click Configure, located next to the Standalone LDAP registry selection.
  5. Determine the full distinguished name (DN) and password of the account you configured as an Active Directory user in step 1.

    For example, if the Active Directory administrator creates an account iis_sso in the Users folder of the Active Directory Users and Computers Windows control panel and the DNS domain is jkenterprises.com, the resulting DN has the following structure:

    cn=iis_sso, cn=users, dc=jkenterprises, dc=com

  6. In the Standalone LDAP Registry page, configure the following items:
    1. Primary administrative user name: This is the Active Directory user name you configured in step 1. This user name is used to access the administrative console. It is also used by the wsadmin command.
    2. Host: Specify the domain name service (DNS) name of the computer that is running Microsoft Active Directory. For example: ad_server.jkenterprises.com.
    3. Base Distinguished Name (DN): Specify the domain components of the DN of the account that is entered as the Primary administrative user name. For example: dc=jkenterprises, dc=com.
    4. Bind Distinguished Name: Specify the full distinguished name of the account that is entered as the Primary administrative user name. For example: CN=iis_sso, CN=users, DC=jkenterprises, DC=com.
    5. Bind Password: Specify the password of the account that is entered as the Primary administrative user name.
    Figure 3. Configuring Standalone LDAP registry values
    Screen capture of WebSphere Application Server properties page, with configurable items circled

    See larger image.

  7. Click Test connection at the top of the page to test the connection between Active Directory and WebSphere Application Server.
  8. If the test is successful, click OK.
  9. Renavigate to the Global Security page. On this page, make sure that Standalone LDAP registry is selected, and click Set as current.
    Figure 4. Setting the LDAP registry as current
    Screen capture of WebSphere Application Server Global Security page, with Standalone LDAP registry circled

    See larger image.

  10. Click Apply.
  11. Click Save at the top of the page to save to the master configuration.
  12. From the Global security page, under Administrative security, select Administrative user roles.
  13. Click Add and select a new Administrative user from the users in the Active Directory user realm. This user should be a user who will also have InfoSphere Information Server administrative privileges. For this scenario, the user is was_iis_admin.
  14. Configure SPNEGO web authentication:
    1. Navigate to the Global security page. Under Authentication, select Web and SIP security. Then select SPNEGO web authentication.
      Figure 5. Selecting SPNEGO web authentication
      Screen capture of WebSphere Application Server Global Security page, with Standalone LDAP registry circled

      See larger image.

    2. On the SPNEGO web authentication page, use the following configuration parameters under General properties:
      1. Make sure that Use the alias host name of the application server is selected.
      2. Select Dynamically update SPNEGO, Enable SPNEGO, and Allow fall back to application authentication mechanism.
      3. Enter the full path of the Kerberos configuration file where indicated.
      4. Enter the full path of the keytab file where indicated.
      Figure 6. Configuring the SPNEGO web authentication page
      Screen capture of WebSphere Application Server SPNEGO web authentication page with values entered

      See larger image.

    3. Under SPNEGO Filters, click New.
    4. Enter the following in the filter criteria field:
      request-url^=bg/services|bg/secure;request-url!=noSPNEGO
    5. Select Trim Kerberos realm name from principal name.
      Figure 7. Configuring SPNEGO web authentication filter properties
      Screen capture of WebSphere Application Server SPNEGO web authentication properties page

      See larger image.

    6. Click OK, and then click Save to the master configuration.
  15. Renavigate to the Global security page. Make sure that in the Authentication section, Authentications mechanisms and expiration is set to LPTA. Do not select Kerberos and LPTA or SWAM (Deprecated).
  16. Run the AppServerAdmin.bat command to update InfoSphere Information Server with the new administrative user.
    1. Navigate to the directory IBM/Information Server/ASBServer/bin.
    2. Enter the following command:
      AppServerAdmin.bat –was –user was_iis_admin -password password

      where:

      was_iis_admin is replaced with the user name you configured as a WebSphere Application Server administrator in step 4 of this section.

      password is the password for that user.

  17. Stop and restart WebSphere Application Server so that the changes take effect.

Step 4: Configuring LDAP registry members as InfoSphere Information Server users

To enable InfoSphere Information Server to recognize the users in the LDAP registry, you can configure their InfoSphere Information Server security roles. To do this:

  1. Enter information_server_host/ibm/iis/console in your web browser.

    where:

    information_server_host is the host name or IP address of the computer that hosts InfoSphere Information Server.

  2. Click the Administration tab.
  3. Select Users and groups > Groups. A list of possible groups is displayed.
  4. Select the check box next to the group that corresponds to the LDAP registry that is configured in Active Directory. Optionally, you can enter a meaningful name for the group.
    Figure 8. Selecting a group in InfoSphere Information Server
    Screen capture of InfoSphere Information Server console, selecting a group to work with page, with group selected

    See larger image.

  5. Click Open Group.
  6. Select the appropriate security roles, then click Save.
    Figure 9. Configuring roles in InfoSphere Information Server
    Configuring security roles in InfoSphere Information Server for the group representing the Active Directory registry

    See larger image.


Step 5: Configuring web browsers

If user access to InfoSphere Business Glossary will be from a web browser (as opposed to using InfoSphere Business Glossary Anywhere), a browser on each Windows client must be configured to use SPNEGO. Configuration steps differ, depending on the type of browser.

Internet Explorer

Complete the following steps to ensure that each Internet Explorer browser is enabled to perform SPNEGO authentication.

  1. Log in to the client Windows computer as a user in the Active Directory domain.
  2. Open Internet Explorer.
  3. In the Internet Explorer window, click Tools > Internet Options.
  4. Select the Security tab.
  5. Select Local intranet and click Sites.
  6. In the Local intranet window, ensure that the check box for Automatically detect intranet network or Include all local (intranet) not listed in other zones is selected, then click Advanced.

    (If Automatically detect intranet network is enabled, then Include all local (intranet) not listed in other zones is enabled by default.)

    Figure 10. Configuring Internet Explorer, specifying zones to include
    Screen capture of Internet Explorer Local intranet dialog, with Automatically detect intranet network selected
  7. In the Local intranet window, in the Add this web site to the zone field, enter the URL to InfoSphere Business Glossary. (For example: http://iis_host:9080/bg)
    Figure 11. Configuring Internet Explorer
    Screen capture of Internet Explorer Local intranet dialog with URL to InfoSphere Business Glossary entered
  8. Click Add.
  9. Click Close, then click OK to complete this step and close the Local intranet dialog.
  10. In the Internet Options window, click the Advanced tab and scroll to Security settings. Ensure that the Enable Integrated Windows Authentication* check box is selected.
  11. Click OK.
  12. Close and restart Internet Explorer to activate the configuration.

Firefox

Complete the following steps to ensure that each Firefox browser is enabled to perform SPNEGO authentication.

  1. Log in to the client Windows computer as a user in the Active Directory domain.
  2. Open Firefox.
  3. In the address field, type about:config. Click through any warning messages displayed by the browser.
  4. In the Filter field, type network.n.
  5. Double click on network.negotiate-auth.trusted-uris to list the sites that are permitted to engage in SPNEGO authentication with the browser. Add the URL to InfoSphere Business Glossary (For example: http://iis_host:9080/bg). If you are adding multiple sites, separate each with a comma.

    Note: Do not set a value for network.negotiate-auth.delegation-uris.

    Figure 12. Configuring Firefox
    Screen capture of Firefox with URL of InfoSphere Business Glossary entered in dialog
  6. Click OK. The configuration appears updated with the URL that you entered.
  7. Close and restart the Firefox browser to activate this configuration.

Chrome

Complete the following steps to ensure that each Chrome browser is enabled to perform SPNEGO authentication.

  1. Right click on the Chrome icon.
  2. Select Properties.
  3. In the Target field, after chrome.exe type the following:

    --auth-server-whitelist="url_value"

    where:

    url_value is the URL to InfoSphere Business Glossary. For example: iis_host:9080/bg

    Figure 13. Configuring Chrome
    Screen capture of Chrome Properties window, with --auth-server-whitelist and InfoSphere Business Glossary URL specified
  4. Click OK.
  5. Close and restart Chrome to activate the configuration.

Step 6: Configuring InfoSphere Business Glossary Anywhere

InfoSphere Business Glossary Anywhere is the mini-application that provides access to InfoSphere Business Glossary Anywhere content from within other applications. You can configure InfoSphere Business Glossary Anywhere to support the SPNEGO authentication that you have configured for InfoSphere Information Server. You can also configure InfoSphere Business Glossary Anywhere so that end-users are given the option of enabling this feature.

You make the required configuration changes in the InfoSphere Business Glossary Anywhere configuration file (config.ini) file.

The configuration file settings take effect the first time you install the InfoSphere Business Glossary Anywhere client on each user computer.

Note: If you want to update existing installations of InfoSphere Business Glossary Anywhere to use the single sign-on features, you must uninstall InfoSphere Business Glossary Anywhere, edit the configuration file, then reinstall InfoSphere Business Glossary Anywhere on each client computer, using the revised config.ini file.

Two parameters affect single sign-on, EnableDesktopSSOConfiguration and EnableDesktopSSO. Figure 14 shows their location in the config.ini file:

Figure 14. Single sign-on parameters in the InfoSphere Business Glossary Anywhere config.ini file
Screen capture of InfoSphere Business Glossary Anywhere config.ini file, with single sign-on parameters circled

Table 1 shows the possible values for these parameters and their results.

Table 1. Single-sign on parameter values and results
EnableDesktopSSOConfiguration settingEnableDesktopSSO settingResult
True

False

True

In the Settings panel of the InfoSphere Business Glossary Anywhere client, a check box is displayed for users to enable or disable single sign-on. By using this check box, end-users can override the EnableDesktopSSO setting in the configuration file.
FalseFalseSingle sign-on is disabled and end-users cannot override this setting. (No check box is displayed on the Settings panel.)
FalseTrueSingle sign-on is enabled, and end-users cannot override this setting. (No check box is displayed on the Settings panel.)

To configure the settings in the config.ini file, follow these steps:

  1. Open the InfoSphere Business Glossary Anywhere config.ini file. The file is provided in the compressed (.zip) file located in the BusinessGlossaryAnywhereClient directory in the root of the InfoSphere Information Server installation media. For InfoSphere Information Server version 9.1, the compressed file is named BGA_WIN_91.zip.
  2. Navigate to the Host Configurations settings section of the file. Edit the EnableDesktopSSOConfiguration and EnableDesktopSSO parameters to the values you prefer. Save the file.
  3. Install the InfoSphere Business Glossary Anywhere client as you would normally, using the revised config.ini file.

For a link to full installation instructions for InfoSphere Business Glossary Anywhere, see Resources.


Troubleshooting

As the configuration is complex, errors are common. This section explains how to configure a trace that might help with troubleshooting, and describes two common errors and their solutions. You can find links to additional troubleshooting information in Resources.

Enabling the JGSS trace

You can enable the JGSS (Java Generic Security Service) trace in WebSphere Application Server to provide troubleshooting information. To enable this trace:

  1. Log in to the WebSphere Application Server administrative console.
  2. From the left pane of the console, select Websphere application servers > server1.
  3. From right pane of the console, select Java and Process Management > Process definition.
  4. Select Java Virtual Machine.
  5. Select Custom properties.
  6. Select the com.ibm.jgss.security.debug and com.ibm.security.krb5.Krb5Debug resources.
    Figure 15. Enabling Java Generic Security Service tracing
    Screen capture of the WebSphere Application Server custom properties page, showing the two resources to select as defined in this step

    See larger image.

  7. Click Apply, and then click Save.
  8. Stop and restart WebSphere Application Server to enable the trace.

Time synchronization

The system clocks of the Active Directory system, the WebSphere Application Server system, and the Windows client must all be within 300 seconds (5 minutes) of each other. If the time settings are not within this range, then single-sign on will fail and the user on the client system is prompted for authentication credentials.

Case sensitivity

Be aware of case-sensitivity when entering name strings. The realm name DOMAIN1 is not the same as the realm name domain1. By convention, realm names are often entered in uppercase characters.


Conclusion

You should be able follow the step-by-step instructions provided in this article to configure single sign-on for InfoSphere Business Glossary and its companion product InfoSphere Business Glossary Anywhere. If issues arise, it is likely that you can identify them from the JGSS trace results and by referring to the troubleshooting-related links in Resources.

Resources

Learn

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Information management on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Information Management
ArticleID=858172
ArticleTitle=Implementing Windows desktop single sign-on for InfoSphere Business Glossary
publish-date=02212013