Integrating APEX with Oracle Identity Cloud Service

Introduction

The purpose of this blog post is to describe how to do the Integration of APEX(on-premise) with Oracle Identity Cloud Service(IDCS).
The integration described in this Post relies on APEX using the Oracle Rest Data Services(ORDS) deployed on Weblogic.

[caption id="attachment_46133" align="alignnone" width="712"] Login flow when APEX is integrated with IDCS[/caption]

1. Request a protected resource on WLS (No previous WLS session)
2. WLS will initiate a federation flow
3. IDCS login screen is shown to user
4. User provides credentials and is redirected back to WLS
5. WLS asserts the User Identity from the SAML token and creates a WLS session with a Virtual user
6. The ORDS application is configured to use a Servlet filter to inject a Header based on the current Weblogic user.
7. The ORDS application uses the Header and finds the User in the DB and establishes an APEX session

A central component of this integration is a custom Servlet Filter used to provide a HTTP Header to ORDS.

Also note that Federation is used since we want to have SSO across different applications once logged in to IDCS.
If you don't need SSO you could just use the IDCS Provider for Weblogic to handle the validation of credentials and creation of a WLS Subject.

Setting up the Integration

The integration consists of several parts that can be setup independently in order to verify the functionality.

High-level approach:

Part 1: Get the Snoop JSP and Servlet filter working

Part 2: Setup Federation to IDCS and ensure the Snoop JSP and Servlet Filter work

Part 3: Configure ORDS and test the complete flow

You don't need to deploy the Snoop JSP and test the Servlet Filter or the Federation setup. I just like to have these verification check points and know the basic stuff works.

Part 1 Setup the Servlet filter and protect the Snoop Servlet

My Snoop JSP is just a simple page made based on a quick Google search. The main purpose is to print out the Weblogic username and the value of the HTTP Header Auth-User and see that the values are the same. This will show that the Weblogic container security and the Servlet filter work as expected.

The example Servlet filter must be deployed to the WLS before the Snoop Servlet. To deploy the Servlet filter to your Weblogic Server you can simply copy the ApexSSOFilter.jar file to the WLS_DOMAIN_HOME/lib folder.
NOTE:Please change the file extension from .zip to .jar after downloading it.
On restart Weblogic will add the jar file to the Classpath and it will be available for the Snoop JSP.

<Aug 16, 2017 3:50:54 PM PDT> <Notice> <WebLogicServer> <BEA-000395> <The following extensions directory contents added to the end of the classpath: /Middleware/Oracle_Home/user_projects/domains/base_domain/lib/ApexSSOFilter.jar.>

The Snoop Servlet web.xml file contains the configuration to enable the Servlet Filter and use Federation when it is setup.

