Sun and Microsoft Interoperate for Web Authentication, Part 3

In Part 1 of this series, you saw how to extend authentication with Sun Java System Access Manager (henceforth, Access Manager) with Policy Agents. In Part 2, you learned how to integrate Microsoft SharePoint Portal Server with Access Manager for SSO.

Part 3 continues the integration story for SSO, this time with Microsoft Outlook Web Access (henceforth, OWA) and Access Manager. Afterward, once users have authenticated with Access Manager, they can—without having to log in again—perform email tasks in their Inbox in OWA.

In an OWA deployment, you can configure in the Microsoft Internet Information Services (IIS) Administration Console any authentication mechanism supported by IIS. The authentication choices are Basic, Digest, Windows Integrated, and Anonymous. The current OWA Agent supports basic authentication only. For tighter security, you can configure basic authentication with Secure Sockets Layer (SSL). Basic authentication is supported by most Web browsers.

Figure 1 shows the Authentication Methods dialog box in the IIS Administration Console. Just select "Basic authentication (password is sent in clear text)" and click OK.

Figure 1: Specifying the Authentication Method in IIS (Click image for larger view.)

In the absence of the OWA Agent, when you access OWA at https:// OWA_hostname : OWA_portnumber /exchange, the OWA login screen is displayed. See Figure 2.

Figure 2: Logging In to OWA

After successful authentication, OWA displays the user1 Inbox. Figure 3 is an example.

Figure 3: Viewing the user1 Inbox

The OWA Agent enables SSO for OWA with all the applications configured in Access Manager. When a user accesses OWA, its Agent displays an Access Manager login screen. Once authenticated, the user can access all the applications that are secured by Access Manager.

To deploy the OWA Agent, first configure a post-authorization plug-in, ReplayPasswd, with Access Manager (see the next section). An encryption key is shared between Access Manager and the OWA Agent.

Here is what transpires behind the scenes:

1. When an access request arrives at the OWA application through IIS, the OWA Agent intercepts the request and redirects it to Access Manager for authentication.
   
   
2. After successful authentication, ReplayPasswd encrypts the password with the shared key and stores the encrypted data in the Access Manager session, whose ID is then set in a special cookie in the form of an SSO Token ID.
   
   
3. The Policy Agent retrieves the encrypted password from the SSO Token and decrypts the information with the shared key. That way, the Policy Agent has in its possession the original credentials, which it then encodes according to the Base64 encoding method and places in the Basic Authentication HTTP header of the original HTTP request.
   
   
4. Now that the HTTP request has a valid Basic Authentication HTTP header, IIS does not prompt for authentication. Subsequently, the user is allowed access to the resource requested.

You must synchronize the user passwords in the Access Manager data store with those of OWA for Exchange Server. If the OWA user accounts are stored in Active Directory, you can configure Access Manager to use the same Active Directory as the data store and avoid having to synchronize passwords in two different LDAP servers.

Before installing the OWA Agent, first configure Access Manager.

Configuring Access Manager
Important: Be sure to install Java 2 Platform, Standard Edition (J2SE platform) 1.4 or a later version.

Included in Access Manager 7.0 Patch 5 onward, except Access Manager 7.1, are ReplayPasswd.java, a plug-in, and DESGenKey.java, a key generator.

Note: For the procedure on how to configure the plug-in in earlier patches and generate the shared key, see Appendix A.

To configure ReplayPasswd.class as a post-authorization plug-in, follow steps 1-5 below.

1. Log in to the Access Manager Administration Console as amadmin.
   
   
2. Click the Access Control tab, click the realm, and then click the Authentication tab.
   
   
3. Under General, click Advanced Properties.
   
   
4. Scroll down to the Authentication Post Processing Class field. In the text field, type com.sun.identity.authentication.spi.ReplayPasswd.
   
   
5. Scroll up, click Save, and exit Access Manager.

Next, generate and add the shared key and the LDAP attribute to the AMConfig.properties file:

