7 Integrating with Oracle Access Manager

This chapter describes how to use Oracle Access Manager to manage user authentication and authorization when a user logs in to Oracle Identity Manager.

This chapter discusses the following topics:

About the Integration with Oracle Identity Manager
Integration Architecture
Preparing the Environment
Configuring Single Sign-On for Oracle Access Manager
Setting Up Oracle Identity Manager for Single Sign-On with Oracle Access Manager
Setting Up Oracle Application Server OC4J Plugin to Communicate with Oracle Access Manager

Note:

This chapter focuses on using JBoss Application Server as the application server in the integration. The same configuration steps apply to instances where Oracle Identity Manager is deployed on IBM WebSphere Application Server, Oracle WebLogic Server, or any other J2EE application server that is supported by Oracle Identity Manager.

7.1 About the Integration with Oracle Identity Manager

The integration of Oracle Access Manager with Oracle Identity Manager provides a secure Web-based infrastructure for identity management for all customer applications and processes. Oracle Access Manager integrates identity and access management across Oracle Identity Manager, enterprise resources, and other domains deployed on e-business networks. Oracle Access Manager provides the foundation for managing the identities of customers, partners, and employees across Internet applications. These user identities are combined with security policies for protected Web interaction.

This integration adds the following features to Oracle Identity Manager implementations:

Oracle Access Manager authentication, authorization, and auditing services for Oracle Identity Manager.
Oracle Access Manager single sign-on for Oracle Identity Manager and other Oracle Access Manager-protected resources within a single domain or across multiple domains.
Oracle Access Manager authentication schemes: The following schemes provide single sign-on authentication for Oracle Identity Manager:
- Basic: Users must enter a user name and password in a window supplied by the Web server.
  
  This method can be redirected to the Secure Sockets Layer (SSL).
- Form: This method is similar to the basic challenge method, but users enter information in the custom HTML form.
  
  You can choose the information that users must provide in the form that you create.
- X509 Certificates: X.509 digital certificates over SSL must be available.
  
  A user's browser must supply a certificate.
- Integrated Windows Authentication (IWA): Users will not notice a difference between an Oracle Access Manager authentication and IWA when they log on to the desktop, open an Internet Explorer (IE) browser, request an Oracle Access Manager-protected Web resource, and complete single sign-on.
- Custom: Additional forms of authentication can be incorporated through use of the Oracle Access Manager Authentication Plug-in API.
Session timeout: Oracle Access Manager enables you to set the length of time that a user session is valid.
Ability to use the Oracle Access Manager Identity System: This system provides identity management features such as user self-service for registration and updating user profiles, portal inserts, delegated administration, and workflows. You can send Identity System data to back-end applications by using a custom data template and a workflow.

7.2 Integration Architecture

Oracle Identity Manager has two authentication mechanisms:

Default mode, where Oracle Identity Manager manages the credential validation and session maintenance.
Single sign-on mode, where Oracle Identity Manager looks for an HTTP header variable that is passed to it.

The header variable should contain the user ID of the Oracle Identity Manager user.

Oracle Access Manager single sign-on with Oracle Identity Manager is achieved as follows:

Deploy the HTTP Server in front of the J2EE Application server.
Deploy the HTTP Server as a reverse proxy.
Deploy a Oracle Access Manager WebGate on the HTTP Server.
Populate a header variable with an attribute value that is stored in the LDAP directory used by Oracle Access Manager.
Configure Oracle Identity Manager to use the single sign-on mode of authentication.

Figure 7-1 shows the architecture for single sign-on between Oracle Identity Manager and Oracle Access Manager.

The user accesses the Oracle Identity Manager Administrative and User Console with a Web browser. The Oracle Access Manager WebGate intercepts the user's HTTP request and checks for the presence of an obSSOCookie. If the cookie does not exist or it has expired, the user is challenged for credentials. Oracle Access Manager verifies the credentials, and if the user is authenticated, the WebGate redirects the user to the requested resource and passes the required header variable to Oracle Identity Manager. Oracle Identity Manager, which has been configured to read an HTTP header variable instead of its authentication, reads the HTTP header and uses the value stored in the variable as the logged-in user.

Figure 7-1 Integration with Oracle Identity Manager

Overview of single sign-on with Oracle Identity Manager

Description of "Figure 7-1 Integration with Oracle Identity Manager"

Process overview: Single sign-on with Oracle Identity Manager

A user attempts to access the Administrative and User Console.
An Oracle Access Manager WebGate that is deployed on the HTTP server intercepts the request.
The WebGate checks the Access Server to determine if the resource (the Oracle Identity Manager URL) is protected.

The security policy in the Access System contains an authentication scheme, authorization rules, and allowed operations based on authentication and authorization success or failure.
If a valid session does not exist, and the resource is protected, the WebGate prompts the user for credentials.
If the credentials are validated, Oracle Access Manager performs the actions that are defined in the security policy for the resource and sets an HTTP header variable that maps to the Oracle Identity Manager user ID.
If a valid session cookie exists, and if the user is authorized to access the resource, the WebGate redirects the user to the requested Oracle Identity Manager resource.
The Administrative and User Console reads the HTTP header variable and sets the value as the logged-in user.
The Administrative and User Console generates the application pages, pending any further authorization checks performed in Oracle Identity Manager.

