Connecting Oracle APEX to IDCS
- Go to https://apex.oracle.com/ and create a free workspace; follow the easy steps.
- Sign-In to your new APEX workspace.
- Click on the App Gallery icon.
- For our example click on the Group Calendar icon to install.
- Click on the Install App button.
- Click Next.
- Click the Install App button.
- Once finished click on the Manage icon (looks like a gear).
- Click the Unlock button, this lets you modify it for an authentication scheme later.
- Click the Unlock Application button to complete.
- Click on the Group Calendar play button and Sign-In.
- Click Complete Set Up button with all the defaults; you should see something similar to Figure 1 below.
- 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=”
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.
- If not already, Login to your APEX workspace https://apex.oracle.com/.
- Click on the App Builder icon.
- Click on the Workspace Utilities icon.
- Click on the Web Credentials link.
- Click the Create button.
- 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>
- Click the Create button to complete (see Figure 3 below).
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.
- If not already, Login to your APEX workspace https://apex.oracle.com/
- Click on the App Builder tab.
- Hover the mouse over the Group Calendar icon and click the pencil Edit icon
- Click on the Shared Components button.
- Under the Security section click on the Authentication Schemes link.
- Click the Create button.
- Use the Based on a pre-configured scheme from the gallery and click the Next button.
- 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"
- Click the Create Authentication Scheme to complete; this will also make the new scheme current.
- Now click on the IDCS Authentication Scheme - Current link.
- Click on the Post-Logout URL tab.
- 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>.
- Click the Apply Changes button to save.
- Click on the Show All tab and you should see something similar to Figure 4 below.
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.
- Go to the https://apex.oracle.com/pls/apex/f?p=<your_apex_number_here> link you copied from earlier.
- You should be prompted by the IDCS login.
- 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).
- 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.
- Logged into the APEX Calendar application click on the top right user profile and select Sign Out.
- If successful it should sign you out and bring you back to the IDCS sign in page.
- 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
- Sign-In to Identity Cloud Service https://idcs-<guid>.identity.oraclecloud.com/ui/v1/adminconsole as an Administrator again.
- From the Applications section click on the Applications cloud icon or in the hamburger menu click on Applications.
- Search and find your Confidential Application that was created earlier called APEX Calendar App and select it.
- Click on the Configuration tab.
- Expand the Authentication and Authorization section and you will see Enforce Grants as Authorization.
- Check the Enforce Grants as Authorization check box and click the Save button (see Figure 6 below).
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.
Figure 7: IDCS Warning you are not authorized
Adding Group Authorization
- Continuing in the Admin Console of Identity Cloud Service click on Groups by opening the hamburger menu.
- Click the Add button.
- In the Name field enter a name APEX Calendar and click Next.
- Search for your user account and click the checkbox next to it, you can add more users later.
- Click Finish.
- Go back to the Applications menu and find the APEX Calendar App application and open it.
- Select the Groups tab.
- Click the Assign button.
- 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.
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.