X

Best Practices from Oracle Development's A‑Team

Integrating SSO between APEX Cloud and Identity Cloud Service the Easy Way

Tim Melander
A-Team Cloud Solution Architect

Johannes Murmann wrote a great blog Integrating APEX with Oracle Identity Cloud Service, but this integration is for APEX running on-premises.  Fast forward, APEX has moved to the cloud like many other things, so I thought I should write an article on how to integrate the cloud version of APEX with Oracle Identity Cloud Service.  The integration is quite different as it uses the OpenID Connect protocol, and should be possible with any APEX cloud application.  As a bonus you to this entire setup using a free trial APEX workspace at https://apex.oracle.com that takes about 2 minutes, install a sample application that comes with the APEX workspace in about 3 minutes, and complete the integration with Identity Cloud Service in about 15 minutes (Assuming you have an IDCS tenant and are an Administrator).  In all, this entire setup from start to finish should only take about 30 minutes or less. So let’s hit that timer and get started!

Install a Sample Application in APEX

This section assumes you can follow the simple steps to get your free trial APEX workspace, and then will step you through installing a sample Calendar application so that we have an example to configure OpenID Connect with Identity Cloud Service.  This section should take about 5-7 minutes.

  1. Go to https://apex.oracle.com/ and create a free workspace; follow the easy steps.
     
  2. Sign-In to your new APEX workspace.
     
  3. Click on the App Gallery icon.
     
  4. For our example click on the Group Calendar icon to install.
     
  5. Click on the Install App button.
     
  6. Click Next.
     
  7. Click the Install App button.
     
  8. Once finished click on the Manage icon (looks like a gear).
     
  9. Click the Unlock button, this lets you modify it for an authentication scheme later.
     
  10. Click the Unlock Application button to complete.
     
  11. Click on the Group Calendar play button and Sign-In.
     
  12. Click Complete Set Up button with all the defaults; you should see something similar to Figure 1 below.
     
  13. Copy the browser URL up until the last guid; e.g. https://apex.oracle.com/pls/apex/f?p=137942 and save this for later when registering the IDCS Confidential Application.
    Note: If you are using the OCI Autonomous Database + APEX services the leading hostname and URI prefix will change from “https://apex.oracle.com/pls/apex/f?p=” to "https://<guid>-demodb.adb..oraclecloudapps.com/ords/f?p=”.

 

Graphic 1

Figure 1: APEX Group Calendar

 

Register a Confidential Application in IDCS

This section creates a confidential application in Identity Cloud Service, which is basically an OAuth2 client that will use a three-legged authorization flow via the OpenID Connect protocol with the APEX cloud calendar application to single sign-on.  If you want more detail on OAuth 3-legged flow, Christopher Johnson wrote a great blog on this named Creating a 3-legged OAuth Application in IDCS

In this section I assume you already have an Oracle Identity Cloud Service tenant and an Administrator, if not, get both or find someone that has both.  This section should take about 5-7 minutes.

NOTE:  The <guid> value in the URL parameter https://idcs-<guid>.identity.oraclecloud.com is the unique identifier that is automatically created for your tenant. 

  1. Sign-In to Identity Cloud Service https://idcs-<guid>.identity.oraclecloud.com/ui/v1/adminconsole as an Administrator.
     
  2. From the Applications section click on the Applications cloud icon or in the hamburger menu click on Applications.
     
  3. Click the Add button.
     
  4. Select Confidential Application.
     
  5. In the App Details section complete the following:

    5.1 Name: "APEX Calendar App"

    5.2 Description: "APEX Sign In for Calendar Application"

    5.3 Application URL: <paste in the APEX calendar application URL from earlier>
     
  6. Click Next.
     
  7. Select Configure this application as a client now.
     
  8. In the Authorization section complete the following:

    8.1 Allowed Grant Types: check "Authorization Code".

    8.2 Redirect URL: https://apex.oracle.com/pls/apex/apex_authentication.callback
    Note: If you are using the OCI Autonomous Database + APEX services the leading hostname and URI prefix will change from “https://apex.oracle.com/pls/apex/apex_authentication.callback” to "https://<guid>-demodb.adb..oraclecloudapps.com/ords/apex_authentication.callback”.


    8.3 Logout URL: https://idcs-<guid>.identity.oraclecloud.com/oauth2/v1/userlogout

    8.4 Post Logout Redirect URL: e.g. https://apex.oracle.com/pls/apex/f?p=<your_apex_number_here>   (Must match what is added later in the APEX Authentication Scheme Post-Logout URL.)
    Note: If you are using the OCI Autonomous Database + APEX services the leading hostname and URI prefix will change from “https://apex.oracle.com/pls/apex/f?p=<your_apex_number_here>” to "https://<guid>-demodb.adb..oraclecloudapps.com/ords/f?p=<your_apex_number_here>”.

     
  9. Click Next.
     
  10. Click Next to Skip for later --- Expose APIs to Other Applications.
     
  11. Click Next to Skip for later --- Web Tier Policy.
     
  12. Click Finish on Authorization (Do not check Enforce Grans as Authorization).
     
  13. Copy the Client ID and Client Secret to a text editor and save for later.

    13.1 Client ID: <your_client_id_here>

    13.2 Client Secret: <your_client_secret_here>
     
  14. Click the Close button.
     
  15. Click the Activate button on the top right.
     
  16. Click the Activate Application button at the Activate Application prompt to confirm (see Figure 2 below).

 

Graphic 2

Figure 2: IDCS Confidential Application

 

Create a new Web Credential in your APEX workspace

This section will show you how to create a new web credential in your APEX workspace.  The web credential maps the details of the Identity Cloud Service confidential application details used in the authentication scheme that will be created in the next section.  This section should take about 5 minutes.

  1. If not already, Login to your APEX workspace https://apex.oracle.com/.
     
  2. Click on the App Builder icon.
     
  3. Click on the Workspace Utilities icon.
     
  4. Click on the Web Credentials link.
     
  5. Click the Create button.
     
  6. In the Web Credentials Attributes section complete the following:

    6.1 Name: "IDCS Web Credentials"

    6.2 Authentication Type: "Basic Authentication"

    6.3 Client ID or Username: <Paste in Client ID from earlier>

    6.4 Client Secret or Password: <Paste in Client Secret from earlier>

    6.5 Verify Client Secret or Password: <Paste in Client Secret from earlier>
     
  7. Click the Create button to complete (see Figure 3 below).

 

Graphic 3

Figure 3: APEX Web Credential

 

Create a new Authentication Scheme in APEX for the Calendar App

We are in the final stretch.  This section will show you how create an authentication scheme for the Calendar application that will tie into the web credential created earlier in order to glue it all together.  The authentication scheme tells you how the login and logout will be configured using the proper protocol to make SSO work. This section should only take about 5 minutes.

  1. If not already, Login to your APEX workspace https://apex.oracle.com/
     
  2. Click on the App Builder tab.
     
  3. Hover the mouse over the Group Calendar icon and click the pencil Edit icon
     
  4. Click on the Shared Components button.
     
  5. Under the Security section click on the Authentication Schemes link.
     
  6. Click the Create button.
     
  7. Use the Based on a pre-configured scheme from the gallery and click the Next button.
     
  8. In the Authentication Scheme section select Social Sign-In from the Scheme Type and complete the following:

    8.1 Name - "IDCS Authentication Scheme"

    8.2 Scheme Type: "Social Sign-in"

    8.3 Credential Store: "IDCS Web Credentials" <-- It should default to the Web Credential created earlier.

    8.4 Authentication Provider: "OpenID Connect Provider"

    8.5 Discovery URI: "https://idcs-<guid>.identity.oraclecloud.com/.well-known/openid-configuration"

    8.6 Scope: "profile"

    8.7 Username Attribute: "sub"

    8.8 Convert Username To Upper Case: "No"
     
  9. Click the Create Authentication Scheme to complete; this will also make the new scheme current.
     
  10. Now click on the IDCS Authentication Scheme  - Current link.
     
  11. Click on the Post-Logout URL tab.
     
  12. Select the URL from Go to and in the URL field <paste in the APEX calendar application URL from earlier; must match the IDCS Post Logout Redirect URL>.
     
  13. Click the Apply Changes button to save.
     
  14. Click on the Show All tab and you should see something similar to Figure 4 below.

 

Graphic 4

