Chapter 5 Single Sign-on Solution for Oracle Application Servers

This chapter explains how you can deploy the Single Sign-on (SSO) solution for Oracle9iAS R1 and Oracle Application Server 10g using Sun ONE Identity Server. This chapter includes the following topics:

Introduction

Oracle9iAS R1 and Oracle Application Server 10g use Login Server and Oracle Single Sign-On (SSO) Server respectively to provide SSO functionality to its partner applications. When a user presents credentials to a partner application, such as Oracle Portal, the request is redirected to the Login Server/Oracle SSO Server, which upon successful authentication, issues a token that represents the user’s identity. This token is passed on to the calling partner application, which then creates its own session tokens. Upon logout, the partner application performs its own local logout procedures and then immediately calls the Login Server/Oracle SSO server’s logout procedure. On completion of these procedures, the user’s session is invalidated.

Integration with Sun ONE Identity Server

Oracle 9iAS R1 or Oracle Application Server 10g can be integrated with Sun ONE Identity Server to achieve SSO functionality. In this type of integration, Sun ONE Identity Server sits in front of Login Server/Oracle SSO Server and provides user authentication only. Login Server or Oracle SSO Server is still responsible for managing user accounts, checking account policies, auditing, generating tokens, and redirecting users to partner applications. Since Login Server/Oracle SSO Server is still responsible for generating trust tokens, special steps must be taken to ensure that it obtains the user’s identity from Sun ONE Identity Server after successful authentication.To accomplish this task, Sun ONE Identity Server must pass the identity of the user to Login Server/Oracle SSO Server via HTTP headers. Once Login Server/Oracle SSO Server retrieves a user’s identity, it can generate a trust token for the partner applications and SSO will function normally within the environment. Since Login Server/Oracle SSO Server handles all of these responsibilities, the partner applications, which interact solely with Login Server/Oracle SSO Server, are completely unaware of the integration with Sun ONE Identity Server.

Software Requirements

For Oracle9iAS R1

For Oracle Application Server 10g

Table 5-1 Software Requirements for the SSO Solution for Oracle9iAS R1
Software	Supported Platforms
Sun ONE Identity Server, version 6.1	Solaris 8 and 9
Web Policy Agent for Oracle9iAS R1 Apache 1.3.29	Solaris 8 and 9
Oracle9iAS R1	Solaris 8 and 9

Table 5-2 Software Requirements for the SSO Solution for Oracle Application Server 10g
Software	Supported Platforms
Sun ONE Identity Server, version 6.1	Solaris 8 and 9
Web Policy Agent, version 2.1	Solaris 8 and 9
Oracle Application Server 10g	Solaris 8 and 9

Deploying the Integrated SSO Solution

The following sections present steps to deploy the integrated SSO solution for Oracle9iAS R1 and Oracle Application Server 10g. Click one of these links to go to the appropriate section.

Deploying the Solution for Oracle9iAS R1

Deploying the Solution for Oracle Application Server 10g

Deploying the Solution for Oracle9iAS R1

Do the following to deploy the integrated Sun ONE Identity Server SSO solution for Oracle9iAS:

Set up two computers as follows:

On the first computer, install Oracle9iAS R1, which includes Login Server and Oracle Portal Server. For detailed installation steps, refer Oracle documentation.

On the second computer, install Sun ONE Identity Server, version 6.1, and Sun ONE Directory Server. Now, synchronize Sun ONE Directory Server with Oracle user store on the first computer. For example, if user portal30_sso is a valid user in Oracle, that user should also be a valid user in Sun ONE Directory Server. One of the ways to synchronize user data is by using Oracle’s synchronization connector for Sun ONE Directory Server. Refer to the Sun ONE Identity Server and Sun ONE Directory Server documentation for more details on adding users to Sun ONE Identity Server.

Modify the default external authentication implementation, wwsso_auth_external, in the file ssoxnete.pkb. This file can be found in the directory $ORACLE_HOME/portal30/admin/plsql/sso. The only two functions that must be modified here are authenticate_user and get_Authentication_Name. The modified functions are documented below with the changes highlighted in bold.

Code Example 5-1 Changes to the Function authenticate_user


FUNCTION authenticate_user
(
p_user OUT VARCHAR2
)
return PLS_INTEGER
IS
l_http_header varchar(1000);
l_ssouser wwsec_person.user_name%type := NULL;
BEGIN

