22 Configuring Single Sign-On for an Enterprise Deployment

You need to configure the Oracle HTTP Server WebGate in order to enable single sign-on with Oracle Access Manager.

• About Oracle Webgate
  Oracle 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.
• General Prerequisites for Configuring Oracle HTTP Server WebGate
  Before you can configure Oracle HTTP Server WebGate, you must have installed and configured a certified version of Oracle Access Manager.
• Configuring Oracle HTTP Server 12c WebGate for an Enterprise Deployment
  You need to perform the following steps in order to configure Oracle HTTP Server 12c WebGate for Oracle Access Manager on both WEBHOST1 and WEBHOST2.
• Enabling OAM Rest OAP Calls
  In Oracle Access Manager 12c, WebGate interacts with Oracle Access Manager through REST API calls. In order for WebGate to have unrestricted access to these Rest APIs, you need to update the WEB_CONFIG_DIR/webgate.conf file.
• Adding a Load Balancer Certificate to WebGate
  Oracle WebGate 12c uses REST calls to interact with Oracle Access Manager 12c. To ensure that the communication works properly, you have to copy the load balancer certificates to WebGate Config and ensure that the REST endpoints are set correctly.
• Copying WebGates Artifacts to Web Tier
  When you created your Oracle Access Management installation, a WebGate called Webgate_IDM was created. In order for WebGate to communicate with the Access servers, you must copy the artifacts associated with this WebGate to the web tier.
• Restarting the Oracle HTTP Server Instance
  
• Setting Up the WebLogic Server Authentication Providers
  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.
• Configuring Oracle ADF and OPSS Security with Oracle Access Manager
  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.

About Oracle Webgate

Oracle 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 Oracle WebGate software is installed as part of the Oracle HTTP Server 12c software installation. See Registering and Managing OAM 11g Agents in Adminstrator’s Guide for Oracle Access Management. Oracle WebGate is available for Oracle HTTP Server.

General Prerequisites for Configuring Oracle HTTP Server WebGate

Before you can configure Oracle HTTP Server WebGate, you must have installed and configured a certified version of Oracle Access Manager.

For the most up-to-date information, see the certification document for your release on the Oracle Fusion Middleware Supported System Configurations page.

For WebGate certification matrix, click and open http://www.oracle.com/technetwork/middleware/id-mgmt/downloads/oam-webgates-2147084.html, then click the Certification Matrix for 12c Access Management WebGates link to download the certification matrix spreadsheet.

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.

Note:

It is recommended that you use the WebGate version that is certified with your Oracle Access Manager 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.

Configuring Oracle HTTP Server 12c WebGate for an Enterprise Deployment

You need to perform the following steps in order 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 WEB_ORACLE_HOME and WEB_CONFIG_DIR, with the values, as defined in File System and Directory Variables Used in This Guide.

1. Perform a complete backup of the web tier domain.

2. Change directory to the following location in the Oracle HTTP Server Oracle home:

   cd WEB_ORACLE_HOME/webgate/ohs/tools/deployWebGate/

3. Run the following command to create the WebGate Instance directory and enable WebGate logging on OHS Instance:

   ./deployWebGateInstance.sh -w WEB_CONFIG_DIR -oh WEB_ORACLE_HOME

   For example:

   ./deployWebGateInstance.sh -w /u02/private/oracle/config/domains/ohsDomain/config/fmwconfig/components/OHS/ohs1 -oh /u01/oracle/products/web

4. Verify that a webgate directory and subdirectories was created by the deployWebGateInstance command:

   ls -lat WEB_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
   

5. Run the following command to ensure that the LD_LIBRARY_PATH environment variable contains WEB_ORACLE_HOME/lib directory path:

   export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:WEB_ORACLE_HOME/lib

6. Change directory to the following directory

   WEB_ORACLE_HOME/webgate/ohs/tools/setup/InstallTools

7. Run the following command from the InstallTools directory.

   ./EditHttpConf -w WEB_CONFIG_DIR -oh WEB_ORACLE_HOME -o output_file_name

   For example:

   ./EditHttpConf -w /u02/private/oracle/config/domains/ohsDomain/config/fmwconfig/components/OHS/ohs1 -oh /u01/oracle/products/web

   Note:

   The -oh WEB_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 -o output_file_name argument to the command.

Enabling OAM Rest OAP Calls

In Oracle Access Manager 12c, WebGate interacts with Oracle Access Manager through REST API calls. In order for WebGate to have unrestricted access to these Rest APIs, you need to update the WEB_CONFIG_DIR/webgate.conf file.

For example:

/u02/private/oracle/config/domains/webtier_domain/config/fmwconfig/components/OHS/ohs1/webgate.conf

To update WEB_CONFIG_DIR/webgate.conf:

1. Add the following lines:

   <LocationMatch "/iam/access/binding/api/v10/oap">
       require all granted
   </LocationMatch>

2. Save the file.

Adding a Load Balancer Certificate to WebGate

Oracle WebGate 12c uses REST calls to interact with Oracle Access Manager 12c. To ensure that the communication works properly, you have to copy the load balancer certificates to WebGate Config and ensure that the REST endpoints are set correctly.

