Integrating Sun Java System Access Manager 2004Q2 with Oracle Application Server 10g (9.0.4) for Single Sign-On

For details of the differences between Oracle Application Server 9i Release 1 (1.0.2.2) and Oracle Application Server 10g (9.0.4), see section 1.2 in the Oracle Application Server 10g (9.0.4) FAQ.

In addition, point (v) in section 5.2 in the technical white paper, Oracle Application Server 10g (9.0.4) New Features Overview, states that Oracle identity management includes OracleAS Single Sign-On component, which provides SSO access to Oracle and third-party Web applications. That component also includes enhancements over the 9i version.

Note - In Oracle Application Server 9i Release 1 (1.0.2.2), the component that is similar to OracleAS Single Sign-On is known as Login Server.

You must install the following software for the Access Manager-Oracle Application Server 10g (9.0.4) integration:

• Sun Java System Access Manager 2004Q2
  
  
• Sun Java System Access Manager Policy Agent 2.1 for Oracle Application Server 9i HTTP Server
  
  Note: This product is compatible with both Oracle Application Server 9i and Oracle Application Server 10g (9.0.4).
  
  
• Oracle Application Server 10g (9.0.4)

The above software supports the Solaris Operating System, versions 8 and 9.

Follow the procedures in this section to install, configure, and deploy the integration. Here, for verification, Oracle Application Server Portal serves as a partner application.

Installation and Configuration

1. Install Oracle Application Server 10g (9.0.4), including OracleAS Single Sign-On and Oracle Application Server Portal.
   
   Be sure to install Oracle Application Server 10g (9.0.4) with a fully qualified domain name (FQDN). Otherwise, third-party authentication will fail. Type:
   
   % ./runInstaller OUI_HOSTNAME=hostname.domainname
   
   For example, if your machine is called agent1 and the domain, example.com, type:
   
   % ./runInstaller OUI_HOSTNAME=agent1.example.com
   
   For details, see the Oracle Application Server 10g (9.0.4) documentation. (Access requires preregistration.)
   
   
2. Install Access Manager on a separate machine.
   
   
3. Create the users with the proper roles in Oracle Internet Directory for your environment.
   
   
4. Synchronize the user names in Oracle Internet Directory with those in Directory Server Enterprise Edition.
   
   If a user name exists in Oracle Internet Directory, then that name must also exist in Directory Server Enterprise Edition.
   
   You can effect the synchronization by manually adding the Oracle Internet Directory user names to Directory Server or by using the Oracle Internet Directory Connector for Directory Server Enterprise Edition. The Oracle Internet Directory Connector, bundled with Oracle Application Server 10g (9.0.4), includes a synchronization component that is driven by the Oracle Directory Integration and Provisioning Server. This connector enables user mapping between the two directories, thereby synchronizing user data-organizations, groups, first names, last names, telephone numbers, email addresses, and the like. The synchronization component maintains consistency of the data between the two directories.
   
   For details, see the procedures.
   
   
5. Install Sun Java System Access Manager Policy Agent 2.1 (Policy Agent) for Oracle Application Server 9i HTTP Server on the machine in which OracleAS Single Sign-On is running.
   
   Though the Policy Agent name refers to Oracle Application Server 9i only, the Policy Agent enables Access Manager to authenticate and authorize users for accesses through a Web browser to both Oracle Application Server 10g (9.0.4) and Oracle Application Server 9i HTTP Server.
   
   Visit the download page for free downloads.
   
   For the installation procedure, see the documentation for the Policy Agent. When the installation program prompts you for an Apache instance, specify OracleAS Single Sign-On, which was installed with the mid-tier, so that it can be protected by the Policy Agent. Additionally, select the SSL Ready checkbox; Oracle's Apache Web Server is SSL ready.
   
   