l_http_header := owa_util.get_cgi_env(’HTTP_IDENTITY_USER’);
debug_print(’Identity ID : ’ \|\| l_http_header);

l_ssouser := l_http_header;
IF ( (l_ssouser IS NULL) or
( INSTR(l_ssouser, GLOBAL_SEPARATOR) != 0) ) THEN
debug_print(’malformed user id: ’
\|\| l_ssouser
\|\| ’ returned by wwsso_auth_external.authenticate_user’);
RAISE EXT_AUTH_FAILURE_EXCEPTION;
ELSE
p_user := NLS_UPPER(l_ssouser);
return 0;
END IF;
EXCEPTION
WHEN OTHERS THEN
WHEN OTHERS THEN
debug_print(’unknown exception in authenticate_user(p_user)’
\|\| sqlerrm);
RAISE EXT_AUTH_FAILURE_EXCEPTION;

END authenticate_user;

Code Example 5-2 Changes to the Function get_Authentication_Name


FUNCTION get_authentication_name
RETURN VARCHAR2
AS
BEGIN
RETURN ’Sun ONE Identity Server’;
END get_authentication_name;

Run ssonete.sql on the first computer to configure Login Server to operate in the external mode and load the new external authentication implementation for Sun ONE Identity Server, which was just saved to ssoxnete.pkb in the previous step. This file can be found in the directory $ORACLE_HOME/portal30/admin/plsql/sso and should be run as user portal30_sso.

Restart Login Server for the changes to take effect.

Install the policy agent for Apache Web Server 1.3.29 in the same machine that Oracle 9iAS R1 is installed. The agent module gets installed on the same instance of Login Server. For instructions to install the agent, see Chapter 2, "Policy Agents on Solaris and HP-UX". When installing the agent, the SSL Ready box must be checked since Oracle’s Apache Server supports SSL. Additionally, make sure CDSSO is enabled even if the agent and Sun ONE Identity Server are in the same domain.

Configure the agent by modifying the AMAgent.properties files. The section Configuring the Agent explains the properties that must be changed.

Edit the modplsql Database Access Descriptor (DAD) file named wdbsvr.app for Oracle9iAS on the first computer, to include the following entries. This file is located in the directory $ORACLE_HOME/Apache/modplsql/cfg.

Identity Server headers:

cgi_env_list = HTTP_IDENTITY_USER

Connect string for the Login Server schema:

connect_string = FQDN:Database_Listener_Port:ORACLE_SID

The cgi_env_list and connect_string entries must be added under the sections [DAD_portal30] and [DAD_portal30_sso].

Deploying the Solution for Oracle Application Server 10g

Follow these steps to deploy the SSO Solution for Oracle Application Server 10g. For this SSO solution, Oracle Portal was used as a partner application to verify the integration.

Install Oracle Application Server 10g including Oracle SSO Server and Oracle Portal.

Make sure that Oracle Application Server 10g is installed using a fully qualified domain name (FQDN) for the server. If it is not installed using FQDN, third-party authentication will not work. Oracle Application Server 10g can be installed using FQDN by running the installation program with the following option:

./runInstaller OUI_HOSTNAME=server.domain

For example, if the hostname of your machine is agent1 and the domain is example.com, then the Oracle installation program should be started with the following command:

./runInstaller OUI_HOSTNAME=agent1.example.com

Consult Oracle Application Server 10g documentation for further details.

Install Sun ONE Identity Server, version 6.1, on a separate server.

Create the necessary users in Oracle Internet Directory (OID), with the proper roles, for your environment.

Synchronize the Oracle users in OID with users in Sun ONE Directory Server. This can be done by manually adding the OID users to Sun ONE Directory Server or by using the OID Connector for Sun ONE Directory Server, which synchronizes users between the two stores. Basically, if a user name exists in OID, then that user name must also exist in Sun ONE Directory Server. Refer to the Sun ONE Identity Server/Sun ONE Directory Server documentation for more details on adding users manually or to the OID Connector documentation for more information on automatic synchronization between the two user stores. You can download the OID Connector for Sun ONE Directory Server at:

http://download-west.oracle.com/docs/cd/B10464_02/manage.904/b12118/odip_ipl.htm#122580

Install the policy agent, version 2.1 for Apache 1.3.29 on the same machine where Oracle SSO Server is running. The policy agent for Apache 1.3.29 can be downloaded from Sun at:

http://wwws.sun.com/software/download/allproducts.html#id_server_agents

Refer Chapter 2, "Policy Agents on Solaris and HP-UX" of this guide for detailed instructions to install the agent. When the installation prompts you for an Apache instance, select the Oracle Single Sign-On server instance, which was installed with the midtier. This allows the agent to protect the Oracle SSO Server. Additionally, the SSL Ready box must be checked since Oracle’s Apache is SSL ready.

Configure the policy agent for Apache 1.3.29 by modifying the agent’s AMAgent.properties file. Refer the section Configuring the Agent for more information about the properties you should modify.

Once you have set the values for agent properties, 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 that you can use. You should use the exact contents of this file except the URL returned by the method getUserCredentialPage. This method should be configured to return an error URL that is pertinent to your environment. In this example, you should substitute error.html with an error URL from your environment. Additionally, you can add extra debug information in this file or change the exception output to help diagnose any problems arising out of third-party authentication.

Code Example 5-3 SSOTPAMAuth.java

/**
* returns IPASUserInfo
/**

/* Copyright (c) 2002, 2003, Oracle Corporation. All rights reserved. */
/*
DESCRIPTION
Class for Sun ONE 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.properties.
*/
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;
}
}

Add the following lines to your CLASSPATH environment variable:

$ORACLE_HOME_INFRASTRUCTURE/j2ee/home/lib/servlet.jar:$<ORACLE_HOME_INFRASTRUCTURE>/sso/lib/ipastoolkit.jar

Note that $ORACLE_HOME_INFRASTRUCTURE must be replaced to point to the ORACLE_HOME directory where Oracle 10g Infrastructure is installed.

Go to the directory $ORACLE_HOME_INFRASTRUCTURE/j2ee/OC4J_SECURITY/applications/sso/web/WEB-INF/classes and compile the file SSOTPAMAuth.java with the following command:

javac -d . SSOTPAMAuth.java

This should create the directory structure SunTPAM/security/ssoplugin and place the compiled SSOTPAMAuth class there.

Copy the entire directory structure SunTPAM/security/ssoplugin and its contents to the directory $ORACLE_HOME_INFRASTRUCTURE/sso/plugin. The file SSOTPAMAuth.class that you just compiled should now be under $ORACLE_HOME_INFRASTRUCTURE/sso/plugin/SunTPAM/security/sssoplugin.

Modify the file policy.properties located in the following directory:

$ORACLE_HOME_INFRASTRUCTURE/sso/conf

In this file, change the property MediumSecurity_AuthPlugin so as follows:

MediumSecurity_AuthPlugin = SunTPAM.security.ssoplugin.SSOTPAMAuth

This property specifies the authentication module for Sun ONE Identity Server that Oracle SSO Server must use.

No other parameters in this file need to be changed for this integration to be successful. However, if need be, the property debugLevel can be changed to provide more debug information for the Oracle SSO server, if necessary. The Oracle SSO server provides the following four levels of debugging:

ERROR: log errors only

WARN: log both errors and warning messages

INFO: log messages such as current data and time, for instance, as well as errors and warnings

DEBUG: log details about program execution as well as errors, warnings, and messages

The Oracle SSO Server debug file is defined by the property debugFile. The debug file provides debugging information to the Oracle SSO Server. For further information on how this file should be set, please refer to the Oracle Application Server 10g documentation.

Additionally, if you want to see where Java exceptions and System.out.println lines from the SSOTPAMAuth class are logged, you can see them at the following location:
$ORACLE_HOME/opmn/logs/OC4J~OCJ4_SECURITY~default_island~1.

Configuring the Agent

You can configure the agent by modifying the following properties in the file AMAgent.properties. The AMAgent.properties file can be found in the following directory:

The following sections explains the properties you need to set for Oracle9iAS R1 and Oracle Application Server 10g.

Policy Agent for Oracle9iAS R1

To configure the agent for Oracle9iAS R1, you must modify the following properties in the file AMAgent.properties:

fetchHeaders

Set this value to true so that additional policy response attributes can be introduced into the HTTP headers.

headerAttributes

This value represents what policy attributes should be added to the HTTP header (if the value of fetchHeaders is true). Set this value to uid|identity-user so that the user id of Sun ONE Identity Server is passed to Login Server.

do_sso_only

Set this value to true so that the agent will just enforce user authentication (SSO) without enforcing policies (authorization). In this integration, Login Server handles authorization.

fqdnDefault

This value is set by the agent installation program to the hostname where the agent is installed. Make sure that this value is a fully qualified domain name. It should be set to hostname.domain. For example, if the machine is called agent1 and the domain is example.com, this property should be set as follows:

fqdnMap

This value must be set manually after the agent is installed. It should be set to hostname|hostname, where hostname is not a fully qualified domain name and represents the machine where the agent is installed. If the machine is called agent1 and the fully qualified domain name of the system is agent1.example.com, the fqdnMap property should be set as follows:

cdsso-enabled

If CDSSO was enabled when the agent was installed, this property will be set automatically. Otherwise, add this property and enable it so that SSO works properly in the Oracle environment.

cdcservletURL

If CDSSO was enabled when the agent was installed, this property will be set automatically. Otherwise, add this property and enable it so that SSO works properly in the Oracle environment. It should be set to http://FQDN hostname:port/amserver/cdcservlet where FQDN hostname is the fully qualified hostname where Sun ONE Identity Server is installed and port is the port where the amserver process is running. For example, if Sun ONE Identity Server is installed on the machine agent2.example.com and listens on port 58080, then this property should be set as follows:

com.sun.am.policy.agents.cdcservletURL = http://agent2.example.com:58080/amserver/cdcservlet

reverse_the_meaning_of_notenforcedList

notenforcedList

When the SSO integration is performed with Oracle Portal 3.0.9, this value must be set to the login pages of both Login Server and Oracle Portal 3.0.9 as follows:

http://hostname:port/pls/portal30_sso/PORTAL30_SSO.wwsec_app_priv.login?p_req uested_url=http%3A%2F%2Fhostname%3Aport%2Fpls%2Fportal30_sso%2FPORTAL30_SS O.home&p_cancel_url=http%3A%2F%2Fhostname%3Aport%2Fpls%2Fportal30_sso%2FPO RTAL30_SSO.home

http://hostname:port/pls/portal30/PORTAL30.wwsec_app_priv.login?p_requested_u rl=http%3A%2F%2Fhostname%3Aport%2Fpls%2Fportal30%2FPORTAL30.home&p_cancel_ url=http%3A%2F%2Fhostname%3Aport%2Fpls%2Fportal30%2FPORTAL30.home

In these examples, hostname is the hostname of the system where the agent is installed and port is the port where the Oracle HTTP Server is running. For example, if the hostname is agent1 and the port is 7779, this value should be set as follows:

com.sun.am.policy.agents.notenforcedList = http://agent1:7779/pls/portal30_sso/PORTAL30_SSO.wwsec_app_priv.login?p_re quested_url=http%3A%2F%2Fagent1%3A7779%2Fpls%2Fportal30_sso%2FPORTAL30_SSO .home&p_cancel_url=http%3A%2F%2Fagent1%3A7779%2Fpls%2Fportal30_sso%2FPORTA L30_SSO.home

http://agent1:7779/pls/portal30/PORTAL30.wwsec_app_priv.login?p_requested_ url=http%3A%2F%2Fagent1%3A7779%2Fpls%2Fportal30%2FPORTAL30.home&p_cancel_u rl=http%3A%2F%2Fagent1%3A7779%2Fpls%2Fportal30%2FPORTAL30.home

logout.url

This value specifies the logout URLs of Login Server and the partner applications. These URLs are never enforced by the agent. When the agent sees any of these URLs, it checks whether a valid session ID for the user still exists. If one does exist, the agent invalidates it and effectively logs the user out of Sun ONE Identity Server. The agent then passes the request onto Login Server so that the logout can be processed there.

In this integration, the logout URL for Login Server and Oracle Portal 3.0.9 are included since Oracle Portal is the partner application chosen for verification. Note that these values are separated by only a space. Here is an example:


Note	If additional Oracle Partner applications are used, then the login pages of those applications must also be added to this list.

com.sun.am.policy.agents.logout.url = http://hostname:port/pls/portal30_sso/PORTAL30_SSO.wwsec_app_priv.logout?p_do ne_url=http%3A%2F%2F<hostname>%3A<port>%2Fpls%2Fportal30_sso%2FPORTAL30_SS O.home http://hostname:port/pls/portal30/PORTAL30.wwsec_app_priv.logout?
p_done_url=http%3A%2F%2F<hostname>%3A<port>%2Fpls%2Fportal30%2FPORTAL30.ho me