7.3 Preparing the Environment

Complete the following tasks to prepare your environment for the integration of Oracle Access Manager with Oracle Identity Manager.

Task overview: Preparing your environment for the integration

Install a supported directory server according to vendor instructions.
Install and configure Oracle Access Manager by using the directory server as the Lightweight Direct Access Protocol (LDAP) repository.

See Also:
Oracle Access Manager Installation Guide
Install a WebGate on the Oracle Identity Manager HTTP server.

Do not install the WebGate against an application server that supports HTTP services, for example, Oracle WebLogic Server. If your application server is Oracle Application Server, JBoss Application Server, IBM WebSphere Application Server, or Oracle WebLogic Server, install an HTTP server such as IIS, Apache, iPlanet, or Oracle HTTP Server.

See Also:
Oracle Access Manager Installation Guide
Configure the HTTP server to forward user requests to the J2EE application server and send responses from the Oracle Identity Manager back to the user.
Configure the Web browser to allow cookies, according to vendor instructions.
Set up Oracle Access Manager for Oracle Identity Manager.

7.4 Configuring Single Sign-On for Oracle Access Manager

The following procedure describes how to configure single sign-on for Oracle Access Manager.

To configure single sign-on for Oracle Access Manager

On the welcome page of the Access System, click Policy Manager, and then click Create Policy Domain.
Create a policy domain and policies to restrict access to the Oracle Identity Manager URLs.
In the Access System console, define host identifiers for Oracle Identity Manager.
Click Policy Manager, and then click the link for the Oracle Identity Manager policy domain.
Click the Resources tab and define resources for Oracle Access Manager to protect.
Click the Authorization Rules tab and define an authorization rule to determine authenticated users who can access the Oracle Identity Manager URLs.
Click the Default Rules tab. The Authentication Rule subtab is selected.
Define an authentication rule, for example, Basic Over LDAP.
Click the Actions subtab and define an authorization action that sets a custom HTTP header variable on successful authorization. The header variable should contain a value that maps to the Oracle Identity Manager user ID.
Click the Policies tab.
Click Add and define an access policy in the Oracle Identity Manager policy domain, and add the Oracle Identity Manager URL resources to this policy.

7.5 Setting Up Oracle Identity Manager for Single Sign-On with Oracle Access Manager

The following procedure describes how to set up Oracle Identity Manager for integration with Oracle Access Manager.

To configure single sign-on for Oracle Identity Manager

Stop the application server gracefully.
Start a plain-text editor and open the following file:
```
OIM_HOME/xellerate/config/xlconfig.xml
```
Locate the following single sign-on configuration (the following are the default settings without single sign-on):
```
<web-client>
<Authentication>Default</Authentication>
<AuthHeader>REMOTE_USER</AuthHeader>
</web-client>
```
Edit the single sign-on configuration as follows.

Replace SSO_HEADER_NAME with the appropriate header configured in your single sign-on system:
```
<web-client>
<Authentication>SSO</Authentication>
<AuthHeader>SSO_HEADER_NAME</AuthHeader>
</web-client>
```
To enable single sign-on with non-ASCII character logins, you must include a decoding class name to decode the non-ASCII header value. Add the decoding class name and edit the single sign-on configuration as follows:
```
<web-client>
<Authentication>SSO</Authentication>
<AuthHeader>SSO_HEADER_NAME</AuthHeader>
<AuthHeaderDecoder>com.thortech.xl.security.auth.CoreIDSSOAuthHeaderDecoder</AuthHeaderDecoder>
</web-client>
```
Replace SSO_HEADER_NAME with the appropriate header configured in your single sign-on system.
Change your application server and Web server configuration to enable single sign-on.

If you are using Oracle Application Server, then see "Setting Up Oracle Application Server OC4J Plugin to Communicate with Oracle Access Manager" for information about performing this step. If you are using any other application server, then see your application server and Web server vendor documentation for details.
Restart the application server.

7.6 Setting Up Oracle Application Server OC4J Plugin to Communicate with Oracle Access Manager

Note:

The information in this section is based on IIS version 6.0. See your application and Web server vendor's documentation for more information about configuring single sign-on.

Several different configurations, including application and Web servers, are possible in an Oracle Identity Manager and Oracle Access Manager environment. This section demonstrates one possible configuration to integrate Oracle Identity Manager with Oracle Access Manager by using Oracle Application Server and the Internet Information Services (IIS) plug-in of the application server (Oracle Application Server OC4J Plugin).

You must install and configure the plug-in so that Oracle Application Server can communicate with the Oracle Access Manager server. The Oracle Application Server OC4J Plugin plug-in is a file named opii.dll.