<filter>     <filter-name>ServletFilter</filter-name>     <filter-class>com.apex.custom.ApexSSOFilter</filter-class> </filter> <filter-mapping>     <filter-name>ServletFilter</filter-name>     <url-pattern>/*</url-pattern> </filter-mapping> ... <auth-method>CLIENT-CERT,BASIC</auth-method>

For the sake of testing I have configured the weblogic.xml file to allow access for users that are members of the Administrators group in Weblogic or members of the IDCS custom group called idcsusers.
So when testing without IDCS Federation we will use the Weblogic user which is also a member of the Administrators group.

There is nothing special about the snoop file and it should be deployed like any other WAR file.
NOTE:Please change the file extension from .zip to .war after downloading it.

When deployed try accessing it using a new browser window - http(s)://wls_server:port/snoop/snoop.jsp
A Basic popup window should show and your Weblogic user credentials should work.

The result should be a page looking similar to this:

The value of the Auth-User header is populated by he Servlet filter and is based on the current Weblogic Username.

At this point you have verified the Servlet filter has been deployed and is working as expected.

Part 2 Setup federation to IDCS

Setting up federation between WLS and IDCS has been described in detail in the post:"Identity Cloud Services and Weblogic Federation with Virtual Users and Groups" written by Paulo. Please follow his blog post.

There are a couple of changes we need to make:

1. Change the value for the "Redirect URIs" from "/FederationSampleApp/protected/*" to "/snoop/*" as our deployed application is using a different context root.
2. Create a test user in IDCS and ensure the username is NOT using the email address.
3. Create a group in IDCS called "idcsusers" and add your IDCS test user to this group.
4. Configure the SAML application defined in IDCS to use "NameID Format"="Unspecified" and "User Name"="User Name"

After making the above changes and restarting WLS try accessing the snoop Servlet using a new browser window - http(s)://wls_server:port/snoop/snoop.jsp
This time WLS should initiate a federation flow and redirect the browser to your IDCS login page.
Provide username/password for your IDCS test user and see that IDCS redirects the browser back to WLS and the Snoop Servlet displays information about the IDCS user.

If there is a problem with the flow I would suggest the following troubleshooting steps:

1. When browsing to http(s)://wls_server:port/snoop/snoop.jsp, if some WLS error shows up then the problem could be with the federation setup on the WLS side. I would suggest checking the WLS federation setup.




2. If the IDCS login page shows up and the browser is redirected back to WLS and then a WLS error is shown there can be multiple reasons but my first reaction would be to check the SAML Assertion returned by IDCS is in fact containing a proper username and group membership attribute.
   This can easily be checked by using the Browsers Dev tools to get the HTTP Header and SAML Assertion from the POST data and then doing a BASE64 decode.
   Note: the Groups attribute in the SAML Assertion must have an upper case G!

Part 3 Configure ORDS and test the end-2-end flow

We need a few more steps to configure APEX(ORDS).

1. For your specific APEX application you need to update the Authentication scheme type used to allow for HTTP Headers.

The scheme must use a HTTP Header with the exact value of "Auth-User” as this is the HTTP Header set by the Servlet filter.

2. The web.xml and weblogic.xml files for the ORDS application must be updated to include the Servlet filter configuration and the security settings to trigger the federation flow.
I suggest unzipping the ORDS.war file and changing the two XML files and then repackaging it as a new ZIP/WAR file. The existing ORDS deployment in WLS can be updated with the new version of this file.

The web.xml file requires the following additions:

<filter>  <filter-name>ServletFilter</filter-name>   <filter-class>com.apex.custom.ApexSSOFilter</filter-class> </filter> <filter-mapping>  <filter-name>ServletFilter</filter-name>  <url-pattern>/*</url-pattern> </filter-mapping> <security-constraint>  <web-resource-collection>   <web-resource-name>ProtectedPages</web-resource-name>   <url-pattern>/*</url-pattern>  </web-resource-collection>  <auth-constraint>   <role-name>apextestrole</role-name>  </auth-constraint> </security-constraint> <login-config>  <auth-method>CLIENT-CERT,BASIC</auth-method>  <realm-name>default</realm-name> </login-config> <security-role>  <role-name>apextestrole</role-name> </security-role>

I added this at the bottom of the web.xml just before the closing web-app tag.

The weblogic.xml file requires the following additions:

<security-role-assignment>  <role-name>apextestrole</role-name>  <principal-name>idcsusers</principal-name>  <principal-name>Administrators</principal-name> </security-role-assignment>

I added this just before the context-root tag.

3. Create an APEX test user with the exact same name as the IDCS tester user created previously. Please test this user and ensure access to the APEX application works when providing Username/Password.

4. In order to have WLS trigger a federation flow we need to add the context root of the ORDS application to the Redirects URI field.
This means updating the value for the "Redirect URIs" from "/snoop/*" to "/ords/*"or if you want to test both you can just add /ords/* on a new line. Ensure the value used matches the context-root defined in the weblogic.xml file.

Note: There are different ways this can be configured and the above is just an example used for the purpose of this blog post. The apextestrole maps to the Administrator group in WLS which is not a good idea in a Prod deployment.

Please restart your WLS and try to access the direct link to your APEX application.
This should trigger a federation flow just as seen when using the Snoop page.
After providing the correct IDCS test user credentials the browser should be redirected back to WLS and the APEX application should open up and show the correct username in the top right corner.

In case the APEX Application does not show up but an ORDS Authorization error is shown I suggest to open the Snoop page url and check that it will actually show and the username matches the APEX test user.
If the Snoop page shows as expected then the problem is with the actual Apex configuration.

This integration does not cover the logout process at this time.
Hopefully I find time to add the details later.

Disclaimer: Any code shown or provide in this blog post is just to be used as example code and not under any circumstance be used in actual Production deployments.