1. Enterprise Deployment Guide for Oracle Identity and Access Management in a Kubernetes Cluster
  2. Common Configuration and Management Procedures for an Enterprise Deployment
  3. Configuring Single Sign-On for an Enterprise Deployment

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

This chapter includes the following topics:

Parent topic: Common Configuration and Management Procedures for an Enterprise Deployment

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.

Parent topic: Configuring Single Sign-On for an Enterprise Deployment

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.

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.

Parent topic: Configuring Single Sign-On for an Enterprise Deployment

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.

Parent topic: Configuring Single Sign-On for an Enterprise Deployment

Enabling OAM Rest OAP Calls and Health Check

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/ohsDomain/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. To enable a health check, add the following lines:

    Note:

    This step is applicable if you have created a health check described in Creating a Health Check. 
    
<LocationMatch "/health-check.html">
    require host webtier.com
    request ip IP ADDRESS OF LOADBALANCER
</LocationMatch>

    Note:

    In above mentioned example webtier.com, a require host is used to restrict access to a particular subnet where your load balancer resides. Alternatively, you can use the clause request IP address of the load balancer to specify the address of the load balancer. This is the IP address of the load balancer and not the floating IP address assigned to the load balancer. This ensures that the OHS returns only health check tests to the load balancer.

    If your load balancer indicates that the webserver is down, then you must check the OHS access log to confirm the cause of the rejected requests which can occur if you are not restricting it to the right IP address of domain.

    You must not set your request host to your internet domain to avoid exposing your health check outside of the organisation.

  3. Save the file.

Parent topic: Configuring Single Sign-On for an Enterprise Deployment

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.

Parent topic: Configuring Single Sign-On for an Enterprise Deployment

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

Parent topic: Adding a Load Balancer Certificate to WebGate

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.

Parent topic: Adding a Load Balancer Certificate to WebGate

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.

Parent topic: Configuring Single Sign-On for an Enterprise Deployment

Copying Generated Artifacts to the Oracle HTTP Server WebGate Instance Location

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 28-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 the user name oamadmin by using the following URL:
    http://iadadmin.example.com/oamconsole
  2. Click Agents.
  3. On the Search screen, click Search.
  4. From the list of agents, select Webgate_IDM.
  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.

Parent topic: Copying WebGates Artifacts to Web Tier

Backing Up the Configuration Files

You should first back up the relevant configuration files to ensure their safety.

Back up the following configuration files:

DOMAIN_HOME/config/config.xml
DOMAIN_HOME/config/fmwconfig/jps-config.xml
DOMAIN_HOME/config/fmwconfig/system-jazn-data.xml

Also back up the boot.properties file for the Administration Server: 

DOMAIN_HOME/servers/AdminServer/security/boot.properties

Parent topic: Configuring Single Sign-On for an Enterprise Deployment