• Copying the LoadBalancer Certificates to WebGate Config
  
• Ensuring that the REST Endpoints are Set Correctly
  

Copying the LoadBalancer Certificates to WebGate Config

WebGate needs to trust your load balancer certificate. To ensure this trust, you should add the load balancer's certificate to the cacert.pem file, which is located in WEB_CONFIG_DIR/webgate/config.

You can obtain the certificate from the load balancer using a browser, such as Firefox. However, the easiest way to obtain the certificate is to use the openssl command. The syntax of the command is as follows:

openssl s_client -connect LOADBALANCER:PORT -showcerts </dev/null 2>/dev/null|openssl x509 -outform PEM > LOADBALANCER.pem

For example:

openssl s_client -connect login.example.com:443 -showcerts </dev/null 2>/dev/null|openssl x509 -outform PEM > login.example.com.pem

This command saves the certificate to a file named login.example.com.pem.

If you do not have load balancer certificates in your WebGate truststore, copy the login.example.com.pem file to WEB_CONFIG_DIR/webgate/config renaming it to cacert.pem.

For example:

cp login.example.com.pem WEB_CONFIG_DIR/webgate/config/cacert.pem

If you already have trusted certificates in WebGate, append the certificate to the cacert.pem file.

For example:

cp login.example.com.pem >> WEB_CONFIG_DIR/webgate/config/cacert.pem

Ensuring that the REST Endpoints are Set Correctly

To ensure that the REST endpoints are set correctly:

1. Log in to the OAM Console using your oam administrator account.
2. Click Agents.
3. Click Search.
4. Locate and click the name of the WebgGate agent from the search results to bring up the edit screen.
5. Expand the User Properties screen and check that the following parameters are defined correctly:
   • OAMRestEndPointHostName = login.example.com
   • OAMRestEndPointPort = 443
   • OAMServerCommunicationMode = HTTPS

   These values should reflect the login point of your Oracle Access Manager installation. If unsure about these values, contact your OAM administrator.

Copying WebGates Artifacts to Web Tier

When you created your Oracle Access Management installation, a WebGate called Webgate_IDM was created. In order for WebGate to communicate with the Access servers, you must copy the artifacts associated with this WebGate to the web tier.

• Copying Generated Artifacts to the Oracle HTTP Server WebGate Instance Location
  

Copying Generated Artifacts to the Oracle HTTP Server WebGate Instance Location

After you run the idmTool configOAM, it creates a WebGate agent called Webgate_IDM. The process creates a number of artifacts relating to that agent in IAD_ASERVER_HOME/output/Webgate_IDM. These artifacts have to be copied to the Oracle HTTP Server configuration directory on the Web Tier hosts.

The location of the files in the Oracle HTTP Server configuration directory depends on 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 about using certificate mode or about Oracle Access Manager supported security modes, see Securing Communication Between OAM Servers and WebGates in Administrator's Guide for Oracle Access Management.

Table 22-1 Web Tier Host Location to Copy the Generated Artifacts

File	Location When Using SIMPLE Mode	Location When Using CERT Mode
wallet/cwallet.ssoFoot 1	WEB_CONFIG_DIR/webgate/config/wallet/ By default the wallet folder is not available. Create the wallet folder under WEB_CONFIG_DIR/webgate/config/.	WEB_CONFIG_DIR/webgate/config/wallet/
ObAccessClient.xml	WEB_CONFIG_DIR/webgate/config/	WEB_CONFIG_DIR/webgate/config/
password.xml	WEB_CONFIG_DIR/webgate/config/	WEB_CONFIG_DIR/webgate/config/
aaa_key.pem	WEB_CONFIG_DIR/webgate/config/simple/	WEB_CONFIG_DIR/webgate/config/
aaa_cert.pem	WEB_CONFIG_DIR/webgate/config/simple/	WEB_CONFIG_DIR/webgate/config/

^Footnote 1 Copy cwallet.sso from the wallet folder and not from the output folder. Even though there are 2 files with the same name they are different. The one in the wallet sub directory is the correct one.

Note:

If you need to redeploy the ObAccessClient.xml to WEBHOST1 and WEBHOST2, delete the cached copy of ObAccessClient.xml and its lock file, ObAccessClient.xml.lck from the servers. The cache location on WEBHOST1 is:

WEB_DOMAIN_HOME/servers/ohs1/cache/

And you must perform the similar step for the second Oracle HTTP Server instance on WEBHOST2:

WEB_DOMAIN_HOME/servers/ohs2/cache/

Obtaining WebGate Artifacts

The easiest way to obtain the WebGate artifacts is to download them from the OAM console. To download, complete the following steps:

1. Log in to the OAM console with user 'oamadmin' using the following URL:

   http://IADADMINVHN.example.com:7001/oamconsole

2. Click Agents.
3. On the Search screen, click Search.
4. From the list of agents, select Webgate_IDM by clicking on its name.
5. Download the artifacts using the download button. A zip file gets downloaded on the host machine you are using.

Copy the downloaded zip file to the Oracle HTTP Server machine and unzip it to the WEB_CONFIG_DIR/webgate/config location. The files get extracted to the correct locations.