1. Go to the lib directory in the Access Manager installation location ( /opt/SUNWam/lib by default) and execute DESGenKey. Type (all on one line):
   
   # java -classpath /opt/SUNWam/lib/am_services.jar:/opt/SUNWam/lib/ am_sdk.jar:/opt/SUNWam/lib/servlet.jar com.sun.identity.common.DESGenKey
   
   Access Manager generates and outputs the key, for example: Key ==> bTGKXVs3WEk=
   
   
2. Add the key as the value of the com.sun.am.replaypasswd.key property in the AMConfig.properties file.
   
   For example, add this line:
   
   com.sun.am.replaypasswd.key = bTGKXVs3WEk=
   
   
3. Add this line to enable the OWA configurations:
   
   com.sun.am.iis_owa_enabled = true
   
   
4. Restart Access Manager.

Installing and Configuring the OWA Agent
First, install and configure the OWA Agent by following steps 1-7 in the section Installing and Configuring the SharePoint Agent in Part 2 of this series.

Creating a Timeout Page for Local Idle Sessions
Next, create a timeout page for local idle sessions:

1. Create a new virtual server (a different Web site) in the IIS Administration Console and a corresponding application pool in a new folder called C:\Inetpub\test.
   
   
2. Install SSL on the new site and verify that the site is accessible from the browser.
   
   
3. Ensure that the OWA server runs does not run on port 444 and then define the site's port number as 444.
   
   
4. Enable the site to run scripts and executables: Open the site's Properties dialog box, click the Home Directory tab, and, under "Application settings," select Scripts and Executables from the "Execute permissions" pull-down menu. See Figure 4.
   
   

   Figure 4: Enabling a Virtual Server to Run Scripts and Executables

    
   
   
5. Create a Web page called timeout.asp in C:\Inetpub\test with the following content.
   
   

   <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <% redirectvalue = Request.QueryString("owagoto") posn=inStr( redirectvalue, "owalogon.asp?url=" ) If(posn > 1) then str2 = Split(redirectvalue,"owalogon.asp?url=") str3 = Split(str2(1),"&reason") redirectvalue=str3(0) End If %> <meta http-equiv="Refresh" content="0;url=https:// <Access_Manager_hostname>:<Access_Manager_portnumber>/amserver/UI/ Login?goto=<%=redirectvalue%>"> </head> </html>

    
   

Modifying the Logoff Page
To ensure that logouts are handled correctly, update the logoff page ( logoff.asp) as follows:

1. Back up the file C:\Program Files\Exchsrvr\exchweb\bin\usa\logoff.asp.
   
   
2. Replace the content of logoff.asp with the following:
   
   

   <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <% Response.Cookies("owaAuthCookie").Domain = ".iplanet.com" Response.Cookies("owaAuthCookie").Path = "/" Response.Cookies("owaAuthCookie")= "owaValue" Response.Cookies("owaAuthCookie").Expires = "July 1, 1995" %> <meta http-equiv="Refresh" content="0;url= https:// <Access_Manager_hostname>:<Access_Manager_portnumber>/amserver/UI/Logout?goto =https%3A%2F%2F<OWA_hostname>%3A<OWA_portnumber>%2F"> </head> </html>

    
   
3. Edit logoff.asp and replace .iplanet.com with the appropriate domain name for the cookies. See Appendix B for the procedure on how to obtain the domain name from the Access Manager Administration Console.
   
   
4. Save the file.

Updating the AMAgent.properties File
Finally, update the AMAgent.properties file as follows:

1. Add the following line to enable the OWA-related configurations:
   
   com.sun.am.policy.agents.config.iis.owa_enabled = true
   
   
2. Add the following line to point to the URL of the timeout page for local idle sessions:
   
   com.sun.am.policy.agents.config.iis.owa_enabled_session_timeout_url = https:// OWA_hostname :444/timeout.asp
   
   
3. Save the file.
   
   
4. Restart IIS with the iisreset command.

To test the setup:

