Introduction

Oracle AccessGate (OAG) lies at the heart of the EBS SSO experience, along with Okta Access Gateway. Unlike the older Oracle Access Manager AccessGate, the EBS AccessGate uses the header variables sent from the SSO system (ie: Okta Access Gateway) to create a native user-session for the target EBS, like any other SSO-enabled web application.

The OAG application requires the Oracle Internet Directory (OID) as its user repository to enable SSO. This is due to the fact that E-Business Suite needs to be registered with OID for Single Sign On. Additionally, E-Business Suite uses orclguid in OID to map the Single Sign On user with the corresponding local user profile. During authentication, EBS AccessGate expects the SSO system to return orclguid and EBS username (stored as a user-attribute in SSO user store) in two header variables, USER_ORCLGUID and USER_NAME respectively.

Due to the unique nature of this integration, we can not use the auto deployment script that comes with EBS server. This is due to the fact that most of the EBS SSO integrations we configure host the EBS application in a different environment than the Access Gateway and AccessGate. Therefore, the auto deployment script can not handle this type of topology. We want to have full control of where we deploy it, how we deploy it, and what domain we host the AccessGate as there are integration platforms that might require CrossDomain SSO functionality as well.

In this white paper, we will demonstrate how to deploy the Oracle AccessGate.

OAG Deployment

The OAG deployment consists of 3 main processes.

  1. Prepare pre-requisite items.

  2. Deploy OAG

  3. Validate OAG Deployment

Pre-requisites before Deployment

OAG can be deployed on any Weblogic Server 10.3.6. In most cases, we will create a WLS Managed Server within the OID/DIP infrastructure and deploy the OAG application on the Managed Server.

A EBS generated dbc file is required for the deployment of OAG.

Make sure an EBS service ID is created (ie: "MYEBSUSER" or "ASADMIN"). This ID must have UMX|APPS_SCHEMA_CONNECT access.

Make sure to download the OAG jar file from Oracle eDelivery site (Patch P18131618 EBS AccessGate 1.2.3).

Command to generate the EBS DBC file:

source apps-vis.env

java oracle.apps.fnd.security.AdminDesktop apps/apps CREATE NODE_NAME=oid1.gateway.info DBC=/home/ebs121/applmgr/inst/apps/VIS_ebs121-demo/appl/fnd/12.0.0/secure/VIS.dbc

cat VIS_OID1.ICSYNERGY.INFO.dbc
#Desktop DB Settings
#Wed Dec 20 18:09:40 CST 2017
FNDNAM=APPS
APPL_SERVER_ID=60CF841E58F639BBE050A8C0660A740A42113618361790919377415661991414
APPS_JDBC_URL=jdbc\:oracle\:thin\:@(DESCRIPTION\=(ADDRESS_LIST\=(LOAD_BALANCE\=YES)(FAILOVER\=YES)(ADDRESS\=(PROTOCOL\=tcp)(HOST\=ebs121-demo.gateway.info)(PORT\=1521)))(CONNECT_DATA\=(SERVICE_NAME\=VIS)))
GWYUID=APPLSYSPUB/PUB

Validate the dbc file via FirstExample.java. It is a helloworld type of program which uses the dbc file and makes a database connection to the EBS tables, just as the AccessGate would.

Please change the necessary database connection string to suite specific environment.

Make sure ojdbc6.jar and AccessGate fndext.jar are available in the classpath. You can copy ojdbc6.jar jar file from the Weblogic server environment.

Run the java command below to test the dbc file

// The code is on /home/oracle/tmp on ofr1-demo.gateway.info
// To compile this program, do the following:
// /u01/vsun-sofware/JDK-17u80/jdk1.7.0_80/bin/javac -cp ./fndext.jar:./ojdbc6.jar:$CLASSPATH FirstExample.java

// To run this program, do the following:
// /u01/vsun-sofware/JDK-17u80/jdk1.7.0_80/bin/java -cp ./fndext.jar:./ojdbc6.jar:$CLASSPATH FirstExample

// You need 3 things to run this:
// 1. fndext.jar and ojdbc6.jar file
// 2. the EBS DBC file
// 3. jdbc id/pw


//STEP 1. Import required packages
import java.io.File;
import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.ResultSetMetaData;
import java.sql.SQLException;
import java.sql.Statement;
import oracle.apps.fnd.ext.jdbc.datasource.AppsDataSource;

public class FirstExample {
   // JDBC driver name and database URL
   static final String JDBC_DRIVER = "oracle.apps.fnd.ext.jdbc.datasource.AppsDataSource";
   static final String DB_URL = "jdbc:oracle:thin:@ebs121-demo.gateway.info:1521:VIS";

