This chapter describes how to configure the Oracle HTTP Server WebGate to enable single sign-on with Oracle Access Manager.
jps-config.xml
file to enable these capabilities.Oracle HTTP Server WebGate is a Web server plug-in that intercepts HTTP requests and forwards them to an existing Oracle Access Manager instance for authentication and authorization.
For Oracle Fusion Middleware 12c, the WebGate software is installed as part of the Oracle HTTP Server 12c software installation.
For more extensive information about WebGate, see Registering and Managing OAM 11g Agents in Adminstrator’s Guide for Oracle Access Management.
Before you can configure Oracle HTTP Server WebGate, you must have installed and configured a certified version of Oracle Access Manager.
At the time this document was published, the supported versions of Oracle Access Manager were 11g Release 2 (11.1.2.2) and 11g Release 2 (11.1.2.3). For the most up-to-date information, see the certification document for your release on the Oracle Fusion Middleware Supported System Configurations page.
Note:
For production environments, it is highly recommended that you install Oracle Access Manager in its own environment and not on the machines that are hosting the enterprise deployment.
For more information about Oracle Access Manager, see the latest Oracle Identity and Access Management documentation, which you can find in the Middleware documentation on the Oracle Help Center.
When you are configuring Oracle HTTP Server Webgate to enable Single Sign-On for an enterprise deployment, consider the prerequisites mentioned in this section.
Oracle recommends that you deploy Oracle Access Manager as part of a highly available, secure, production environment. For more information about deploying Oracle Access Manager in an enterprise environment, see the Enterprise Deployment Guide for your version of Oracle Identity and Access Mangement.
To enable single sign-on for the WebLogic Server Administration Console and the Oracle Enterprise Manager Fusion Middleware Control, you must add a central LDAP-provisioned administration user to the directory service that Oracle Access Manager is using (for example, Oracle Internet Directory or Oracle Unified Directory). For more information about the required user and groups to add to the LDAP directory, follow the instructions in Creating a New LDAP Authenticator and Provisioning Enterprise Deployment Users and Group.
Perform the following steps to configure Oracle HTTP Server 12c WebGate for Oracle Access Manager on both WEBHOST1 and WEBHOST2.
In the following procedure, replace the directory variables, such as OHS_ORACLE_HOME and OHS_CONFIG_DIR, with the values, as defined in File System and Directory Variables Used in This Guide.
Perform a complete backup of the Web Tier domain.
Change directory to the following location in the Oracle HTTP Server Oracle home:
cd
OHS_ORACLE_HOME
/webgate/ohs/tools/deployWebGate/
Run the following command to create the WebGate Instance directory and enable WebGate logging on OHS Instance:
./deployWebGateInstance.sh -w OHS_CONFIG_DIR -oh OHS_ORACLE_HOME
Verify that a webgate
directory and subdirectories was created by the deployWebGateInstance
command:
ls -lart OHS_CONFIG_DIR/webgate/
total 16
drwxr-x---+ 8 orcl oinstall 20 Oct 2 07:14 ..
drwxr-xr-x+ 4 orcl oinstall 4 Oct 2 07:14 .
drwxr-xr-x+ 3 orcl oinstall 3 Oct 2 07:14 tools
drwxr-xr-x+ 3 orcl oinstall 4 Oct 2 07:14 config
Run the following command to ensure that the LD_LIBRARY_PATH
environment variable contains OHS_ORACLE_HOME/lib
directory path:
export LD_LIBRARY_PATH=OHS_ORACLE_HOME/lib
If LD_LIBRARY_PATH
is already set, run the following command:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:OHS_ORACLE_HOME/lib
Change directory to the following directory
OHS_ORACLE_HOME/webgate/ohs/tools/setup/InstallTools
Run the following command from the InstallTools
directory.
./EditHttpConf -w OHS_CONFIG_DIR -oh OHS_ORACLE_HOME -o output_file_name
Note:
The -oh OHS_ORACLE_HOME
and -o output_file_name
parameters are optional.
This command:
Copies the apache_webgate.template
file from the Oracle HTTP Server Oracle home to a new webgate.conf
file in the Oracle HTTP Server configuration directory.
Updates the httpd.conf
file to add one line, so it includes the webgate.conf
.
Generates a WebGate configuration file. The default name of the file is webgate.conf
, but you can use a custom name by using the output_file
argument to the command.
You can register the WebGate agent with Oracle Access Manager using the Oracle Access Manager Administration console.
For more information, see Registering an OAM Agent Using the Console in Administrator's Guide for Oracle Access Management.
You can run the RREG Tool in one of two modes: in-band and out-of-band.
Use in-band mode when you have the privileges to access the Oracle Access Manager server and run the RREG tool yourself from the Oracle Access Manager Oracle home. You can then copy the generated artifacts and files to the Web server configuration directory after you run the RREG Tool.
Use out-of-band mode if you do not have privileges or access to the Oracle Access Manager server. For example, in some organizations, only the Oracle Access Manager server administrators have privileges access the server directories and perform administration tasks on the server. In out-of-band mode, the process can work as follows:
The Oracle Access Manager server administrator provides you with a copy of the RREG archive file (RREG.tar.gz).
Untar the RREG.tar.gz
file that was provided to you by the server administrator.
For example:
gunzip RREG.tar.gz
tar -xvf RREG.tar
After you unpack the RREG archive, you can find the tool for registering the agent in the following location:
RREG_HOME
/bin/oamreg.sh
In this example, RREG_Home
is the directory in which you extracted the contents of RREG archive.
Use the instructions in Updating the Standard Properties in the OAM11gRequest.xml File to update the OAM11GRequest.xml
file, and send the completed OAM11GRequest.xml
file to the Oracle Access Manager server administrator.
The Oracle Access Manager server administrator then uses the instructions in Running the RREG Tool in Out-Of-Band Mode to run the RREG Tool and generate the AgentID_response.xml
file.
The Oracle Access Manager server administrator sends the AgentID_response.xml
file to you.
Use the instructions in Running the RREG Tool in Out-Of-Band Mode to run the RREG Tool with the AgentID_response.xml
file and generate the required artifacts and files on the client system.
Before you can register the Webgate agent with Oracle Access Manager, you must update some required properties in the OAM11gRequest.xml
file.
Note:
If you plan to use the default values for most of the parameters in the provided XML file, then you can use the shorter version (OAM11gRequest_short.xml
, in which all non-listed fields will take a default value.
Note:
In the primary server list, the default names are mentioned as OAM_SERVER1 and OAM_SERVER2 for OAM servers. Rename these names in the list if the server names are changed in your environment.To perform this task:
If you are using in-band mode, then change directory to the following location in the directory:
OAM_ORACLE_HOME/oam/server/rreg/input
If you are using out-of-band mode, then change directory to the location where you unpacked the RREG archive.
Make a copy of the OAM11GRequest.xml
file template.
Review the properties listed in the file, and then update your copy of the OAM11GRequest.xml file to make sure the properties reference the host names and other values specific to your environment.
OAM11gRequest.xml Property | Set to... |
---|---|
serverAddress |
The host and the port of the Administration Server for the Oracle Access Manager domain. |
agentName |
Any custom name for the agent. Typically, you use a name that identifies the Fusion Middleware product you are configuring for single sign-on. |
applicationDomain |
A value that identifies the Web tier host and the FMW component you are configuring for single sign-on. |
security |
The security mode of the Oracle Access Manager server, which can be open, simple, or certificate mode. For an enterprise deployment, Oracle recommends simple mode, unless additional requirements exist to implement custom security certificates for the encryption of authentication and authorization traffic. In most cases, avoid using open mode, because in open mode, traffic to and from the Oracle Access Manager server is not encrypted. For more information using certificate mode or about Oracle Access Manager supported security modes in general, see Securing Communication Between OAM Servers and WebGates in the Administrator's Guide for Oracle Access Management. |
cachePragmaHeader |
private |
cacheControlHeader |
private |
ipValidation |
0 <ipValidation>0<ipValidation> |
ipValidationExceptions |
The IP address of the front-end load balancer. For example: <ipValidationExceptions> <ipAddress>130.35.165.42</ipAddress> </ipValidation> |
agentBaseUrl |
The host and the port of the machine on which Oracle HTTP Server 12c WebGate is installed. |
OAM11gRequest.xml
file. To identify the URLs:The following topics provide information about running the RREG tool to register your Oracle HTTP Server Webgate with Oracle Access Manager.
To run the RREG Tool in in-band mode:
Navigate to the RREG home directory.
If you are using in-band mode, the RREG directory is inside the Oracle Access Manager Oracle home:
RREG_HOME/oam/server/rreg
If you are using out-of-band mode, then the RREG home directory is the location where you unpacked the RREG archive.
In the RREG home directory, navigate to the bin directory:
cd RREG_HOME/bin/
Set the permissions of the oamreg.sh
command so you can execute the file:
chmod +x oamreg.sh
Run the following command:
./oamreg.sh inband input/OAM11GRequest.xml
In this example:
It is assumed the edited OAM11GRequest.xml
file is located in the RREG_HOME/input
directory.
The output from this command will be saved to the following directory:
RREG_HOME/output/
The following example shows a sample RREG session:
Welcome to OAM Remote Registration Tool! Parameters passed to the registration tool are: Mode: inband Filename: /u01/oracle/products/fmw/iam_home/oam/server/rreg/client/rreg/input/OAM11GWCCDomainRequest.xml Enter admin username:weblogic_idm Username: weblogic_idm Enter admin password: Do you want to enter a Webgate password?(y/n): n Do you want to import an URIs file?(y/n): n ---------------------------------------- Request summary: OAM11G Agent Name:WCC1221_EDG_AGENT URL String:null Registering in Mode:inband Your registration request is being sent to the Admin server at: http://host1.example.com:7001 ---------------------------------------- Jul 08, 2015 7:18:13 PM oracle.security.jps.util.JpsUtil disableAudit INFO: JpsUtil: isAuditDisabled set to true Jul 08, 2015 7:18:14 PM oracle.security.jps.util.JpsUtil disableAudit INFO: JpsUtil: isAuditDisabled set to true Inband registration process completed successfully! Output artifacts are created in the output folder.
To run the RREG Tool in out-of-band mode on the WEBHOST server, the administrator uses the following command:
RREG_HOME/bin/oamreg.sh outofband input/OAM11GRequest.xml
In this example:
Replace RREG_HOME with the location where the RREG archive file was unpacked on the server.
The edited OAM11GRequest.xml
file is located in the RREG_HOME/input
directory.
The RREG Tool saves the output from this command (the AgentID_response.xml
file) to the following directory:
RREG_HOME/output/
The Oracle Access Manager server administrator can then send the AgentID_response.xml
to the user who provided the OAM11GRequest.xml
file.
To run the RREG Tool in out-of-band mode on the Web server client machine, use the following command:
RREG_HOME/bin/oamreg.sh outofband input/AgentID_response.xml
In this example:
Replace RREG_HOME with the location where you unpacked the RREG archive file on the client system.
The AgentID_response.xml
file, which was provided by the Oracle Access Manager server administrator, is located in the RREG_HOME/input directory.
The RREG Tool saves the output from this command (the artifacts and files required to register the Webgate software) to the following directory on the client machine:
RREG_HOME/output/
The files that get generated by the RREG Tool vary, depending on the security level you are using for communications between the WebGate and the Oracle Access Manager server. For more information about the supported security levels, see Securing Communication Between OAM Servers and WebGates in Administrator's Guide for Oracle Access Management.
Note that in this topic any references to RREG_HOME
should be replaced with the path to the directory where you ran the RREG tool. This is typically the following directory on the Oracle Access Manager server, or (if you are using out-of-band mode) the directory where you unpacked the RREG archive:
OAM_ORACLE_HOME/oam/server/rreg/client
The following table lists the artifacts that are always generated by the RREG Tool, regardless of the Oracle Access Manager security level.
File | Location |
---|---|
cwallet.sso |
RREG_HOME/output/Agent_ID/ |
ObAccessClient.xml |
RREG_HOME/output/Agent_ID/ |
The following table lists the additional files that are created if you are using the SIMPLE or CERT security level for Oracle Access Manager:
File | Location |
---|---|
aaa_key.pem |
RREG_HOME/output/Agent_ID/ |
aaa_cert.pem |
RREG_HOME/output/Agent_ID/ |
password.xml |
RREG_HOME/output/Agent_ID/ |
Note that the password.xml
file contains the obfuscated global passphrase to encrypt the private key used in SSL. This passphrase can be different than the passphrase used on the server.
You can use the files generated by RREG to generate a certificate request and get it signed by a third-party Certification Authority. To install an existing certificate, you must use the existing aaa_cert.pem
and aaa_chain.pem
files along with password.xml
and aaa_key.pem
.
After the RREG Tool generates the required artifacts, manually copy the artifacts from the RREG_Home/output/agent_ID
directory to the Oracle HTTP Server configuration directory on the Web tier host.
The location of the files in the Oracle HTTP Server configuration directory depends upon the Oracle Access Manager security mode setting (OPEN, SIMPLE, or CERT).
The following table lists the required location of each generated artifact in the Oracle HTTP Server configuration directory, based on the security mode setting for Oracle Access Manager. In some cases, you might have to create the directories if they do not exist already. For example, the wallet directory might not exist in the configuration directory.
Note:
For an enterprise deployment, Oracle recommends simple mode, unless additional requirements exist to implement custom security certificates for the encryption of authentication and authorization traffic. The information about using open or certification mode is provided here as a convenience.
Avoid using open mode, because in open mode, traffic to and from the Oracle Access Manager server is not encrypted.
For more information using certificate mode or about Oracle Access Manager supported security modes in general, see Securing Communication Between OAM Servers and WebGates in Administrator's Guide for Oracle Access Management.
File | Location When Using OPEN Mode | Location When Using SIMPLE Mode | Location When Using CERT Mode |
---|---|---|---|
wallet/cwallet.sso |
OHS_CONFIG_DIR/webgate/config/wallet |
OHS_CONFIG_DIR/webgate/config/wallet/
Note: By default the wallet folder is not available. Create the wallet folder underOHS_CONFIG_DIR/webgate/config/ . |
OHS_CONFIG_DIR/webgate/config/wallet/ |
ObAccessClient.xml |
OHS_CONFIG_DIR/webgate/config |
OHS_CONFIG_DIR/webgate/config/ |
OHS_CONFIG_DIR/webgate/config/ |
password.xml |
N/A | OHS_CONFIG_DIR/webgate/config/ |
OHS_CONFIG_DIR/webgate/config/ |
aaa_key.pem |
N/A | OHS_CONFIG_DIR/webgate/config/simple/ |
OHS_CONFIG_DIR/webgate/config/ |
aaa_cert.pem |
N/A | OHS_CONFIG_DIR/webgate/config/simple/ |
OHS_CONFIG_DIR/webgate/config/ |
Note:
If you need to redeploy theObAccessClient.xml
to WEBHOST1
and WEBHOST2
, delete the cached copy of ObAccessClient.xml
from the servers. The cache location on WEBHOST1
is:
OHS_DOMAIN_HOME/servers/ohs1/cache/
And you must perform the similar step for the second Oracle HTTP Server instance on WEBHOST2
:
OHS_DOMAIN_HOME/servers/ohs2/cache/
For information about restarting the Oracle HTTP Server instance, see Restarting Oracle HTTP Server Instances by Using WLST in Administrator's Guide for Oracle HTTP Server.
If you have configured Oracle HTTP Server in a WebLogic Server domain, you can also use Oracle Fusion Middleware Control to restart the Oracle HTTP Server instances. For more information, see Restarting Oracle HTTP Server Instances by Using Fusion Middleware Control in Administrator's Guide for Oracle HTTP Server.
To set up the WebLogic Server authentication providers, back up the configuration files, set up the Oracle Access Manager Identity Assertion Provider and set the order of providers.
The following topics assumes that you have already configured the LDAP authenticator by following the steps in Creating a New LDAP Authenticator and Provisioning Enterprise Deployment Users and Group. If you have not already created the LDAP authenticator, then do so before continuing with this section.
To be safe, you should first back up the relevant configuration files:
ASERVER_HOME/config/config.xml ASERVER_HOME/config/fmwconfig/jps-config.xml ASERVER_HOME/config/fmwconfig/system-jazn-data.xml
Also back up the boot.properties
file for the Administration Server:
ASERVER_HOME/servers/AdminServer/security/boot.properties
Set up an Oracle Access Manager identity assertion provider in the Oracle WebLogic Server Administration Console.
Some Oracle Fusion Middleware management consoles use Oracle Application Development Framework (Oracle ADF) security, which can integrate with Oracle Access Manager Single Sign On (SSO). These applications can take advantage of Oracle Platform Security Services (OPSS) SSO for user authentication, but you must first configure the domain-level jps-config.xml
file to enable these capabilities.
jps-config.xml
file is located in the following location after you create an Oracle Fusion Middleware domain:
DOMAIN_HOME/config/fmwconfig/jps-config.xml
Note:
The domain-level jps-config.xml
should not be confused with the jps-config.xml
that is deployed with custom applications.
The configurations described in the following sections may be necessary or helpful in providing additional security for your site.
Configure the WebCenter Portal application for SSO by adding a setting to EXTRA_JAVA_PROPERTIES
.
There is a system property that tells WebCenter Portal and ADF that the application is configured in SSO mode and some special handling is required. The following system property is required in this mode:
Field | Value | Comment |
---|---|---|
|
|
This flag tells WebCenter Portal that SSO is being used, so no login form should be displayed on the default landing page. Instead, it displays a login link that the user can click to invoke the SSO authentication. |
To set this property:
This section describes how to configure the discussions server for single sign-on.
Note:
Direct login to the discussions server is not supported after SSO is configured. Log in must be done through the Oracle HTTP Server URL.
To set up the discussions server for SSO:
The WebCenter Portal REST APIs need to be configured for a stateless basic authentication scheme in Oracle Access Manager.
By default, WebCenter Portal RSS feeds are protected by SSO. However, they will not work well with external readers if left protected. If access using external readers is important, Oracle recommends that the WebCenter Portal RSS resource be excluded from the OAM policy so that the authentication for the RSS Servlet is handled by WebLogic Server's BASIC authentication that external readers can handle.
Follow the steps below to unprotect RSS feed for OAM 11g:
This section describes how to optionally set up OAM 11g single sign-on for the WebLogic Server Administration Console and Enterprise Manager.
Notes:
Setting up OAM SSO for Enterprise Manager and the WebLogic Server Administration Console would provide single sign-on access to same set of users for whom OAM SSO access has been configured. If you want the web tier to be accessible to external users through OAM, but want administrators to log in directly to Enterprise Manager and the WebLogic Server Administration Console, then you may not want to complete this additional configuration step.
The OAM policy resource protections may have been completed in the Updating the Protected, Public, and Excluded Resources for an Enterprise Deployment section earlier in this chapter. Note that the rewrite rule for admin SSO logout should still be completed. If you want to reverse that configuration, follow the steps in this section and change the protection level from Protected to Public.
To set up OAM 11g SSO for the WebLogic Server Administration Console and Enterprise Manager:
Log in to the OAM Console using your browser:
http://host:port/oamconsole
From the Launch Pad, select the Application Domains link found in the Access Manager block.
The Policy Manager pane displays.
Locate the application domain you created using the name while registering webgate agent.
Expand the Resources node and click Create.
The Resource page displays.
Add the resources that must be secured. For each resource:
Select http
as the Resource Type.
Select the Host Identifier created while registering the WebGate agent.
Enter the Resource URL for the WebLogic Server Administration Console (/console
) or Enterprise Manager (/em
).
Enter a Description for the resource and click Apply.
Set the Protection Level to Protected
.
Go to Authentication Policies > Protected Resource Policy and add the newly created resource.
Do the same under Authorization Policies > Protected Resource Policy>
On WEBHOST1 and WEBHOST2, update the admin_vh.conf
file and add a RewriteRule to enable SSO logout for the WLS Console.
<VirtualHost WEBHOST1:7777> ServerName admin.example.com:80 ServerAdmin you@your.address RewriteEngine On RewriteOptions inherit # SSO logout redirection for WLS Console RewriteRule ^/console/jsp/common/logout.jsp "/oamsso/logout.html?end_url=/console" [R] </VirtualHost>
Restart the Oracle HTTP Server for your changes to take effect.
You should now be able to access the WebLogic Server Administration Console and Enterprise Manager with the following links:
http://admin.example.com/console http://admin.example.com/em
and be prompted with the OAM SSO login form.
The crawl sources that are defined to crawl WebCenter Portal data and repositories used by WebCenter Portal and the corresponding authentication end points defined in SES must be routed through the Web Tier Oracle HTTP Server ports so that they can be properly authenticated (the authentication method continues to be BASIC and realm jazn.com).
For information about configuring SES connections, see Setting Up Oracle SES Connections in Administering Oracle WebCenter Portal.
Once SSO is functional, the portal connection to Content Server should be updated to set the web context root path. Setting this parameter tells the Document Library code that SSO is configured. Note that the webContextRoot
value should not be set until after SSO has been set up and is functional.
Follow the steps below to only allow users to access WebCenter Portal and associated components through the web tier OHS ports so that they can be properly authenticated.
If you have set up your Portlet Producer applications to route through OHS, be sure to use the OHS host and port when specifying producer URLs for registration. This applies to out of-the-box producers like wsrp-tools, services-producer, pagelet producers and any other producer you have explicitly configured.
Be sure to use the internal load-balancer URL (for example, http://wcp-internal.example.com/...) when specifying producer URLs for registration. This applies to out of-the-box producers like wsrp-tools, services-producer, pagelet producers and any other producer you have explicitly configured.
If you configure WebCenter Portal with SOA Suite, and you also configure Single Sign-On with Oracle Access Manager, you must configure Oracle Access Manager for WebCenter Portal Workflow URLs.
Table 19-3 List of Resources to be Added
Host Identifier | Resource URL | Protection Level | Authentication Policy | Authorization Policy |
---|---|---|---|---|
Your Host | /soa-infra/services/default/CommunityWorkflows/** | Excluded | N/A | N/A |
Your Host | /soa-infra/services/default/CommunityWorkflows* | Excluded | N/A | N/A |
Your Host | /workflow/WebCenterWorklistDetail/** | Unprotected | Public Resource Policy | Public Resource Policy |
Your Host | /workflow/WebCenterWorklistDetail* | Unprotected | Public Resource Policy | Public Resource Policy |