15.12 Replacing the IAMSuiteAgent with an 11g WebGate

Access Manager and Oracle Identity Manager are among the Oracle Fusion Middleware 11g components. During initial configuration with the WebLogic Server Configuration Wizard, the IAMSuiteAgent is registered with Access Manager 11g along with the IDM domain host identifier and an Application Domain named for the agent.

You can skip this section if you are not replacing the IAMSuiteAgent with an 11g WebGate.

Oracle Fusion Middleware uses Access Manager to protected Oracle Identity Management consoles out of the box using the IAMSuiteAgent. To protect applications beyond containers, you can replace the IAMSuiteAgent with a 11g WebGate (to protect the same set of applications using the same Application Domain and policies as the pre-registered IAMSuiteAgent). The following list is the task overview for this section.

  1. Registering a Replacement 11g WebGate for IAMSuiteAgent

  2. Installing the Replacement 11g WebGate for IAMSuiteAgent

  3. Updating the WebLogic Server Plug-in Configuration

  4. Optional: Confirming the AutoLogin Host Identifier for an OAM / OIG Integration

  5. Optional: Configuring OAM Security Providers for WebLogic

  6. Optional: Disabling IAMSuiteAgent

  7. Configuring Centralized Logout for 11g WebGates

  8. Verifying the Webgate Configuration

15.12.1 Registering a Replacement 11g WebGate for IAMSuiteAgent

You can register a replacement 11g WebGate using the remote registration tool, in-band mode.

For more information about the remote registration tool, processing, and request files, see Registering and Managing OAM 11g Agents