   public static void main(String[] args) {

   AppsDataSource ads = null;
   Connection conn = null;
   Statement stmt = null;
   String expr = "select user_name from fnd_user where user_id like '1013482'";
   ResultSet rs = null;
   try {
        ads = new AppsDataSource();
        ads.setDescription("Apps Demo");
        ads.setUser("ASADMIN");
        ads.setPassword("b-B3ZB58");
        ads.setDbcFile ("/home/oracle/tmp/1.dbc");
        conn = ads.getConnection();
        stmt = conn.createStatement (ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.CONCUR_READ_ONLY);
        rs = stmt.executeQuery ( expr );
        ResultSetMetaData rsmd = rs.getMetaData();
        int columnsNumber = rsmd.getColumnCount();
        while (rs.next()) {
       for (int i = 1; i <= columnsNumber; i++) {
           if (i > 1) System.out.print(",  ");
           String columnValue = rs.getString(i);
           System.out.print(columnValue + " " + rsmd.getColumnName(i));
       }
       System.out.println("");
   }
    }
    catch (Exception e)
    {
        e.printStackTrace();
    }

   System.out.println("Goodbye!");
}
}

Deploy Oracle Access Gate

Create JDBC DataSource

  1. Log in to the WebLogic Console.

  2. Navigate to Domain Structure → Services → Data Sources.

  3. Click the New button for Datasource and select Generic Data Source.

    Oracle OAG Deployment

  4. Enter values for:

    1. Name of the DataSource

    2. JNDI Name

    3. DataSource Type: Oracle

    4. DataBase Driver: "Oracle’s Drive (Thin) for Instance connections; Version: 9.0.1.9.2.0.10,11"

      Oracle OAG Deployment

  5. Click Next.

  6. For a non-XA data source, uncheck the Supports Global Transactions checkbox.

    Oracle OAG Deployment

  7. Enter Values for:

    1. DataBase Name: (SID of Oracle EBS DB)

    2. Hostname (DB hostname)

    3. Port (DB Port)

    4. DB username (ie: ASADMIN)

    5. Password for DB username

  8. Confirm Password and click Next.

    Oracle OAG Deployment

  9. Enter Driver Class Name: oracle.apps.fnd.ext.jdbc.datasource.AppsDataSource and JDBC URL (ie: jdbc:oracle:thin:@ebs121-demo.gateway.info:1521:VIS)

    Oracle OAG Deployment

  10. In the Properties field, add a new property after the user property: dbcFile= <file path>.

  11. Click Test Connection. You will get a message indicating a successful connection to the EBS DB.

  12. Click Next after a successful test. Check the checkbox for the appropriate target server, and cick Finish.