Figure 4: APEX Authentication Scheme

 

Test the LOGIN and LOGOUT to the APEX Group Calendar using IDCS

Now to test the fruits of your labor.   These steps should be pretty straight forward, but I figured I should put them both in here to be complete.

LOGIN or SIGN-IN

Try to login or sign-in using the following simple steps.

  1. Go to the https://apex.oracle.com/pls/apex/f?p=<your_apex_number_here> link you copied from earlier.
     
  2. You should be prompted by the IDCS login.
     
  3. The first time you will be prompted with a APEX Calendar App OAUTH2 to Allow or Don't Allow, click the Allow button (see Figure 5 below).
     
  4. If successful it should sign you into the APEX Calendar application.

 


Figure 5: APEX OAuth Allow/Don't Allow Prompt

 

LOGOUT or SIGN-OUT

Try to logout or sign-out with the following steps.  Note that once signed out you will need to go to the link back to the APEX Calendar application you used earlier.

  1. Logged into the APEX Calendar application click on the top right user profile and select Sign Out.
     
  2. If successful it should sign you out and bring you back to the IDCS sign in page.
     
  3. Note if you sign in again from this page you will go to the IDCS My Apps page.  Go back to the APEX Calendar application link to login again.

 

Authorizing Access using Groups or Users

Now to take one step further and talk about authorization.  What we previously did was integrate the APEX calendar application to use Identity Cloud Service for authentication, but that will give any user that can authenticate to Identity Cloud Service access.  In the real world we will want to limit access in some way.  This section will explain one way to limit access to our sample calendar application using IDCS users or groups, and it is quite simple. 

Enforce Grants to the APEX Application

  1. Sign-In to Identity Cloud Service https://idcs-<guid>.identity.oraclecloud.com/ui/v1/adminconsole as an Administrator again.
     
  2. From the Applications section click on the Applications cloud icon or in the hamburger menu click on Applications.
     
  3. Search and find your Confidential Application that was created earlier called APEX Calendar App and select it.
     
  4. Click on the Configuration tab.
     
  5. Expand the Authentication and Authorization section and you will see Enforce Grants as Authorization.
     
  6. Check the Enforce Grants as Authorization check box and click the Save button (see Figure 6 below).

 

Graphic 6

Figure 6:  IDCS APEX Confidential Application Enforce Grants as Authorization

 

At this point if you sign-out and sign-in again to the APEX Calendar application you will see a message that says "You are not authorized to access the app. Contact your system administrator." (see Figure 7 below).  This is because now that Enforce Grants as Authorization is being used no user is authorized access.  We don't want that, so let's continue to the next steps and see how we can use a group or user to grant access to the calendar application.

 

 

Graphic 7

Figure 7: IDCS Warning you are not authorized

 

Adding Group Authorization

  1. Continuing in the Admin Console of  Identity Cloud Service click on Groups by opening the hamburger menu.
     
  2. Click the Add button.
     
  3. In the Name field enter a name APEX Calendar and click Next.
     
  4. Search for your user account and click the checkbox next to it, you can add more users later.
     
  5. Click Finish.
     
  6. Go back to the Applications menu and find the APEX Calendar App application and open it. 
     
  7. Select the Groups tab.
     
  8. Click the Assign button.
     
  9. Search for the group APEX Calendar that was created and click the checkbox next to it and finally click OK.

Now try to sign-out and sign-in again to the APEX Calendar application.  This time you should find that you can access the APEX Calendar app.  You can repeat this process and user users instead of groups or a combination of both if you want.

Summary

This article should show how easy it is to setup Single Sign-On with your APEX cloud application.  If you create multiple APEX cloud applications you will need to create the same three components for each application, 1) IDCS confidential application, 2) APEX web credential, and 3) the authentication scheme.  This is so that each confidential application you create in IDCS can be assigned unique groups or users for that unique application. 

If you were to assign an authentication scheme to one confidential application that is configured to a group or user(s) for multiple applications, this would paint yourself into a corner since it would automatically authorize a user to all the applications belong to that group that authorizes that single confidential application. 

In closing, I hope this article shows you how easy it is to setup SSO between an APEX cloud application and Identity Cloud Service along with some tips on providing at least one way to authorize a user to the APEX application using groups or users. 

 

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