In this example, OAMRequest_short.xml is used as a template to create an agent named 11g4IAM, protecting /.../*, and declaring a public resource, /public/index.html. Your values will be different.

Note:

To use IAM Suite policies with the replacement WebGate, ensure that the WebGate registration is configured to use the IAMSuiteAgent Host Identifier and Preferred Host.

  1. Acquire the Access Manager remote registration tool and set up the script for your environment. For example:

    1. Locate RREG.tar.gz file in the following path:

      $ORACLE_HOME/oam/server/rreg/client/RREG.tar.gz 
      
    2. Untar RREG.tar.gz file to any suitable location. For example: exploded_dir_for_RREG.tar/rreg/input/oamreg.

    3. In the oamreg script, set the following environment variables based on your situation (client side or server side) and information in Table 15-5:

      • OAM_REG_HOME = exploded_dir_for_RREG.tar/rreg
      • JAVA_HOME = Java_location_on_the_computer
  2. Create the registration request and ensure that the autoCreatePolicy parameter is set to false:

    1. Locate OAMRequest_short.xml and copy it to a new file. For example:

      exploded_dir_for_RREG.tar/rreg/input/oamreg/ 
      

      Copy: OAM11gRequest_short.xml

      To: 11g4IAM.xml

    2. Edit 11g4IAM.xml to include details for your environment. For example, if you are changing from the IAMSuiteAgent to an 11g WebGate Agent your request might look like the following:

      <OAM11gRegRequest>
          <serverAddress>http://ruby.uk.example.com:7001</serverAddress>
          <hostIdentifier>11g4IAM</hostIdentifier>
          <agentName>11g4IAM</agentName>
          <autoCreatePolicy>false</autoCreatePolicy>
          <logOutUrls><url>/oamsso/logout.html</url></logOutUrls>
          ...retain defaults for remaining elements...
          ...
          ...
      </OAM11gRegRequest>
      
  3. Register the agent. For example:

    1. Locate the remote registration script.

      • Linux: rreg/bin/oamreg.sh

      Windows: rreg\bin\oamreg.bat

    2. From the directory containing the script, execute the script using inband mode. For example:

      $ ./bin/oamreg.sh inband input/11g4IAM.xml

      Welcome to OAM Remote Registration Tool!
      Parameters passed to the registration tool are:
      Mode: inband
      Filename: ...
      
    3. When prompted, enter the following information using values for your environment:

      Enter your agent username: userame
         Username:  userame
      Enter agent password: ********
      Do you want to enter a WebGate password?(y/n)
          n
      iv.     Do you want to import an URIs file?(y/n)
          n
      
    4. Review the final message to confirm that this was a successful registration:

      Inband registration process completed successfully! Output artifacts are 
      created in the output folder"
      
  4. Log in to the Oracle Access Management Console and review your new registration:

    1. From the System Configuration tab, Access Manager section, open the OAM Agents node and locate your agent registration.

    2. Double-click the agent's name to display the registration page and review the details. For example:

      Note:

      If you install a fresh WebGate, enter matching details during installation.

    3. OAM Proxy Port—From the System Configuration tab, Common Configuration section, double-click Server Instances and locate the port on which the OAM Proxy is running.

  5. Copy the artifacts as follows (or install WebGate with the same specifications, then copy artifacts), as described in "Installing the Replacement 11g WebGate for IAMSuiteAgent".

    Agent & Artifacts Artifacts

    11g WebGate/Access Client

    ObAccessClient.xml and cwallet.sso

    From the AdminServer (Console) host:

    $DOMAIN_HOME/output/$Agent_Name/

    To the Agent host: $11gWG_install_dir/WebGate/config

  6. Proceed to "Updating the WebLogic Server Plug-in Configuration".

15.12.2 Installing the Replacement 11g WebGate for IAMSuiteAgent

After provisioning you must install the 11g WebGate to replace the IAMSuiteAgent.

During the installation, you must provide some of the same information for the WebGate as you did when provisioning it. Following is the task overview.

  1. Install the 11g WebGate as described in Oracle Fusion Middleware Installation Guide for Oracle Identity and Access Management.
  2. Replace IAMSuiteAgent Registration as described in "Updating the WebLogic Server Plug-in Configuration".

15.12.3 Updating the WebLogic Server Plug-in Configuration

After provisioning and installing the 11g WebGate to replace the IAMSuiteAgent, the mod_wl_ohs.conf file requires specific entries to instruct the WebGate Web server to forward requests to the applications on the WebLogic Server.

The generic name of the WebLogic Server plug-in for Apache is mod_weblogic. For Oracle HTTP Server 11g, the name of this plug-in is mod_wl_ohs (the actual binary name is mod_wl_ohs.so). Examples show exact syntax for implementation.

The following example illustrates the areas that must be changed using sample entries. Entries for your environment will be different.

Updates for the 11g Webgate in mod_wl_ohs.conf

<IfModule weblogic_module>
   <Location /oamconsole>
         SetHandler weblogic-handler
         WebLogicHost ruby.uk.example.com
         WebLogicPort    6162
   </Location>
   <Location apmmconsole>
         SetHandler weblogic-handler
         WebLogicHost ruby.uk.example.com
         WebLogicPort    6162
   </Location>
...

</IfModule>

Note:

You need similar Location entries for each of the URIs for all the applications that were earlier accessed directly on the WebLogic Server.

  1. Locate the mod_wl_ohs.conf file in the following path:
    $OHS-INSTANCE_HOME/config/OHS/INSTANCE_NAME/mod_wl_ohs.conf
     
    
  2. Edit the file to include a Location element for each application URI that was previously accessed directly on the WebLogic Server (see the Updates for the 11g Webgate in mod_wl_ohs.conf example).
  3. Save the file.
  4. Restart the Web server.
  5. Proceed to the following task, as needed:

15.12.4 Confirming the AutoLogin Host Identifier for an OAM / OIG Integration

You can confirm (or configure) Oracle Identity Manager (OIM) automatic login functionality when you have Access Manager integrated with OIM.

Skip this step if you do not have Access Manager 11g integrated with Oracle Identity Manager 11g.

The AutoLogin functionality when Oracle Identity Manager is integrated with Access Manager 11g requires the 10g WebGate Web server host name and port in the list of host identifiers for the IAMSuiteAgent.

Note:

If you have a load balancer in front of the 11g WebGate Web server, you must also include the load balancer's host name and port during Step 3.

The agentBaseUrl parameter is used to update a given Host Identifier. However, if automatic policy creation is set to false, the remote registration utility does not create the Application Domain and does not honor the agentBaseUrl parameter.

The following procedure shows how to confirm (or configure) the AutoLogin host identifier for an Access Manager/Oracle Identity Manager integration. Your values will be different. Before you begin, read Updating the WebLogic Server Plug-in Configuration

  1. From the Policy Configuration tab, Host Identifiers node, and select IAMSuiteAgent.
  2. In the Operations panel, confirm that all host name and port combinations are listed for this Host Identifier.
  3. Proceed to "Configuring OAM Security Providers for WebLogic".

15.12.5 Configuring OAM Security Providers for WebLogic

You can configure the WebLogic Security Providers to ensure Single Sign On using Access Manager 11g and the 10g WebGate.

Skip this step if you do not have Access Manager 11g integrated with Oracle Identity Manager 11g.

Refer to following topics for more information on setting up the security providers for the 11g WebGate.

15.12.5.1 About Security Providers in a WebLogic Server Domain

To complete the Access Manager 11g SSO configuration when a 11g WebGate is replacing the IAMSuiteAgent requires configuring the security providers in a WebLogic Server domain.

Following are the security providers:

  • OAM Identity Asserter: Uses token-based authentication and asserts the OAM SSO header and token.

  • OID (or OVD) Authenticator: Creates the Subject and populates it with the correct principals.

    Depending on the store where your users are located, you configure either the Oracle Internet Directory Authenticator or the Oracle Virtual Directory Authenticator as the primary credential authenticator.

  • Default Authenticator: This default WebLogic Authentication provider allows you to manage users and groups in one place: the embedded WebLogic Server LDAP server. This Authenticator is used by the Oracle WebLogic Server to login administrative users:

When you configure multiple Authentication providers, you use the JAAS Control Flag for each provider to control how the Authentication providers are used in the login sequence. You can choose the following the JAAS Control Flag settings, among others:

  • REQUIRED—The Authentication provider is always called, and the user must always pass its authentication test. Regardless of whether authentication succeeds or fails, authentication still continues down the list of providers. The OAM Identity Asserter is required.

  • SUFFICIENT—The user is not required to pass the authentication test of the Authentication provider. If authentication succeeds, no subsequent Authentication providers are executed. If authentication fails, authentication continues down the list of providers. Both the Oracle Internet Directory (or Oracle Virtual Directory) and the Default Authenticator are sufficient.

  • OPTIONAL—When additional Authentication providers are added to an existing security realm, the Control Flag is set to OPTIONAL by default. You might need to change the setting of the Control Flag and the order of providers so that each Authentication provider works properly in the authentication sequence.

    The user is allowed to pass or fail the authentication test of this Authentication provider. However, if all Authentication providers configured in a security realm have the JAAS Control Flag set to OPTIONAL, the user must pass the authentication test of one of the configured providers.

See Also:

Configuring Authentication Providers in Oracle Fusion Middleware Securing Oracle WebLogic Server for a complete list of Authentication providers and details about configuring the Oracle Internet Directory provider to match the LDAP schema for user and group attributes.

Access Manager JAR are WAR files for authentication providers are available when you install an Oracle Fusion Middleware product (Oracle Identity Management, Oracle SOA Suite, or Oracle WebCenter). If you have a Fusion Middleware application, you already have the files you need.

  • oamAuthnProvider.jar: Includes files for both the Access Manager Identity Asserter for single sign-on and the Authenticator for Oracle WebLogic Server 10.3.1+. A custom Access Manager AccessGate is also provided to process requests for Web and non-Web resources (non-HTTP) from users or applications.

  • oamauthenticationprovider.war: Restricts the list of providers that you see in the Oracle WebLogic Server Console to only those needed for use with Access Manager.

    When you deploy the extension, the Administration Console creates an in-memory union of the files and directories in its WAR file with the files and directories in the extension WAR file. Once the extension is deployed, it is a full member of the Administration Console: it is secured by the WebLogic Server security realm, it can navigate to other sections of the Administration Console, and when the extension modifies WebLogic Server resources, it participates in the change control process For more information, see Oracle Fusion Middleware Extending the Administration Console for Oracle WebLogic Server.

15.12.5.2 Setting Up Security Providers for the 11g WebGate

You can set up the security providers using the WebLogic Server Administration Console.

This example illustrates setting up the Oracle Internet Directory provider with the OAM Identity Asserter and Default Authenticator. The steps are the same for OVD, should you need this.

Note:

If you have a Fusion Middleware application, you already have the files you need and you can skip Step 1 of the following procedure. With no Fusion Middleware application, however, you have a stand-alone Oracle WebLogic Server and must obtain the JAR and WAR files from Oracle Technology Network as described in Step 1.

  1. No Oracle Fusion Middleware Application: Obtain the Access Manager provider:

    1. Log in to Oracle Technology Network at:

      https://www.oracle.com/middleware/technologies/identity-management/
      
    2. Locate the oamAuthnProvider ZIP file with WebGates:

      oamAuthnProvider<version number>.zip  
      
    3. Extract and copy oamAuthnProvider.jar to the following path on the computer hosting Oracle WebLogic Server:

      $BEA_HOME/wlserver_10.x/server/lib/mbeantypes/oamAuthnProvider.jar 
      
  2. With Oracle Fusion Middleware Application Installed:

    1. Locate oamauthenticationprovider.war in the following path:

      $ORACLE_HOME/modules/oracle.oamprovider_11.1.2/oamauthenticationprovi
      der.war
      
    2. Copy oamauthenticationprovider.war to the following location:

      $BEA_HOME/wlserver_10.x/server/lib/console-ext/autodeploy/oamauthentication
      provider.war  
      
  3. Log in to the WebLogic Server Administration Console and click Security Realms, Default Realm Name, and click Providers.

  4. OAM Identity Asserter: Perform the following steps to add this provider:

    1. Click Authentication, click New, and then enter a name and select a type:

      Name: OAM ID Asserter

      Type: OAMIdentityAsserter

      OK

    2. In the Authentication Providers table, click the newly added authenticator.

    3. Click the Common tab, set the Control Flag to REQUIRED, and click Save

  5. OID Authenticator: Perform the following steps to add this provider.

    1. Click Security Realms, Default Realm Name, and click Providers

    2. Click New, enter a name, and select a type:

      Name: OID Authenticator

      Type: OracleInternetDirectoryAuthenticator

      OK

    3. In the Authentication Providers table, click the newly added authenticator.

    4. On the Settings page, click the Common tab, set the Control Flag to SUFFICIENT, and then click Save.

    5. Click the Provider Specific tab and specify the following required settings using values for your own environment:

      Host: Your LDAP host. For example: localhost

      Port: Your LDAP host listening port. For example: 6050

      Principal: LDAP administrative user. For example: cn=orcladmin

      Credential: LDAP administrative user password.

      User Base DN: Same searchbase as in Access Manager.

      All Users Filter: For example: (&(uid=*)(objectclass=person))

      User Name Attribute: Set as the default attribute for username in the LDAP directory. For example: uid

      Group Base DN: The group searchbase (same as User Base DN)

      Do not set the All Groups filter as the default works fine as is.

      Save.

  6. Default Authenticator: Perform the following steps to set up the Default Authenticator for use with the Identity Asserter:

    1. Go to Security Realms, Default Realm Name, and click Providers.

    2. Click Authentication, Click DefaultAuthenticator to see its configuration page.

    3. Click the Common tab and set the Control Flag to SUFFICIENT.

    4. Save.

  7. Reorder Providers:

    1. Click Security Realms, Default Realm Name, Providers.

    2. On the Summary page where providers are listed, click the Reorder button

    3. On the Reorder Authentication Providers page, select a provider name and use the arrows beside the list to order the providers as follows:

      OAM Identity Asserter (REQUIRED)

      OID Authenticator (SUFFICIENT)

      Default Authenticator (SUFFICIENT)

    4. Click OK to save your changes

  8. Activate Changes: In the Change Center, click Activate Changes

  9. Reboot Oracle WebLogic Server.

  10. Proceed as follows:

15.12.6 Disabling IAMSuiteAgent

This step is optional, not required. IAMSuiteAgent detects when the WebGate has performed the authentication and then goes silent. However, if the agent must be disabled, then either the WLSAGENT_DISABLED system property or environment variable must be set to true for each one of the servers on which the agent should be disabled. This applies to both AdminServer and OAM Servers.

You can disable the agent in one of two ways:

  • Either set the WLSAGENT_DISABLED environment variable to true

  • Or pass WLSAGENT_DISABLED as a System Property

Before you begin: Configuring OAM Security Providers for WebLogic, if needed.

  1. On the computer hosting the IAMSuiteAgent, perform one the following tasks:
    • Either set the WLSAGENT_DISABLED environment variable to true:

      setenv WLSAGENT_DISABLED true
      
    • Or or pass DWLSAGENT_DISABLED=true as a System Property:

      -DWLSAGENT_DISABLED=true
      
  2. Restart the Web server.
  3. Proceed with "Configuring Centralized Logout for 11g WebGates", then return to "Verifying the Webgate Configuration".

15.12.7 Verifying the Webgate Configuration

Oracle recommends testing your environment using the 11g WebGate to ensure that all applications that were previously protected by the IAMSuiteAgent are now protected after configuration.