6. Configure the Policy Agent by revising its AMAgent.properties file at /etc/opt/SUNWam/agents/apache/config/_Pathinstancename. Do the following:
   
   
   1. Set the value of fetchHeaders to true, like this:
      
      com.sun.am.policy.am.fetchHeaders = true
      
      Afterwards, you can introduce additional policy response attributes into the HTTP headers through the headerAttributes property.
      
      
   2. Set the value of headerAttributes to uid|identity-user, like this:
      
      com.sun.am.policy.am.headerAttributes=uid|identity-user
      
      This property configures Access Manager to pass authenticated user IDs to OracleAS Single Sign-On by means of HTTP headers. In this case, Access Manager passes the authenticated user's uid attribute to OracleAS Single Sign-On from the identity-user HTTP header.
      
      
   3. Set the value of do_sso_only to true, like this:
      
      com.sun.am.policy.agents.do_sso_only = true
      
      The Policy Agent then enforces user authentication without enforcing policies (authorization). In this integration, OracleAS Single Sign-On handles authorization.
      
      
   4. Set the value of fqdnDefault to be the FQDN (hostname.domainname).
      
      For example, if the FQDN is agent1.example.com, set the value as follows:
      
      com.sun.am.policy.agents.fqdnDefault = agent1.example.com
      
      By default, the Policy Agent's installation program sets this value to the name of the host in which the Policy Agent resides.
      
      
   5. Set the value of reverse_the_meaning_of_notenforcedList to true, like this:
      
      com.sun.am.policy.agents.reverse_the_meaning_of_notenforcedList = true
      
      That way, the notenforced list becomes the enforced list, whose URLs are protected by the Policy Agent.
      
      
   6. Set the value of notenforcedList to reflect the list of URLs that the Policy Agent enforces; that is, these URLs require authentication for access.
      
      For example, if the FQDN of the machine in which Oracle Application Server 10g (9.0.4) is installed is agent1.example.com and the number of the port on which OracleAS Single Sign-On is running is 7777, set the value as follows (all on one line):
      
      com.sun.am.policy.agents.notenforcedList = http://
agent1.example.com:7777/pls/orasso/
ORASSO.wwsso_app_admin.ls_login http://
agent1.example.com:7777/sso/auth*
      
      Separate the two URLs with a space.
      
      Also, do not change the value of notenforcedList according to the number or type of partner applications. Always set it as described in this step.
      
      
   7. Set the value of logout.url to reflect the logout URLs of OracleAS Single Sign-On and its partner applications (all on one line).
      
      This value specifies the logout URLs of OracleAS Single Sign-On and its partner applications. Those URLs are never enforced by the Policy Agent. When the Policy Agent encounters any of them, it checks whether a valid session ID for the user still exists. If so, the agent invalidates the session, which effectively logs the user out of Access Manager.
      
      Next, the Policy Agent passes the request to OracleAS Single Sign-On for processing. In this integration, since Oracle Application Server Portal is the partner application for verification, the logout URLs for both OracleAS Single Sign-On and Oracle Application Server Portal are included.
      
      Note: Be sure to separate the values with a space.
      
      Here is an example:
      
      com.sun.am.policy.agents.logout.url = http://hostname:portnumber
      /plsportal30_sso/
PORTAL30_SSO.wwsec_app_priv.logout?p_done_url=http%3A%2F%2Fhost
name%3A‹port›%2Fpls%2Fportal30_sso%2FPORTAL30_SSO.home

http://hostname:portnumber/pls/portal30/
PORTAL30.wwsec_app_priv.logout?p_done_url=http%3A%2F%2Fhostname
      %3Aportnumber%2Fpls%2Fportal30%2FPORTAL30.home
      
      Here, hostname refers to the machine in which the Policy Agent resides. portnumber is the number of the port of Oracle HTTP Server. For example, if hostname is agent1.example.com and portnumber is 7779, set logout.url as follows:
      
      com.sun.am.policy.agents.logout.url=http://agent1.example.com:7779/pls/
portal30_sso/
PORTAL30_SSO.wwsec_app_priv.logout?p_done_url=http%3A%2F
%2Fagent1.example.com%3A7779%2Fpls%2Fportal30_sso%2FPORTAL30_SSO.home

http://agent1.example.com:7779/pls/portal30/
PORTAL30.wwsec_app_priv.logout?p_done_url=http%3A%2F%2Fagent1.example.com%
3A7779%2Fpls%2Fportal30%2FPORTAL30.home
      
      Note: If you use additional Oracle partner applications, add their logout URLs to the list.
      
      
   8. Set the value of logout.cookie_reset_list to list the cookies that Access Manager must reset or delete upon logout.
      
      For example, if you also use Oracle Application Server Portal for the integration, include the cookies for both OracleAS Single Sign-On and Oracle Application Server Portal and set logout.cookie_reset_list as follows:
      
      com.sun.am.policy.agents.logout.cookie_reset_list = Domain=, iPlanetDirectoryPro, iPlanetDirectoryPro;Domain=, portal30,portal30;Domain=
      
      If you use other Oracle partner applications in the integration, be sure to add their cookies to this list.

Other Setup

Follow the steps in this section to complete the configuration and deployment.

1. Create a file called SSOTPAMAuth.java in the directory $ORACLE_HOME_INFRASTRUCTURE/j2ee/OC4J_SECURITY/applications/sso/web/WEB-INF/classes.
   
   Here is a sample file.

