5 Configuring Oracle Role Manager for Single Sign-On

This chapter describes managing user authentication and authorization by using Oracle Access Manager when a user logs into Oracle Role Manager.

This chapter covers the following topics:

• About the Single Sign-On Configuration with Oracle Role Manager

• Configuration Design

• Configuring Apache As a Proxy for JBoss

• Configuring Apache As a Proxy for WebLogic

• Configuring Apache as a Proxy for WebSphere

• Setting Up a WebGate on an HTTP Server

• Setting Up Oracle Access Manager for Single Sign-On With Oracle Role Manager

5.1 About the Single Sign-On Configuration with Oracle Role Manager

Oracle Role Manager has two authentication mechanisms:

• Default mode, where Oracle Role Manager manages the credential validation and session maintenance.

• Single sign-on (SSO) mode, where HTTP header variable is used by the SSO system to communicate with Oracle Role Manager.

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

The configuration of Oracle Access Manager with Oracle Role Manager provides a secure web-based infrastructure for role management for all customer applications and processes. Oracle Access Manager integrates identity and access management across Oracle Role Manager, enterprise resources, and other domains deployed on eBusiness 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.

Note:

Oracle certifies Oracle Access Manager for SSO configuration with Oracle Role Manager, but you can use any other SSO providers.

The configuration of Oracle Access Manager with Oracle Role Manager adds the following features to Oracle Role Manager implementations:

• Oracle Access Manager authentication and authorization services for Oracle Role Manager.

• Oracle Access Manager single sign-on for Oracle Role Manager and other Oracle Access Manager-protected resources within a single domain or across multiple domains.

• Oracle Access Manager authentication schemes, which provide a single sign-on for Oracle Role Manager such as, users must enter a user name and password in a window supplied by the web server.

• Session timeout, Oracle Access Manager enables you to set the length of time for a user session to be valid.

• Oracle Access Manager authentication schemes, the following schemes provide single sign-on 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 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 users must provide in the form that you create.

  • X509 Certificates: X.509 digital certificates over SSL.

    A user's browser must supply a certificate.

  • Integrated Windows Authentication (IWA): Open an Internet Explorer (IE) browser, request a Oracle Access Manager-protected Web resource to complete single sign-on.

  • Custom: Additional forms of authentication can be incorporated through use of the Oracle Access Manager Authentication Plug-in API.

5.2 Configuration Design

To achieve the Oracle Access Manager single sign-on with Oracle Role Manager:

• Deploy an HTTP Server in front of the J2EE application server on which the Oracle Role Manager is deployed.

• Deploy the HTTP Server as a reverse proxy.

• Deploy a WebGate on the HTTP Server.

  See Also:

  Oracle Access Manager Installation Guide for more information about setting up a WebGate on an HTTP server.

• Populate a header variable with an attribute value that is stored in the LDAP directory used by Oracle Access Manager.

• Configure Oracle Role Manager to use the single sign-on mode of authentication.

Figure 5-1 shows the configuration design for single sign-on between Oracle Role Manager and Oracle Access Manager.

When configured, Oracle Access Manager enables Single Sign-On between Oracle Role Manager Web UI and another application.

You can access the administrative console with a web browser. The WebGate intercepts the your HTTP request and checks for the presence of an obSSOCookie. If the cookie does not exist or it has expired, an error message is shown asking you to verify the credentials.

On the Oracle Role Manager side, there is a J2EE Servlet Filter, which is configured to intercept requests to the faces servlet. The filter verifies if the user is authenticated, that is if the user has a ClientEntity in the session, and allows the request to proceed if the value is true. If the user is not authenticated, then the filter looks for a particular header, configured by the filter's configuration in the web.xml file, to use as the person identifier. If the header is present, then the header's value is used to create a ClientEntity that the Web UI uses for the rest of the session.

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 a 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 5-1 shows the configuration design of Oracle Role Manager for single sign-on.

Figure 5-1 Configuration Design of Oracle Role Manager for Single Sign-On

Description of "Figure 5-1 Configuration Design of Oracle Role Manager for Single Sign-On"

The following steps demonstrate the single sign-on process:

1. A user attempts to access Oracle Role Manager Web UI.

2. A WebGate that is deployed on the HTTP server intercepts the request.