Restarting the Oracle HTTP Server Instance

For information about restarting the Oracle HTTP Server instance, see Restarting Oracle HTTP Server Instances by Using WLST in Administering 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. See Restarting Oracle HTTP Server Instances by Using Fusion Middleware Control in Administering Oracle HTTP Server.

Setting Up the WebLogic Server Authentication Providers

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 you continue with this section.

Note:

You only need to perform these steps in the IAMGovernanceDomain, they will already have been performed in the IAMAccessDomain as part of running configOAM.

• Backing Up Configuration Files
  
• Setting Up the Oracle Access Manager Identity Assertion Provider
  
• Updating the Default Authenticator and Setting the Order of Providers
  

Backing Up Configuration Files

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

Setting Up the Oracle Access Manager Identity Assertion Provider

Set up an Oracle Access Manager identity assertion provider in the Oracle WebLogic Server Administration Console.

To set up the Oracle Access Manager identity assertion provider:

1. Log in to the WebLogic Server Administration Console, if not already logged in.
2. Click Lock & Edit.
3. Click Security Realms in the left navigation bar.
4. Click the myrealm default realm entry.
5. Click the Providers tab.
6. Click New, and select the asserter type OAMIdentityAsserter from the drop-down menu.
7. Name the asserter (for example, OAM ID Asserter) and click OK.
8. Click the newly added asserter to see the configuration screen for the Oracle Access Manager identity assertion provider.
9. Set the control flag to REQUIRED.
10. Under Chosen types, select both the ObSSOCookie and OAM_REMOTE_USER options, if they are not selected by default.
11. Click Save to save the settings.
12. Click Activate Changes to propagate the changes.

Updating the Default Authenticator and Setting the Order of Providers

Set the order of identity assertion and authentication providers in the WebLogic Server Administration console.

To update the default authenticator and set the order of the providers:

1. Log in to the WebLogic Server Administration Console, if not already logged in.
2. Click Lock & Edit.
3. From the left navigation, select Security Realms.
4. Click the myrealm default realm entry.
5. Click the Providers tab.
6. From the table of providers, click the DefaultAuthenticator.
7. Set the Control Flag to SUFFICIENT.
8. Click Save to save the settings.
9. From the navigation breadcrumbs, click Providers to return to the list of providers.
10. Click Reorder.
11. Sort the providers to ensure that the OAM Identity Assertion provider is first and the DefaultAuthenticator provider is last.

    Table 22-2 Sort order

    Sort Order	Provider	Control Flag
    1	OAMIdentityAsserter	REQUIRED
    2	LDAP Authentication Provider	SUFFICIENT
    3	OIMAuthenticationProvider	SUFFICIENT
    4	DefaultIdentityAsserter	N/A
    5	Trust Service Identity Asserter	N/A
    6	DefaultAuthenticator	SUFFICIENT

12. Click OK.
13. Click Activate Changes to propagate the changes.
14. Shut down the Administration Server, Managed Servers, and any system components, as applicable.
15. Restart the Administration Server.
16. If you are going to configure ADF consoles with SSO, you can keep the managed servers down and restart them later. If not, you need to restart managed servers now.

Configuring Oracle ADF and OPSS Security with Oracle Access Manager

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.

The domain-level jps-config.xml file is located in the following location after you create an Oracle Fusion Middleware domain:

ASERVER_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.

To update the OPSS configuration to delegate SSO actions in Oracle Access Manager, complete the following steps:

1. Change to the following directory:
   ORACLE_COMMON_HOME/common/bin
2. Start the WebLogic Server Scripting Tool (WLST):
   ./wlst.sh
3. Connect to the Administration Server, by using the following WLST command:
   connect(‘admin_user’,’admin_password’,’admin_url’)
4. Run the addOAMSSOProvider command, as shown:

   addOAMSSOProvider(loginuri="/${app.context}/adfAuthentication", logouturi="/oam/logout.html")

   The following table defines the expected value for each argument in the addOAMProvider command.

   Note:

   Perform this action for each domain in your configuration.

   Table 22-3 Expected Values for the Argument in the addOAMProvider command

   Argument	Definition
   loginuri	Specifies the URI of the login page Note: For ADF security enabled applications, "/context-root/adfAuthentication" should be provided for the 'loginuri' parameter. For example: /${app.context}/adfAuthentication Note: ${app.context} must be entered as shown. At runtime, the application replaces the variable appropriately. Here is the flow: User accesses a resource that has been protected by authorization policies in OPSS, fox example. If the user is not yet authenticated, ADF redirects the user to the URI configured in loginuri. Access Manager, should have a policy to protect the value in loginuri: for example, "/context-root/adfAuthentication". When ADF redirects to this URI, Access Manager displays a Login Page (depending on the authentication scheme configured in Access Manager for this URI).
   logouturi	Specifies the URI of the logout page. The value of the loginurl is usually /oam/logout.html.
   autologinuri	Specifies the URI of the autologin page. This is an optional parameter.

5. Disconnect from the Administration Server by entering the following command:
   disconnect()
6. Restart the Administration Server and the managed servers.