IDCS EBS Asserter Cheat Sheet

Introduction

I worked with a number of customers to resolve issues with their E-Business Suite single sign-on setup using the IDCS asserter solution and saw a pattern in the misconfigurations causing these similar types of issues.

In this blog, I want to share the basic EBS asserter flows to understand the runtime better and the commonly faced issues along with their resolutions. 

I hope this post will save you a lot of time and effort should you have any of these issues or will serve as a first-time guide to get this integration working.

The starting point for anyone trying to set up EBS SSO using the asserter can be found here - https://www.oracle.com/webfolder/technetwork/tutorials/obe/cloud/idcs/ebs_asserter_obe/ebs-asserter.html

Most customers are comfortable configuring the asserter and making the login/logout flows work as per the document, but when it comes to troubleshooting, a deeper understanding of the asserter flows helps. 

So, here are the 2 important flows :

Login flow

As you can see in the above figure, the EBS asserter makes a backend call to IDCS service and also to EBS DB to establish EBS session. So, make sure the asserter host can reach IDCS and EBS DB.

Logout Flow

This is a fairly simple flow. At the end of the logout flow, a user should land on the configured post logout URL.

Important Steps During Setup 

Datasource connection

At setup time many customers may struggle a bit with the datasource configuration step.

Apart from the usual database connection parameters such as host, port and SID/Service name, following are the important things to verify when creating a datasource used by the asserter to connect to EBS DB

The driver class - If you use a non-XA datasource, type oracle.apps.fnd.ext.jdbc.datasource.AppsDataSource    If you are using an XA data source, type oracle.apps.fnd.ext.jdbc.datasource.AppsXADataSource  and make sure that the driver jar file is copied to <your_domain>/lib and the admin server has been restarted.

The user - EBS user with UMX|APPS_SCHEMA_CONNECT Role. For security reasons, do not use "APPS" DB user, this user has the highest privileges not required by the asserter. 

DBC file -  A customer reported getting a NullPointerException when creating the data source. The issue turned out to be a missing DBC file on the asserter machine because the DBC file was created on the EBS system but was never copied over to the asserter machine.

Asserter Bridge.properties

The document does a good job of explaining all the parameters configured. 

Pay extra attention to -   

whitelist.urls  - Lists the URL E-Business Suite Asserter can accept as the requestUrl  parameter value. 

when a login session is initiated from a different page than the EBS home page, the asserter gets "requestUrl" parameter in the request and knows where to redirect upon successful authentication. The asserter keeps a list of the allowed URLs. If the white list does not contain the incoming "requestURL", the asserter will redirect the user to the configured homepage.

post.logout.url - Mention the URL where a user should be redirected to upon EBS app logout. This must match the post redirect URL configured in IDCS for the asserter application.

Context root and cookie path

Customers may need to deploy the asserter WAR file multiple times on the same Weblogic server with different context roots ( e.g. devsso, testsso etc.) or a single WAR, but with a different context root than the default one. 

Make sure to match the cookie path with the new context root in Weblogic.xml before you deploy the asserter.

<weblogic-web-app>
  <container-descriptor>
  <prefer-web-inf-classes>true</prefer-web-inf-classes>
      </container-descriptor>
      <session-descriptor>
          <cookie-name>ASSERTERSESSIONID</cookie-name>
           <cookie-path>/ebs</cookie-path>
      </session-descriptor>
 </weblogic-web-app>

Common issues

1) The number one issue reported by the customers is with the WebADI templates. WebADI ( Web Applications Desktop Integrator ) provides the use of Microsoft Office applications such as Excel, Word, and Project to upload data to Oracle E-Business Suite. It initiates the login flow in an embedded browser. The authentication flow goes through as expected but the users don’t land on the expected page. So, when WebADI users click on the "upload document” button, they are taken to the EBS homepage rather than to the "user responsibilities" selection page.

This happens when the asserter whitelist URLs are not configured correctly, either the WebADI specific URLs (like "/OA_HTML/BneApplicationService") are missing or there is a typo in the configuration. Another reason could be that an older version of the asserter is being used. 

Make sure you download the latest asserter from your IDCS tenancy and verify the whitelist URLs configured in bridge.properties.

2) User does not land on the expected URL post logout

The user clicks on “logout” button in EBS application and lands on the IDCS login page instead of the one configured as a “post.logout.url” in the asserter configuration.  

The issue is that the asserter does not find the session cookie, but initiates IDCS logout anyway, without the necessary request data. IDCS session logout happens and the user is taken to the IDCS global session logout URL instead of the asserter application-specific post logout URL.

Verify the asserter cookie path configured in "weblogic.xml" file within the asserter WAR.

The cookie path must match the context root used for the asserter deployment.  For example, if you used “/dev/asserter” as the context root, make sure the cookie path is set to “/dev/asserter” too.

Summary

Verify the asserter version and configurations mentioned in the tutorial and in this blog and your EBS SSO setup should be a cakewalk.