Here, the hostname refers to the host where the agent is installed and the port is the port of the Oracle HTTP Server. For example, if the hostname is agent1 and the port is 7779, then this value should be set as follows:

com.sun.am.policy.agents.logout.url=http://agent1:7779/pls/portal30_sso/PO RTAL30_SSO.wwsec_app_priv.logout?p_done_url=http%3A%2F%2Fagent1%3A7779%2Fp ls%2Fportal30_sso%2FPORTAL30_SSO.home

http://agent1:7779/pls/portal30/PORTAL30.wwsec_app_priv.logout?p_done_url= http%3A%2F%2Fagent1%3A7779%2Fpls%2Fportal30%2FPORTAL30.home

logout.cookie_reset_list

This property lists the cookies that need to be reset or removed upon log out from Login Server. If Oracle Portal 3.0.9 is also used for the integration, cookies for both Login Server and Oracle Portal must be present in this list as follows:


Note	If additional Oracle Partner applications are used, then the logout pages for those applications must also be added to this list.

com.sun.am.policy.agents.logout.cookie_reset_list = Domain=, iPlanetDirectoryPro, iPlanetDirectoryPro;Domain=, portal30,portal30;Domain=

Policy Agent for Oracle Application Server 10g


Note	If additional Oracle partner applications are used, then cookies for those applications must also be added to this list so they can be reset/removed upon logout from Login Server.

You can configure the agent for Oracle Application Server 10g by modifying the following properties in the file AMAgent.properties:

fetchHeaders

Set this value to true so that additional policy response attributes can be introduced into the HTTP headers.

headerAttributes

do_sso_only

Set this value to true so that the agent will just enforce user authentication without enforcing policies (authorization). In this integration, Oracle SSO Server handles authorization.

fqdnDefault

reverse_the_meaning_of_notenforcedList

notenforcedList

Since the property reverse_the_meaning_of_notenforcedList is set to true, this property becomes the list of URLs that the agent enforces (in other words, the URLs in this list require user authentication to grant access). For example, if the fully qualified hostname of the system where the Oracle 10g Infrastructure is installed is agent1.example.com and the port where the Oracle SSO Server is running is 7777, then this value should be set as follows:

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*

Note that a space separates the two URLs. Additionally, the value of this property must not change based on the number or type of partner applications. It should always be set as detailed above.

logout.url

This value specifies the logout URLs of Oracle SSO Server and the partner applications. These URLs are never enforced by the agent. When the agent sees any of these URLs, it checks whether a valid session ID for the user still exists. If one does exist, the agent invalidates it, which basically logs the user out of Sun ONE Identity Server. The agent then passes the request onto Oracle SSO Server so that the logout can be processed there. In this integration, the Logout URL for Oracle SSO Server and Oracle Portal 3.0.9 are included since the Oracle Portal is the partner application that was chosen for verification. Note that these values are separated by only a space. Here is an example:

http://hostname:port/pls/portal30/PORTAL30.wwsec_app_priv.logout?p_done_url=h ttp%3A%2F%2F<hostname>%3A<port>%2Fpls%2Fportal30%2FPORTAL30.home

com.sun.am.policy.agents.logout.url=http://agent1:7779/pls/portal30_sso/PO RTAL30_SSO.wwsec_app_priv.logout?p_done_url=http%3A%2F%2Fagent1%3A7779%2Fp ls%2Fportal30_sso%2FPORTAL30_SSO.home

http://agent1:7779/pls/portal30/PORTAL30.wwsec_app_priv.logout?p_done_url= http%3A%2F%2Fagent1%3A7779%2Fpls%2Fportal30%2FPORTAL30.home

logout.cookie_reset_list

This property lists the cookies that need to be reset or removed upon log out from Oracle SSO Server. If Oracle Portal 3.0.9 is also used for the integration, cookies for both Oracle SSO Server and Oracle Portal must be present in this list as follows:


Note	If additional Oracle Partner applications are used, then the logout pages for those applications must also be added to this list.

com.sun.am.policy.agents.logout.cookie_reset_list = Domain=, iPlanetDirectoryPro, iPlanetDirectoryPro;Domain=, portal30,portal30;Domain=


Note	If additional Oracle partner applications are used, then cookies for those applications must also be added to this list so they can be reset/removed upon logout from Oracle SSO Server.

Verifying the Deployment

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