3. The WebGate checks the Access Server to determine if the resource (the Oracle Role 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.

4. If a valid session does not exist, and the resource is protected, WebGate prompts the user for credentials.

5. 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 Role Manager user ID.

6. If a valid session cookie exists, and if the user is authorized to access the resource, WebGate redirects the user to the requested Oracle Role Manager resource.

7. The administrative console reads the HTTP header variable and sets the value as the logged-in user.

8. The administrative console generates the applications pages, pending any further authorization checks performed in Oracle Role Manager.

5.2.1 Preparing Your Environment

To prepare your environment for the integration, perform the following steps:

1. Install a supported directory server according to vendor instructions, for example, iPlanet.

2. Install and configure Oracle Access Manager using the directory server as the LDAP repository.

3. Ensure that the Oracle Role Manager J2EE application server is proxied by an HTTP server (Apache 2.0).

4. Configure the Web browser (Internet Explorer) to allow cookies, according to vendor instructions.

5. Ensure that user IDs in Oracle Role Manager and Oracle Access Manager are same.

5.2.2 Setting Up Oracle Role Manager for Single Sign-On

To configure Oracle Role Manager for single sign-on with Oracle Access Manager, perform the following procedure:

1. Extract webui.ear and locate the file web.xml. The file is present in the WEB-INF directory.

2. Open the web.xml file in a text editor.

3. Locate the following section:

   <filter>
   <filter-name>SSO Filter</filter-name>
   <filter-class>oracle.iam.rm.ui.webapp.SSOInterceptor</filter-class>
   <init-param>
   <param-name>httpHeader</param-name>
   <param-value>username</param-value>
   </init-param>
   <init-param>
   <param-name>alternativeWelcome</param-name>
   <param-value>/pages/inbox/find_outbox.jsf</param-value>
   </init-param>
   </filter>
   

4. Replace the value username with a name such as ORM_UID.

   Note:

   The name can be any value, but the same name is to be used for header variable while creating access policy in OAM Access System.

5. Save and close the file.

6. Disable the logout link by opening the header.xhtml file present in the pages/components folder and add an attribute rendered="false" to the commandLink tag with an attribute id="logout".

   You can achieve this by replacing the tag:

   <h:commandLink id="logout" value="#{b:text('button.signout')}" action="#{ClientSession.gotoSignoutAction}"/>
   

   with

   <h:commandLink id="logout" value="#{b:text('button.signout')}" action="#{ClientSession.gotoSignoutAction}" rendered="false"/>
   

7. Re-create the file webui.war.

8. Deploy the WAR file, webui.war to the application server.

5.3 Configuring Apache As a Proxy for JBoss

Oracle Role Manager runs on a J2EE application server, for example, JBoss, WebLogic, and WebSphere. You cannot install an AccessGate directly in front of these application servers. You can deploy a Web server, for example, Apache, in front of these application servers. You can deploy the AccessGate on the web server, and configure the web server to route requests to the Oracle Role Manager Application and forward responses back to the user.

For application servers such as JBoss, you must deploy an additional plug-in, referred to as the mod_jk plug-in or the JBoss plug-in, on the Web server.

To configure the Apache HTTP server as a proxy for JBoss:

1. Download and install Apache HTTP Server 2.0.63.

2. Download the latest stable version of mod_jk 1.2.26 binary that supports the installed Apache HTTP Server, from the following URL:

   http://www.apache.org/dist/jakarta/tomcat-connectors/jk/binaries/

3. Rename it to mod_jk.so.

4. Copy this file to the following directory:

   Apache_install_dir/modules

5. Modify Apache_install_dir /conf/httpd.conf and add a single line at the end of the file:

   # Include mod_jk's specific configuration file

   include conf/mod-jk.conf

6. Create the following text files in the directory Apache_install_dir\conf:

   • mod-jk.conf

   • workers.properties

   • uriworkermap.properties

     Oracle recommends that you do not rename uriworkermap.properties and workers.properties. If you do, your configuration may stop working. The locations of these files are defined under two registry keys: worker_file and worker_mount_file. These files are in HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\version_number.

7. Copy the following configuration into the mod-jk.conf file:

   # Load mod_jk module
   # Specify the filename of the mod_jk lib
   LoadModule jk_module modules/mod_jk.so
    
   # Where to find workers.properties
   JkWorkersFile conf/workers.properties
    
   # Where to put jk logs
   JkLogFile logs/mod_jk.log
    
   # Set the jk log level [debug/error/info]
   JkLogLevel info 
    
   # Select the log format
   JkLogStampFormat  "[%a %b %d %H:%M:%S %Y]"
    
   # JkOptions indicates to send SSK KEY SIZE
   JkOptions +ForwardKeySize +ForwardURICompat -ForwardDirectories
    
   # JkRequestLogFormat
   JkRequestLogFormat "%w %V %T"
                  
   # Mount your applications
   JkMount /application/* loadbalancer
    
   # You can use external file for mount points.
   # It will be checked for updates each 60 seconds.
   # The format of the file is: /url=worker
   # /examples/*=loadbalancer
   JkMountFile conf/uriworkermap.properties               
    
   # Add shared memory.
   # This directive is present with 1.2.10 and
   # later versions of mod_jk, and is needed for
   # for load balancing to work properly
   JkShmFile logs/jk.shm 
     
   # Add jkstatus for managing runtime data
   <Location /jkstatus/>
       JkMount status
       Order deny,allow
       Deny from all
       Allow from 127.0.0.1
   </Location>
   

8. Copy the following into the workers.properties file:

   Note:

   The local values <Host IP or DNS Name> must be substituted in the following command.

   # Define list of workers that will be used
   # for mapping requests
   worker.list=loadbalancer,status
    
   # Define Node1
   # modify the host as your host IP or DNS name.
   worker.node1.port=8009
   worker.node1.host=<host IP or DNS Name>
   worker.node1.type=ajp13
   worker.node1.lbfactor=1
   worker.node1.cachesize=10
    
   # Load-balancing behaviour
   worker.loadbalancer.type=lb
   worker.loadbalancer.balance_workers=node1
   worker.loadbalancer.sticky_session=1
   #worker.list=loadbalancer
    
   # Status worker for managing load balancer
   worker.status.type=status
   

9. Copy the following into the uriworkermap.properties file:

   # Simple worker configuration file
    
   # Mount the Servlet context to the ajp13 worker
   /jmx-console=loadbalancer
   /jmx-console/*=loadbalancer
   /web-console=loadbalancer
   /web-console/*=loadbalancer
   /webui=loadbalancer
   /webui/*=loadbalancer
   /ormconsole=loadbalancer
   /ormconsole/*=loadbalancer
   

10. Edit JBOSS_HOME/server/all/deploy/jbossweb-tomcat50.sar/server.xml (replace /all with your own server name) and locate the <Engine….> element and add an attribute jvmRoute:

    <Engine name="jboss.web" defaultHost="localhost" vmRoute="node1">
    </Engine>
    

11. Edit JBOSS_HOME/server/all/deploy/jbossweb-tomcat50.sar/META-INF/jboss-service.xml (replace /all with your own server name) and locate the <attribute> element with a name of UseJK and set its value to "true":

    <attribute name="UseJK">true</attribute>
    

12. Start the Apache server and test the installation.

5.4 Configuring Apache As a Proxy for WebLogic

To configure the Apache HTTP server as a proxy for WebLogic:

1. Download and install Apache HTTP Server 2.0.63.

2. Download the apache plugin(s) for WebLogic 10.3 from the following location: http://download.oracle.com/otn/bea/weblogic/server103/server103_apacheplugins.zip

3. Copy the appropriate mod_wl_20.so from server103_apacheplugins.zip into Apache_install_dir/modules.

   Note:

   Appropriate mod_wl_20.so means, if WebLogic is installed on Win 32 machine, then you must copy \win\32\mod_wl_20.so from server103_apacheplugins.zip.

4. Modify Apache_install_dir /conf/httpd.conf to add the following at the end of the file:

   LoadModule weblogic_module modules/mod_wl_20.so
   <IfModule mod_weblogic.c>
   WebLogicHost <hostname>
   WebLogicPort <port>
   </IfModule>
   <LocationMatch ^/webui>
   SetHandler weblogic-handler
   </LocationMatch>
   

   Note:

   Replace <hostname> and <port> for the appropriate values from the WebLogic Installation.

5. In the WebLogic domain configuration, add the following element:

   <enforce-valid-basic-auth-credentials>false</enforce-valid-basic-auth-credentials>
   

   to the last line of <security-configuration> in config.xml for the users domain, usually in DOMAIN_NAME/config/config.xml. This keeps WebLogic from trying to authenticate basic authentication headers.

5.5 Configuring Apache as a Proxy for WebSphere

To configure the Apache HTTP server as a proxy for WebSphere:

1. Download and install Apache HTTP Server 2.0.63 or Apache HTTP Server 2.2.11.

2. Copy mod_ws_20.so from websphere_install\server\plugin\win32 into modules in Apache_install_dir/modules.

3. Modify Apache_install_dir /conf/httpd.conf to add the following at the end of the file:

   LoadModule proxy_module modules/mod_proxy.so
   LoadModule proxy_http_module modules/mod_proxy_http.so
   LoadModule rewrite_module modules/mod_rewrite.so
    
   ProxyRequests Off
   <Proxy>
      Order deny,allow
      Allow from all
   </Proxy>
   

   RewriteEngine on

   ProxyPass /webui/ http://localhost:9080/webui/
   ProxyPassReverse /webui/ http://localhost:9080/webui/
   RewriteRule ^/webui$ /webui/ [R]
   

5.6 Setting Up a WebGate on an HTTP Server

To set up a WebGate on an HTTP server:

1. Install and configure Oracle Access Manager on a supported platform, using a supported LDAP server.

2. Create an AccessGate and install it on the Apache server.

   The following is the sample configuration for an access gate:

   AccessGate Name: AccessGate_Apache

   State: Enabled

   Hostname: <hostname where Apache is installed>

   Port: 80

   AccessGate Password: abcd1234

   Access Management Service: On

   Primary HTTP Cookie Domain: idc.oracle.com

   Preferred HTTP Host: <hostname where Apache is installed>

3. Associate the Access Server.

See Also:

Oracle Access Manager Installation Guide for more information about setting up a WebGate on an HTTP server.

5.7 Setting Up Oracle Access Manager for Single Sign-On With Oracle Role Manager

To configure Oracle Access Manager for single sign-on with Oracle Role Manager, perform the following procedure:

1. In the landing page for the Access System, click Policy Manager and then click Create Policy Domain.

2. Create a policy domain and policies to restrict access to the Oracle Role Manager URLs.

3. In the Access System Console, define host identifiers for Oracle Role Manager.

4. Go to Policy Manager, Oracle Role Manager policy domain, Resources tab, and define resources for Oracle Access Manager to protect. Table 5-1 shows the resource definition for Oracle Access Manager.

   Table 5-1 Resource Definition

   Resource	Resource Type	URL Prefix	Description
   All	http	/webui	webui

   
   

5. Click the Authorization Rules tab and define an authorization rule to determine which authenticated users can access the Oracle Role Manager URLs. Table 5-2 shows the authorization rules for the users who access Oracle Role Manager.

   Table 5-2 Authorization Rules

   Authorization Rules
   Name	authz
   Description	authz
   Enabled	Yes
   Allow takes precedence	No
   On Success HTTP Header Variable	Type headervar	Name ORM_UID	Return Attribute uid
   HTTP Header Variable Allow Access Role	Any one

   
   

6. Click the Default Rules tab. The Authentication Rule subtab is selected. Perform the following steps:

   1. Define an authentication rule, for example, Basic Over LDAP.

   2. Click the Actions subtab and define an authorization action that sets a custom HTTP header variable upon successful authorization.

      The header variable must contain a value that maps to the Oracle Role Manager user ID. Table 5-3 shows the authorization expression for the custom HTTP header variable.

      Table 5-3 Authorization Expression for Custom HTTP Header Variable

      Default Rules
      	Authentication Rule
      	Authentication Scheme	authn Basic Over LDAP
      	On Success
      	HTTP Header Variable	Type headervar	Name ORM_UID	Return Attribute uid
      	HTTP Header Variable
      	Authorization Expression
      	Expression	authz
      	Duplicate Actions	No policy defined for this Authorization Expression. The Access System level default policy for dealing with duplicate action headers will be employed.
      	On Success
      	HTTP Header Variable	Type headervar	Name ORM_UID	Return Attribute uid
      	HTTP Header Variable
      	Audit Rule
      	There is no Audit Rule defined

      
      

7. Click the Policies tab, and then click Add. Define an access policy in the Oracle role Manager policy domain and add the Oracle Role Manager URL resources to this policy. Table 5-4 shows the access policy to add the Oracle Role Manager URL resources to it.

   Table 5-4 Access Policy

   Policy
   	Name	webui
   	Description	webui
   	Resource Type	http
   	Resource Operation(s)	GET POST PUT HEAD OPTIONS CONNECT
   	Resource	all
   	Authentication Rule
   	Authentication Scheme	authn Basic Over LDAP
   	On Success
   	HTTP Header Variable	Type HeaderVar	Name ORM_UID	Return Attribute uid
   	HTTP Header Variable
   	Authorization Expression
   	Expression	authz
   	Duplicate Actions	No policy defined for this Authorization Expression. The Access System level default policy for dealing with duplicate action headers will be employed.
   	On Success
   	HTTP Header Variable	Type headervar	Name ORM_UID	Return Attribute uid
   	HTTP Header Variable
   	Audit Rule
   	There is no Audit Rule defined

   
   

   See Also:

   Oracle Access Manager Installation Guide for more information.