Best Practices from Oracle Development's A‑Team

Using IDCS Appgate to secure Oracle BI Discoverer on OCI

Muhammad Abdel-Halim
Principal Cloud Technology Architect


In this blog I want to discuss about an interesting usecase that showcases how IDCS Appgate can be used to enable SSO security for legacy applications when migrating to the cloud. Many customers who are looking to migrate their workloads into the cloud find that they have legacy systems in their portfolio that are not necessarily amenable to modernisation.

An example of one of these legacy systems is Oracle Discoverer. Oracle BI Discoverer is a business intelligence tool for analyzing data and is a key component of Oracle Fusion Middleware. Discoverer provides an integrated business intelligence solution that comprises intuitive ad-hoc query, reporting, analysis, and Web-publishing functionality. Some EBS customers will also have Oracle BI Discoverer in the mix; and if they’re looking to migrate to the cloud they will face the challenge of how to bring these applications together under an IDCS-based SSO umbrella.

User experience in Discoverer

Most probably if the customer is migrating EBS to OCI, then the chances are that they will be using Oracle EBS Asserter. A bit of an explanation about EBS Asserter. EBS asserter is an Oracle product that allows OOB integrate with IDCS SSO. It’s a weblogic gateway that intercepts inbound requests and authenticates them with IDCS using Openidc and then creates and maps a session in EBS using API calls.

How Discoverer security works in On-Prem

Now. How does Discoverer fit into this new landscape in the cloud? It might be a good idea to understand how Discovere does SSO security on-prem to understand how we can translate that setup into the cloud. In the on premise setup Discoverer offers two options:

  • Local Authentication: logs the user in directly using u/p credentials, or

  • Use SSO.

Local Authentication

When logging in the user directly, Discoverer prsents a login screen to the user and then matches the username and password against the <<EBS.USER>> table in EBS. If a user record is found with matching username and password then the user is authenticated and logged in.

Below is the a screen shot showing the Discoverer viewer landing page. User is prompted for both username and password since there is no SSO.


In the SSO case, an apache MOD_OSSO security gateway running in apache is used to intercept the incoming requests and redirect to Oracle Access Manager for user authentication, after which user GUID is fetched back from Oracle Unified Directory (OUD). MOD_OSSO then forwards the GUID header to Discoverer. The Discoverer application (which is nothing but a servlet running in a weblogic server) will intercept the inbound request and extract the GUID header and create a session and then present a login screen (yes a login screen!) to the user which has to then type in their username (no need for password: remember the user is authenticated and MOD-OSSO WOULDN’T have passed a GUID header onto Discoverer if the user hadn’t been already authenticated). After the user enters the username in the Login screen, Discoverer will then match the GUID AND the username against the records in the <<EBS.USER>> table. All users in OAM will be pre-provisioned in EBS user table along with their GUIDs. If Discoverer matches the username and GUID against a record in the database then user will be logged in and a Discoverer session created.

Below is the a screen shot showing the Discoverer viewer landing page post SSO. Notice that there is no prompt for the user password.

How Discoverer security can work in OCI?

Now let’s see how in the light of the mechanism above we can translate this into OCI. Note that in OCI we’re using IDCS, which is Oracle's cloud-native Identity Management Service designed to be an integral part of the enterprise security fabric. We're not using OAM and so we've broken the integration between EBS and OAM that was used for EBS SSO in the on-prem scenario. EBS is now using EBS asserter instead. Since EBS is using the EBS asserter, the table for the instance running in OCI will not have the GUID column populated. But the Discoverer SSO mechanism discussed above relies on a GUID value match. Discoverer assumes that there is OAM integration, and this assumption/mechanism is unfortunately ‘hard baked’ into the Discoverer binary and cannot be changed (remember I said 'not amenable to modernisation'?).

Local Authentication

So we still can leverage the username/password mechanism described above and login directly into Discoverer using the username/password credentials which get verified against the values in the <<EBS.USER>> table if they exist.

SSO using IDCS

But what about SSO? How do we do that? Since Discoverer, as we’ve seen, relies on headers for SSO security (the username plus the GUID), we will need to find a mechanism in OCI that can leverage IDCS for the SSO part, and then inject the username and GUID headers into Discoverer following a succcessufl SSO authentication. IDCS Appgate comes to the rescue. It is basically a reverse proxy that sits in front of Discoverer and intercepts all inbound requests and redirects to IDCS for SSO authentication, before injecting username/GUID headers in the final redirected request to Discoverer. Appgate is configured as a SAML SP with IDCS as IDP. APPGATE extracts the username from the SAML response from the IDP and injects it as a username header. But how about the value of the GUID? How do we populate this value? Remember we said that this value is empty in the <<EBS.USER>> table. One solution is to ensure that the GUID column is prepoluated with the Username values; Or any other other value, as long as it's unique and can me mapped from the SAML response coming from the IDP.