/**
 * returns IPASUserInfo
 /**
 /* Copyright (c) 2002, 2003, Oracle Corporation. All rights reserved. */
 /*
 DESCRIPTION
     Class for Sun Java System Identity Server integration with SSO Server

 PRIVATE CLASSES
 NOTES
 This class implements the SSOServerAuthInterface. To enable this integration,
replace: oracle.security.sso.server.auth.SSOServerAuth with
oracle.security.sso.server.auth.SSOTPAMAuth for the desired security level in
policy.properies.
 */

package SunTPAM.security.ssoplugin;

import java.io.PrintWriter;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import oracle.security.sso.ias904.toolkit.IPASAuthInterface;
import oracle.security.sso.ias904.toolkit.IPASAuthException;
import oracle.security.sso.ias904.toolkit.IPASUserInfo;
import oracle.security.sso.ias904.toolkit.IPASInsufficientCredException;
import java.net.URL;

public class SSOTPAMAuth implements IPASAuthInterface {

 private static String CLASS_NAME = "SSOTPAMAuth";

 private static String TPAM_USER_HEADER = "identity-user";

 public SSOTPAMAuth() {
}

public IPASUserInfo authenticate(HttpServletRequest request) throws
IPASAuthException, IPASInsufficientCredException {

String TPAMUserName = null;

try {

     TPAMUserName = request.getHeader(TPAM_USER_HEADER);

 } catch (Exception e) {

               throw new IPASInsufficientCredException("No TPAM Header");

 }

 if (TPAMUserName == null) throw new IPASInsufficientCredException("No TPAM
Header");

 IPASUserInfo authUser = new IPASUserInfo(TPAMUserName);
 return authUser;

 }
 public URL getUserCredentialPage(HttpServletRequest request, String msg)
 {
 // This function will never have been reached in the case of TPAM
 // as the TPAM Agent will intercept all requests

try {

   return new URL("error.html");
} catch (Exception e) {

System.out.println("Exception in SSOTPAMAuth");
e.printStackTrace();
}

System.out.println("Error encountered in SSOTPAMAuth");
return null;
 }
}

You can adopt the content of this file, but do the following edits:


1. Revise the URL returned by the method getUserCredentialPage.
   
   
2. Configure getUserCredentialPage to return an error URL that pertains to your environment.
   
   In this example, substitute error.html with an error URL from your environment.
   
   
3. Optional. Add extra debug information or change the exception output to help diagnose problems that may arise from third-party authentication.


2. Add the following to your CLASSPATH environment variable (all on one line):
   
   $ORACLE_HOME_INFRASTRUCTURE/j2ee/home/lib/
servlet.jar:$ORACLE_HOME_INFRASTRUCTURE/sso/lib/ipastoolkit.jar
   
   Replace $ORACLE_HOME_INFRASTRUCTURE with the name of the directory in which the Oracle Application Server 10g (9.0.4) infrastructure resides.
   
   
3. Go to the directory $ORACLE_HOME_INFRASTRUCTURE/j2ee/OC4J_SECURITY/applications/sso/web/WEB-INF/classes and compile the file SSOTPAMAuth.java by typing:
   
   % javac -d . SSOTPAMAuth.java
   
   That command line creates the directory structure SunTPAM/security/ssoplugin and places the compiled SSOTPAMAuth class there.
   
   
4. Copy the directory SunTPAM/security/ssoplugin and its contents to the directory $ORACLE_HOME_INFRASTRUCTURE/sso/plugin.
   
   The file SSOTPAMAuth.class that you just compiled is now under $ORACLE_HOME_INFRASTRUCTURE/sso/plugin/SunTPAM/security/sssoplugin.
   
   
5. Edit the policy.properties file at $ORACLE_HOME_INFRASTRUCTURE/sso/conf by setting the following property (all on one line):
   
   MediumSecurity_AuthPlugin = SunTPAM.security.ssoplugin.SSOTPAMAuth
   
   That way, OracleAS Single Sign-On uses the authentication module for Access Manager.
   
   For a successful integration, you need not change any other properties in policy.properties.
   
   Optionally, to include debug information for OracleAS Single Sign-On, set the debugLevel property. OracleAS Single Sign-On provides these four debugging levels (in ascending order):
   
   
   ERROR - Logs errors only.
   WARN - Logs both errors and warnings.
   INFO - Logs informational messages (such as the current data and time), errors, and warnings.
   DEBUG - Logs details on program execution, informational messages, errors, and warnings.
   
   The debug file provides debugging information to OracleAS Single Sign-On and is defined by the property debugFile, which specifies the location of the SSO debug file.
   
   Important note: This is a mandatory property you must pass to the OracleAS Single Sign-On; be sure to cite a valid file location for the property.

Now that installation and configuration are complete, you can test the SSO integration with a partner application. Follow these steps:

1. Restart Access Manager.
   
   For the procedure, see Chapter 10 in the Access Manager Administration Guide.
   
   
2. Restart Oracle HTTP Server and OC4J_SECURITY on the Web with Enterprise Manager.
   
   
3. Log in to OracleAS Single Sign-On or to the partner application, for example, Oracle Application Server Portal.
   
   Once you have logged in, OracleAS Single Sign-On directs you to the Access Manager login page. After successful authentication, you can access the Oracle application.

For troubleshooting tips, see that section in the article, Integrating Sun Java System Access Manager 6.1 with Oracle 9i Application Server Release 1: A Case Study.

For a log of Java exceptions and System.out.println lines from the SSOTPAMAuth class, see:

$ORACLE_HOME/opmn/logs/OC4J~OCJ4_SECURITY~default_island~1

Following are the known bugs and workarounds that have been identified for this integration:

• Sun Bug ID #5052932: After installation, the Policy Agent's installation program changes the ownership of the file httpd.conf from the original user to the user root. Subsequently, Oracle startup problems may occur.
  
  Workaround: Manually change the ownership of httpd.conf to the original user.
  
  
• Sun Bug ID #5069515: If Access Manager is installed on a domain other than that for Oracle Application Server 10g (9.0.4), the integration becomes error prone. For example, if you enable the Policy Agent for Cross-Domain Single Sign-On (CDSSO), accesses to OracleAS Single Sign-On or Oracle Application Server Portal return a 500 Internal Server error.
  
  Workaround: Ensure that the Access Manager host is on the same domain as Oracle Application Server 10g (9.0.4). This integration does not support CDSSO.
  
  
• Sun Bug ID #5069541: If you run Internet Explorer 6 for the integration and attempt to log in to Oracle Application Server Portal, an error results. This error does not occur with the Mozilla or Netscape browsers.
  
  Why? The problem likely stems from how Internet Explorer handles multiple redirections. Because Oracle Application Server Portal and OracleAS Single Sign-On are on the same machine, the Login link on the portal actually points to Oracle Application Server Portal, which redirects the request to Policy Agent-protected OracleAS Single Sign-On. When it gets the login URL, the Policy Agent sets the port number to 7778; the correct number is 7777 instead. However, since the Policy Agent enforces only the login URL with port 7777, it allows the login URL without redirect or authentication.
  
  Workarounds: An obvious workaround is to run the Mozilla or Netscape browser for this integration. Alternatively, install Oracle Application Server Portal and OracleAS Single Sign-On on different machines. If neither of these options is possible, log in through OracleAS Single Sign-On first before accessing Oracle Application Server Portal.
  
  You can also configure a second instance of the Policy Agent to protect port 7778. In the AMAgent.properties file of the Policy Agent instance, set the following two properties (one line each).
  
  propertycom.sun.am.policy.agents.reverse_the_meaning_of_notenforcedList = true

com.sun.am.policy.agents.notenforcedList = http://agent1.example.com:7778/sso/auth* http://agent1.example.com:7778/pls/portal/
PORTAL.wwsec_app_priv.login?p_requested_url=http%3A%2F%
2Fagent1.example.com%3A7778%2Fpls%2Fportal%2FPORTAL.home&p_can
cel_url=http%3A%2F%2Fagent1.example.com%3A7778%2Fpls%2Fportal%
2FPORTAL.home
  
  The second line is an example only; be sure to replace agent1.example.com:7778 with the appropriate value.

• Sun Java System Access Manager
  • Main page
  • Developer home
  • Collection of documentation
  
  
• Sun Java System Access Manager Policy Agent 2.1
  • Collection of documentation
  • User guide
  
  
• Related Oracle Products and Documentation
  • Oracle Portal Center
  • Oracle Application Server 10g (9.0.4)
  • Oracle Application Server Single Sign-On Administrator's Guide
  • Oracle Internet Directory Administrator's Guide: Integration with Sun Java System Directory Server

Jennifer Glore and Prashant Srinivasan are members of technical staff of the Market Development Engineering group at Sun. They work with Oracle to integrate its products with Sun Java System Access Manager.

Marina Sum is a staff writer for Sun Developer Network. She has been writing for Sun for 15 years, mostly in the technical arena.