Deploy OAG

  1. Log in to WLS console.

  2. Click Deployment → Install.

  3. Enter the path to the AccessGate war file, and click Next.

    Oracle OAG Deployment

  4. Select Install this deployment as application, and click Next.

    Oracle OAG Deployment

  5. Select the AccessGate Managed Server eag_server1.

    Oracle OAG Deployment

  6. Name the deployment accordingly with the EBS instance (ie: ebsauth_ebs121demo).

    Oracle OAG Deployment

    Oracle OAG Deployment

  7. Update the context root for the AccessGate to be more specific to our environment (ie: ebsauth-ebs121demo).

    This context root is the application context where the Access Gateway will protected. Oracle OAG Deployment

    Oracle OAG Deployment

  8. Click Save.

    An environment specific Plan.xml is created by the deployment. (ie: /home/oracle/accessgate/p18131618_R12_GENERIC/Plan.xml
    Oracle OAG Deployment

  9. Update Plan.xml with the EBS SSO related information. See Oracle Doc 1077460.1 for more information.

    For details on Update the Plan.xml, see Oracle Doc 1077460.1 Section 5: Set Oracle E-Business Suite AccessGate configuration parameters mentioned above. Sample Plan.xml from the Okta Lab OAG

    <?xml version='1.0' encoding='UTF-8'?>
    <deployment-plan xmlns="http://xmlns.oracle.com/weblogic/deployment-plan" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.oracle.com/weblogic/deployment-plan http://xmlns.oracle.com/weblogic/deployment-plan/1.0/deployment-plan.xsd">
      <application-name>ebsauth_ebs121demo</application-name>
    <variable-definition>
        <variable>
          <name>app_SSO_SERVER_TYPE</name>
          <value>OAM</value>
        </variable>
        <variable>
          <name>app_CONNECTION_REF</name>
          <value>jdbc/JDBC AppsDataSource-1</value>
        </variable>
        <variable>
          <name>app_APPL_SERVER_ID</name>
          <value>4F99CAA182A37162E050A8C0660A4DB533095795391574515454246815672712</value>
        </variable>
        <variable>
          <name>app_LOG_CONFIG_FILE</name>
          <value>default</value>
        </variable>
        <variable>
          <name>app_SSO_SERVER_RELEASE</name>
          <value>10</value>
        </variable>
        <variable>
          <name>app_SSO_SERVER_URL</name>
          <value>https://ebs121demosso.gateway.info/sso</value>
        </variable>
        <variable>
          <name>app_WEBGATE_LOGOUT</name>
          <value>https://ebs121demosso.gateway.info/spgwLogout</value>
        </variable>
        <variable>
            <name>app_LOG_CONFIG_FILE</name>
            <value>/home/oracle/logging.properties</value>
        </variable>
      </variable-definition>
      <module-override>
        <module-name>fndauth.war</module-name>
        <module-type>war</module-type>
        <module-descriptor external="true">
          <root-element>weblogic-web-app</root-element>
          <uri>WEB-INF/weblogic.xml</uri>
          <hash-code>1495656967991</hash-code>
        </module-descriptor>
        <module-descriptor external="false">
          <root-element>web-app</root-element>
          <uri>WEB-INF/web.xml</uri>
    <variable-assignment>
          <name>app_SSO_SERVER_TYPE</name>
          <xpath>/web-app/context-param/[param-name="SSO_SERVER_TYPE"]/param-value</xpath>
          <operation>replace</operation>
        </variable-assignment>
        <variable-assignment>
          <name>app_CONNECTION_REF</name>
          <xpath>/web-app/context-param/[param-name="CONNECTION_REF"]/param-value</xpath>
          <operation>replace</operation>
        </variable-assignment>
        <variable-assignment>
          <name>app_APPL_SERVER_ID</name>
          <xpath>/web-app/context-param/[param-name="APPL_SERVER_ID"]/param-value</xpath>
          <operation>replace</operation>
        </variable-assignment>
        <variable-assignment>
          <name>app_LOG_CONFIG_FILE</name>
          <xpath>/web-app/context-param/[param-name="LOG_CONFIG_FILE"]/param-value</xpath>
          <operation>replace</operation>
        </variable-assignment>
        <variable-assignment>
          <name>app_SSO_SERVER_RELEASE</name>
          <xpath>/web-app/context-param/[param-name="SSO_SERVER_RELEASE"]/param-value</xpath>
          <operation>replace</operation>
        </variable-assignment>
        <variable-assignment>
          <name>app_SSO_SERVER_URL</name>
          <xpath>/web-app/context-param/[param-name="SSO_SERVER_URL"]/param-value</xpath>
          <operation>replace</operation>
        </variable-assignment>
        <variable-assignment>
          <name>app_WEBGATE_LOGOUT</name>
          <xpath>/web-app/context-param/[param-name="WEBGATE_LOGOUT"]/param-value</xpath>
          <operation>replace</operation>
        </variable-assignment>
        </module-descriptor>
        <module-descriptor external="true">
          <root-element>wldf-resource</root-element>
          <uri>META-INF/weblogic-diagnostics.xml</uri>
        </module-descriptor>
      </module-override>
      <config-root>/home/oracle/accessgate/p18131618_R12_GENERIC/plan</config-root>
    </deployment-plan>
    
  10. Redeploy the OAG application. Select Deployment → Update.

    Oracle OAG Deployment

  11. Select Redeploy this application, and click Next.

    Oracle OAG Deployment

  12. Confirm the deployment war file name and path, and click Finish.

    Oracle OAG Deployment

  13. Click Control → Start, and select Servicing all requests.

    Oracle OAG Deployment

  14. Click Activate Changes to complete this deployment.

  15. Restart OAG Managed Server: eag_server1.

Validate OAG Deployment

Once the OAG is successfully deployed, perform a unit test before we attach the Access Gateway to this integration.

Install Firefox Modified Header Add-On for this testing exercise.

Make sure we have a test user that exists in EBS, OUD, IDP

  1. Enable the Firefox Modified Header AddOn.

  2. Add the 2 headers as shown below: USER_NAME, USER_ORCLGUID.

    Oracle OAG Deployment

  3. You can validate the GUID in OID via the ODSM console.

    Oracle OAG Deployment

  4. Use Firefox and access the OAG url (ie: http://oid1.gateway.info:7010/ebsauth_ebs121demo).

  5. Verify that the user can successfully SSO into EBS and land at the EBS home page.