Sunday, December 7, 2025

Oracle Asserter IDCS setup and integration with Oracle EBS 12.2 for SSO

Introduction

The Oracle E-Business Suite (EBS) Asserter is a lightweight Java application that enables single sign-on (SSO) authentication and password management for Oracle EBS using Oracle Identity Cloud Service (IDCS). It acts as a bridge between EBS and IDCS, deployed on Oracle WebLogic Server. This guide provides a step-by-step process for setup and integration with EBS Release 12.2, based on official Oracle documentation. Ensure you have administrative access to EBS, IDCS, and WebLogic environments.

Prerequisites

Before starting, verify the following:

  • Software Versions:
    • Oracle EBS 12.2.4 or later (with latest patches applied).
    • Oracle WebLogic Server 12c (12.2.x) Standard Edition (not Enterprise Edition).
    • Java JDK/JRE 8 or later, with Java Cryptography Extension (JCE) installed.
    • EBS Asserter version 19.1.4-1.2.2 or later (download from IDCS console: Settings > Downloads > Identity Cloud Service E-Business Suite Asserter).
  • Environment Setup:
    • EBS and Asserter hosts must be in the same domain (e.g., example.com).
    • Use HTTPS for all communications (IDCS requires SSL/TLS).
    • Synchronize clocks between EBS, Asserter, and IDCS servers.
    • EBS must not have prior SSO integrations (e.g., Oracle Access Manager or Internet Directory); remove them and restart servers.
    • Note key details: EBS hostname/URL, Asserter WebLogic hostname/URL (e.g., https://asserter.example.com:7002), IDCS base URL (e.g., https://idcs-tenant.identity.oraclecloud.com), EBS database details (host, port, SID), and APPS user password.
  • Access Rights:
    • IDCS: Admin rights to create users/applications.
    • EBS: Sysadmin access.
    • WebLogic: Admin console access.
  • Downloads:
    • Extract the Asserter ZIP to a working directory (e.g., /opt/ebssdk on both EBS and Asserter servers).
    • Key files: ebs.war, idcs-wallet-<version>.jar, and fndext.jar (from ebs.war/WEB-INF/lib).

For multiple EBS instances, deploy one Asserter per instance (or multiple on the same server starting from Asserter 19.2.1-1.5.0 by renaming WAR files).

Step 1: Create an Application User in EBS for the Asserter

  1. Log in to EBS as an administrator (e.g., SYSADMIN).
  2. Navigate to User Management > Users.
  3. From the Register dropdown, select User Account and click Go.
  4. In Create User Account:
    • User Name: Enter a unique name (e.g., EBSSERVICEUSER).
    • Password: Set a strong password.
    • Description: "EBS Asserter Service User".
    • Password Expiration: None.
    • Click Submit.
  5. Click Assign Roles > Assign Roles.
  6. Search for role code UMX|APPS_SCHEMA_CONNECT, select Apps Schema Connect Role, and assign it with justification ("EBS Asserter Service User"). Click Save.
  7. Log out and log back in with the new user to reset the password (ignore Workflow warnings).

This user connects the Asserter to the EBS database.

Step 2: Create and Configure the SYSADMIN User in IDCS

  1. Sign in to the IDCS console.
  2. Go to Users > Add.
  3. In Add User:
    • First Name: EBS.
    • Last Name: Sysadmin.
    • Uncheck Use the email address as the user name.
    • User Name: sysadmin.
    • Email: Use the email from the EBS SYSADMIN account (update EBS if needed—see Step 3).
    • Click Finish.

Step 3: Update SYSADMIN Email in EBS to Match IDCS

  1. Log in to EBS as SYSADMIN.
  2. Go to User Management > Users, search for SYSADMIN, and click the update icon.
  3. Update the Email field to match the IDCS email.
  4. Click Apply and close EBS.

Step 4: Register the Asserter Server with EBS

  1. On the EBS application server, run echo $JAVA_HOME and echo $WL_HOME (note values for EBS 12.2+).
  2. Create /opt/ebssdk and copy fndext.jar from ebs.war/WEB-INF/lib to it (and to Asserter's $DOMAIN_HOME/lib).
  3. Source the EBS environment: source $APPL_TOP/APPS<CONTEXT_NAME>_env (e.g., EBSapps.env).
  4. Locate the .dbc file in $FND_SECURE (e.g., VISION.dbc).
  5. Run: cd /opt/ebssdk; java oracle.apps.fnd.security.AdminDesktop apps/<APPS_PASSWORD> 0 Y CREATE_NODE NODE_NAME=<asserter_hostname> DBC=<full_path_to_dbc>.
    • Replace <asserter_hostname> with the Asserter WebLogic hostname.
  6. Verify: cat <SID>_<hostname>.dbc and note the APPL_SERVER_ID value.
  7. Copy the new .dbc file to /opt/ebssdk on the Asserter server.

Step 5: Register a Confidential Application in IDCS for the Asserter

  1. In IDCS, go to Applications > Add > Confidential Application.
  2. Details tab:
    • Name: EBS Asserter.
    • Description: EBS Asserter Application.
    • Application URL: /ebs.
    • Check Display in My Apps.
    • Click Next.
  3. Client tab:
    • Select Configure this application as a client now.
    • Allowed Grant Types: Client Credentials, Authorization Code.
    • Allowed Scopes: Check all.
    • Redirect URI: https://<asserter_host>:<port>/ebs/response.
    • Logout URI: https://<asserter_host>:<port>/ebs/logout.
    • Post Logout Redirect URI: https://<asserter_host>:<port>/ebs.
    • Click Next.
  4. Resources tab:
    • Under Grant the client access to Identity Cloud Service Admin APIs, add Authenticator Client and Me scopes.
    • Click Next > Finish.
  5. Note the Client ID and Client Secret, then Activate the application.

Step 6: Create a Wallet File for IDCS Credentials

  1. On the Asserter server, cd /opt/ebssdk.
  2. Run: java -jar idcs-wallet-<version>.jar.
  3. Enter:
    • Wallet Path: Full path (e.g., /opt/ebssdk/cwallet.sso).
    • Client ID: From Step 5.
    • Client Secret: From Step 5.
    • IDCS Base URL: e.g., https://idcs-tenant.identity.oraclecloud.com.
  4. This generates cwallet.sso.

Step 7: Configure the Asserter Properties (bridge.properties)

  1. Unzip ebs.war to a temp directory.
  2. Edit WEB-INF/bridge.properties (uncomment and set):
    text
    app.url=https://<asserter_host>:<port>/ebs
app.serverid=<APPL_SERVER_ID from Step 4>
ebs.url.homepage=https://<ebs_host>:<port>/OA_HTML/OA.jsp?OAFunc=OANEWHOMEPAGE
ebs.ds.name=visionDS  # Example; match your datasource name
ebs.user.identifier=username  # Or 'email' based on EBS user field
idcs.iss.url=https://identity.oraclecloud.com
wallet.path=/opt/ebssdk/cwallet.sso
whitelist.urls=https://<ebs_host>:<port>/OA_HTML/RF.jsp?,https://<ebs_host>:<port>/OA_HTML/OA.jsp?,https://<ebs_host>:<port>/OA_HTML/BneApplicationService
ebs.renew.session=true  # Optional: Renews EBS session on each request
post.logout.url=/ebs  # Optional: Must match IDCS post-logout URI
    • For proxy mode (switch user): Set proxy.mode=true and proxy.home.url=<EBS switch user URL>.
    • Ensure idcs.user.identifier matches ebs.user.identifier for user mapping.
  3. Re-zip the directory to recreate ebs.war.

Step 8: Configure WebLogic Server

  1. Access WebLogic Console (e.g., https://<asserter_host>:<admin_port>/console).
  2. Disable Hostname Verification (for SSL):
    • Lock & Edit > Environment > Servers > [Server Name] > SSL > Advanced.
    • Set Hostname Verification to None.
    • Activate Changes and restart the server.
  3. Handle IDCS Certificates (if needed for trust):
    • Use default Java trust store; avoid custom imports.
    • For renewals: Remove old certs with keytool commands on $WL_HOME/server/lib/DemoTrust.jks and $JAVA_HOME/jre/lib/security/cacerts (default password: changeit), then restart.

Step 9: Define Data Source and Deploy the Asserter

  1. Create Data Source:
    • In WebLogic Console: Services > Data Sources > New > Generic Data Source.
    • Name/JNDI: visionDS (match ebs.ds.name).
    • Database Type: Oracle.
    • Driver: Oracle's Driver (Thin) Versions: 12.x or later (non-XA) or Thin XA for XA.
    • Connection: Database Name (SID), Host, Port (e.g., 1521), User/Password (from Step 1).
    • Driver Class Name: oracle.apps.fnd.ext.jdbc.datasource.AppsDataSource (non-XA) or AppsXADataSource (XA).
    • Properties: dbcFile=/opt/ebssdk/<SID>_<hostname>.dbc.
    • Test Configuration, target EBSAsserter_server (create if needed), Finish > Activate Changes.
  2. Deploy:
    • Copy updated ebs.war to /opt/ebssdk.
    • Deployments > Install, select ebs.war, install as application, target the managed server, Activate Changes.
    • Start the server if stopped.

Step 10: Update EBS Profiles for SSO

  1. Log in to EBS as SYSADMIN.
  2. Go to System Administrator > Profiles > System.
  3. Update:
    • APPS_AUTH_AGENT: Site level = Asserter URL (e.g., https://asserter.example.com:7002/ebs).
    • APPS_SSO: Site level = SSWA w/ SSO.
    • APPS Session: Site level = DOMAIN (from HOST).
  4. Sign-off and restart EBS application servers.

Step 11: Test the Integration

  1. In IDCS, create a test user with username matching an EBS user; assign the EBS Asserter app.
  2. Access the Asserter URL (e.g., https://asserter.example.com:7002/ebs) → Redirects to IDCS login.
  3. Log in with IDCS credentials → Redirects to EBS homepage.
  4. Test logout: Should redirect to IDCS logout and back to Asserter.
  5. Verify password changes in IDCS sync to EBS.
  6. For issues: Check WebLogic logs ($DOMAIN_HOME/servers/<server>/logs), enable diagnostics in bridge.properties (log.level=DEBUG), or review IDCS audit logs.

Additional Considerations

  • Monitoring: Use WebLogic Console for deployment status; enable Asserter metrics via properties.
  • Mobile Apps: For EBS mobile, configure additional IDCS apps (see Oracle docs).
  • Troubleshooting: Common issues include mismatched user identifiers, network ports, or certificate trust. Collect diagnostics by setting log.level=TRACE and reviewing asserter.log.
  • High Availability: Deploy multiple Asserters behind a load balancer.

For the latest patches or variations, refer to Oracle Support. If using Docker for deployment, additional steps apply (e.g., build WebLogic image). 

Posted by SamiMalik at Sunday, December 07, 2025
Labels: ,