To install and configure the Oracle Application Server OC4J Plugin

Download the Oracle Application Server OC4J Plugin from Oracle Technology Network (OTN) by using the following steps.
1. Go to the OTN Web site at the following URL:
  
  http://www.oracle.com/technology/index.html
2. Click Downloads on the horizontal navigation menu at the top of the page.
3. Scroll to the Middleware section of the page and click SOA Suite in the Developer Tools section.
4. Click See All in the Oracle SOA Suite 10g Release 3 (10.1.3.x) section.
5. In the page that is displayed, accept the License Terms and Export Restrictions and also the Oracle Technology Network Development License Agreement.
6. Expand the Oracle SOA Suite 10g Companion (10.1.3.x) CD entry. In the list that is displayed, the Oracle Application Server OC4J Plugin is listed as a component.
7. Click CD1 for the appropriate operating system to download CD1 for the Oracle SOA Suite 10g Companion (10.1.3.x) CD.
Open the Registry Editor and perform the following steps:

Note:
This procedure uses sample steps by using regedit.
1. Click HKEY_LOCAL_MACHINE, and then click SOFTWARE.
2. Right-click Oracle and select New. Then select Key and name it opii.
3. Right-click the opii entry, select New. Then select String Value and name the String Value log_file.
4. Right-click the log_file entry and select Modify. The Edit String dialog box is displayed.
5. In the Value data field, enter the path where you want to keep the opii log file and click OK.
6. Right-click the opii entry, and then select New.
7. Select String Value and name the String Value log_level. This log_level string value specifies the desired log level for opii, for which debug, inform, error, and emerg are valid values.
8. Right-click the opii entry, and then select New. Then select String Value and name the String Value server_defs.
9. Right-click the server_def String Value and select Modify. The Edit String dialog box is displayed.
10. Enter the path where the opii.conf file will reside. You will create the opii.conf file in Step 10.
Start the IIS Management Console, then expand the entry for the node hosting the IIS server that will communicate with the Oracle Access Manager server.
Expand the Web Sites entry, then right-click the Default Web Sites entry and then select New. After this, select Virtual Directory. The Virtual Directory Creation Wizard is displayed.
Click Next and perform the following steps:
1. Enter opii in the Alias Name field and click Next.
2. Enter the location of the opii.dll file in the Path field and click Next.
3. Select the Read, Run scripts, and Execute options on the Virtual Directory Access Permissions screen and click Next.
4. Click Finish to close the Virtual Directory Creation Wizard.
Add the opii.dll Oracle Application Server OC4J Plugin as a filter to your IIS Web sites by using the following steps:
1. In the IIS Management Console, right-click the Default Web Sites entry and select Properties. The Default Web Site Properties dialog box is displayed.
2. Click the ISAPI Filters tab, and then click Add.
3. Enter opii in the Filter Name field.
4. Enter the path of the opii.dll Oracle Application Server OC4J Plugin in the Executable field.
5. Click OK on the Add/Edit Filter Properties dialog box.
6. Click OK on the Default Web Site Properties dialog box.
  
  Note:
  Ensure that the opii filter has a lower priority than the WebGate filter.
Restart the IIS server by using the following steps in the IIS Management Console:
1. Right-click the node hosting the IIS server that will communicate with the Oracle Access Manager server. Select All Tasks, and then select Restart IIS. The Stop/Start/Restart dialog box is displayed.
2. Select Restart Name_of_IIS_server and click OK.
3. After the IIS server restarts, verify that the opii.dll Oracle Application Server OC4J Plugin is running by right-clicking Default Web Sites, selecting Properties, selecting the ISAPI Filters tab, and confirming that there is a green arrow pointing up for the opii filter.
On the IIS Management Console, click Web Services Extensions, select opii, and then click the Allow button.
Identify the port for the ajp13 protocol by using the following steps:
1. On the computer hosting the Oracle Application Server, open the OAS_HOME/j2ee/OAS_INSTANCE/config/default-web-site-.xml file in a text editor.
  
  Note:
  OAS_HOME represents the location in which Oracle Application Server is installed.
  OAS_INSTANCE represents the name of the Oracle Application Server instance.
2. Search for the string ajp13.
3. Identify the port number for ajp13, for example 8889.

Create a file named opii.conf in the opii directory that contains the following entries. The entries list the Oracle Identity Manager applications protected by OracleAS Single Sign-On, the name of the computer hosting Oracle Identity Manager (for example, host_name), and the port number for ajp13 (for example, ajp13 port number).

Oc4jMount/xlWebApp ajp13://host_name:ajp13 port number
Oc4jMount/xlWebApp/* ajp13://host_name:ajp13 port number
Oc4jMount/xlScheduler ajp13://host_name:ajp13 port number
Oc4jMount/xlScheduler/* ajp13://host_name:ajp13 port number
Oc4jMount/Nexaweb ajp13://host_name:ajp13 port number
Oc4jMount/Nexaweb/* ajp13://host_name:ajp13 port number