1. Start a new browser.
   
   
2. Go to the OWA login screen at https:// OWA_hostname : OWA_portnumber /exchange.
   
   You are redirected to the Access Manager login screen. See Figure 5.
   
   

   Figure 5: Logging In at Access Manager Login Screen

    
   
   Tip: If the Access Manager login screen is not displayed, you might not have deployed the ISAPI filters properly. To view a list of the deployed ISAPI filters, on the right pane in the IIS Administration Console, select Web Sites > Default Web Site > Properties > ISAPI Filters. Figure 6 shows an example.
   
   

   Figure 6: Viewing the Deployed ISAPI Filters

    
   
   
3. Enter the login credentials for user1.
   
   Access Manager displays the Inbox of user1 (see Figure 7) instead of the OWA login screen (as shown in Figure 2)—a testament that SSO is in action.
   
    
   

   Figure 7: Inbox of user1 Upon Successful Login

For any release that is earlier than Access Manager 7.0 Patch 5 and for Access Manager 7.1, ReplayPasswd.java and DESGenKey.java are shipped separately. You must compile the two files and ensure that their class files are in Access Manager's lib directory ( /opt/SUNWam/lib by default), as follows:

1. As root, compile ReplayPasswd.java and DESGenKey.java by typing (all on one line):
   
   # javac -classpath Access_Manager_install_dir /lib/am_services.jar: Access_Manager_install_dir /lib/am_sdk.jar:
Access_Manager_install_dir /lib/servlet.jar ReplayPasswd.java DESGenkey.java
   
   where Access_Manager_install_dir is the location in which you installed Access Manager. The default is /opt/SUNWam.
   
   For example:
   
   # javac -classpath /opt/SUNWam/lib/am_services.jar:/opt/SUNWam/lib/am_sdk.jar:
/opt/SUNWam/lib/servlet.jar ReplayPasswd.java DESGenkey.java
   
   
2. In the Access Manager Administration Console, click the Access Control tab, click the realm, and then click the Authentication tab. Under General, click Advanced Properties. Scroll down to the Authentication Post Processing Class field. In the text field, type ReplayPasswd.
   
   
3. Generate the shared key: Go to the lib directory of the Access Manager installation and type:
   
   # java DESGenKey

Note: On the Solaris and Linux platforms, the class files must reside in Access Manager's lib directory; in Windows, in the WEB-INF\classes subdirectory of Access Manager's amserver directory.

To obtain the name of the cookie domain:

1. Log in to the Access Manager Administration Console as amadmin.
   
   The Access Control screen is displayed. See Figure 8.
   
   

   Figure 8: Access Control Screen on Access Manager Administration Console (Click image for larger view.)

    
   
   
2. Click the Configuration tab. See Figure 9.
   
   

   Figure 9: Configuration Screen on Access Manager Administration Console (Click image for larger view.)

    
   
   
3. Scroll down to System Properties and click Platform, the bottom link. See Figure 10.
   
   

   Figure 10: System Properties on Access Manager Administration Console (Click image for larger view.)

    
   
   A list of names is displayed under Cookie Domains. Figure 11 is an example, with only .iplanet.com listed.
   
   

   Figure 11: Platform Screen on Access Manager Administration Console (Click image for larger view.)

    
   
   
4. Pick the appropriate name.

Thanks to the OWA Agent, when multiple applications—email, calendar, and such—are all interacting with Access Manager, enabling SSO for them takes only a few steps. Try it out yourself!

• Sun Java System Access Manager
  • Main page
  • Developer home
  • Software Forum
  
  
• Previous articles on Access Manager
  • Sun and Microsoft Interoperate for Web Authentication, Part 2 (August 27, 2007)
  • Sun and Microsoft Interoperate for Web Authentication, Part 1 (December 4, 2006)
  • What's Happening in Identity at Sun (September 1, 2006)
  • Configuring Load Balancing for Sun Java System Access Manager (December 14, 2005)
  • Building Identity-Enabled Web Services (October 18, 2005)
  • Federated Identity: Single Sign-On Among Enterprises (October 14, 2004)
  
  
• Sun developer services
  • Support
  • Training and certification