In the diagram below we illustrate this flow.

  1. User points user agent (browser) at APPGATE reverse proxy url (https://<public domain url>/discoverer/viewer)

  2. APPGATE checks that user has a valid session, and if not triggers a SAML flow against IDCS.

  3. IDCS (if federated with an external IDP) will in turn send SAML request to the external IDP.

  4. SAML response received from external IDP.

  5. IDCS concludes federated SAML flow by sending the SAML response back to APPGATE.

  6. APPGATE processes the SAML response from IDCS, and maps and injects the custom headers (most importantly the GUID header), and redirects back to Discoverer landing page.

  7. Discoverer creates a server-side session with GUID value as key; the User is then re-promted for the Username only (no password required).

  8. Discoverer searches for user in the <<EBS.USER>> table and finds a match using (Username + GUID). User is now LOGGED in to Discoverer.

  9. Discoverer connects to the EUL (end-user layer) in the database and executes BI reports.

Steps to implement SSO for Discoverer using IDCS and APPGATE in OCI

Here is an outline of the steps you need to Setup Discoverer SSO in OCI (assuming EBS is secured by EBS asserter):

  1. Download the APPGATE appliance.

  2. Create an APPGATE appliance Custom Image in OCI.

  3. Instantaite an APPGATE instance in OCI.

  4. Setup APPGATE and configure integration with the IDCS instance This basically sets up APPGATE as a trusted client and allows it to invoke IDCS APIs and manage and create IDCS appilcations. (This step is the same step explained in more detail in the APGGATE documentation).

  5. Switch off the OHS instance in the Discoverer domain.

    • Use: <opmnctl stopall> command in the Discoverer weblogic domain.

    • This OHS instance is no longer needed as it will be replaced with APPGATE.

  6. Create a Header-based Application in APPGATE and configure custom headers.

    • Specify the Public Domain URL for the Discoverer application.

    • Specify the Protected Web Resource URL. This is the URL of the Managed Weblogic server that is running the Discoverer application.

    • Specify the following Post Login URL: https://<public domain url>/discoverer/viewer?connectionAccessType=APPS&eulName=eul_us. This is the URL that APPGATE will redirect the browser to post login. 

    • These are the custom headers required:

      • Name: Osso-User-Guid, Value: spgw-username (This is a dynamic header using this IDP datasource).

      • Name: Proxy-Remote-User, Value: spgw_username (This is a dynamic header using this IDP datasource).

      • Name: WL-Proxy-SSL, Value: false (This is a static header).

      • Name: Proxy-Auth-Type, Value: Osso SSO (This is a static header).

  7. Following the creation of the Header-based Application in APPGATE, APPGATE will then connect into IDCS as a trusted client and create a NEW SAML application using the same application name. This is the SAML application that will be used by APPGATE when SSO authenticating the inbound requests coming in for Discoverer. NOTE: You will need to go into IDCS and make sure that your Discoverer users in IDCS are assigned to this newly created SAML application. Otherwise IDCS will not authorise SAML access. 

  8. Configure Substitution Rules for content URL rewrites in the response will be required. They are as follows: 

    • subs_filter ‘http://<discoverer weblogic hostname>:<discoverer port>’ ‘https://<public domain url>

    • subs_filter ‘http://<discoverer weblogic hostname>’ ‘https://<public domain url>

    • subs_filter ‘/discoverer/app/exit?event=disconnect&clientType=viewer&CustomUrl=’ ‘/appgwyLogout’. This substitution rule ensures that the logout button in the Discoverer viewer page triggers the /appgwyLogout endpoint on the APPGATE which triggers in turn an SLO with IDCS.

  9. Switch on SSO in DISCOVERER.

    • The Discoverer configuration settings can be found in the following file: <discoverer_home>/discoverer/deploy/scratch/configuration/configuration.xml

    • Make sure you set the enableAppsSSOConnection switch to true in the following fragment:

      • ... userDefinedConnections="true" laf="dc_blaf" switchWorksheetBehavior="prompt" defaultLocale="en" disableBrowserCaching="false" enableAppsSSOConnection="true" propagteGUIDtoVPD="false" pageNavigation="true"> 

  10. Configure the certificate for Public Domain URL in APPGATE.

    • For this you'll have to login into the management console (ssh into the APPGATE VM) and then bring up the Services menu and then:

    • Press 6 on the NGINX menu to update an SSL certificate.

    • Review the certification format requirements, and press Enter to continue.

    • Enter the domain name, and press Enter.

    • Follow the directions, and press Enter when you are prepared to insert your certificate file.

    • Enter the new SSL certificate information, and press Esc when you are finished.

    • Type :wq and press Enter to close the window. After the certificate is validated, review and press Enter to return to the Services menu.

  11. Populate GUID column in EBS with IDP UserIds or whatever unique values you've chosen to use (as long as they're mappable to SAML response custom attributes coming from you IDP). This population step will require you manually execute a script agains the <<EBS.USERS>> table. It can be automated to populate automatically whenever a user is provisioned in IDCS/EBS. This will be discussed in a future blog.

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha