Prerequisites

• IDCS administration access for partner app setup
• APEX 18+ with an application for authentication setup

IDCS Trusted Application Setup

There are many options in IDCS. We will cover the very minimum first, then come back to discuss other features. To start, you will need to be logged into your IDCS administration console with access to Application settings.

Step 1. Add Trusted Application Wizard

Add and application using the IDCS dashboard Select “Trusted Application”

Step 2. Application Naming and Login URL Information

Provide Name, Description, and optionally the APEX Application Login URL.

Click Next.

Step 3. Application Client Configure

In the wizard client step, select “Configure this application as a client now.”

Allowed Grant Types: check Authorization Code

Allow non-HTTPS URLs check box: check only if you are using unencrypted web traffic (not recommended for production)

Redirect URL: Enter the APEX URL for the authentication callback with your hostname and listener substituted. This will be the SAME for all applications using IDCS authentication served by the same APEX host.

Pattern:

http://[server]:[port]/[listener]/apex_authentication.callback

Click Next

Step 4. Complete the Wizard

No Information is needed for resources, web tier policy, or authorization. – Click Next, Next, and Finish to complete the wizard.

You will be presented with a Client ID and Client Secret. This is synonymous with a username and password for your application access. These values will be added to the APEX application credential store.

Keep this information private. This information can be retrieved again from the application definition page in IDCS.

Step 5. Activate Application

The applications can be activated and deactivated independently. After creation, the default status is deactivated.

Click “Activate” to allow the setup to be used.

The IDCS Partner application is now setup and ready to accept requests.

APEX APP Auth-N Setup

Create an application or use an existing application to setup a new authentication scheme. APEX Social Sign-In Authentication has two major components. Web Credentials: To store the client ID and client secret An Authentication Scheme: To determine how IDCS will be contacted, what credentials will be used, and what information will be stored at the time of login.

Step 1. Create APEX Web Credentials

In the APEX application → Shared Components → Security → Web Credentials: Create a new entry

Name: Name that will be referenced in the authentication scheme

Authentication Type: Basic Authentication

Client ID and Client Secret: Values from the IDCS registration. Client Secret will need to be entered twice for validation.

Click Create to store the values.

NOTE: The client ID and Client Secret values are white space sensitive. Make sure there are no extra values at the ends of the lines from a copy paste operation. If run in debug mode, APEX may display the following message if your client secret is contaminated with white space.

https://[idcs-server]/oauth2/v1/token request got HTTP status 401

OAuth2 Authorization error "invalid_client". Client authentication failed.

Step 2. Create Authentication Scheme

In the APEX application → Shared Components → Security → Authentication Schemes: Create a new entry

Name: [Any Authentication Scheme Name]

Scheme Type: Social Sign-In

Credential Store:

Authentication Provider: OpenID Connect Provider

Discovery URL: https://[idcs-service-url]/.well-known/openid-configuration/

Scope: profile

Username Attribute: sub

Click – Create Authentication Scheme. This will save and make the the new authentication scheme current.

Step 3. Test the Application

Run the APEX application. Note: Do not run a public page such as the default login page. APEX should redirect to the IDCS login page when requiring authentication.

Authenticate in IDCS using your username and password. Note: If your browser session is already authenticated into IDCS, the redirect back to APEX will be automatic.

Approve access to profile information. This is prompted only the first time a user is authenticated.

APEX will use the “sub” attribute for the APEX username attribute.

User should now be redirected back to APEX and identified as an authenticated user!

How Does This Work?

Here are the basic steps of how this authentication works. (paraphrased for brevity)

When APEX determines the current session is not authenticated, it will fetch the discovery URL identified as …/.well-known/openid-configuration/.

APEX redirects the browser to the “authorization_endpoint” with attributes including an encoded “state” value to assure APEX can find the specific application it was called from.

The IDCS server will authenticate the user and verify the callback URL. IDCS will redirect the browser to the /apex_authentication.callback URL with the state value and a one time use code.

APEX will receive the code and state value then make a call to the “token_endpoint”. This will provide APEX with a ID token and an access token.

Internally, APEX will evaluate the contents of the ID token information to determine if the requested username attribute and additional user attributes are included as defined in the Authentication Scheme. If they are not present, an additional call is made to the “userinfo_endpoint” where the attributes are again searched for.

Failure to find the “username attribute” defined in the authentication scheme will result in an error.

Null username passed to login procedure. Contact your application administrator. Details about this incident are available via debug id #####

The information received is available during the Post-Authentication Procedure of the APEX authentication scheme.

How To Do Auth-Z (Authorization)

Once you have configured Auth-N (authentication) in your APEX application, all users in your IDCS can now have access to your application. This may or may not be your goal. In the case that you would like to limit access to a subset of users, you can use several methods.

The question is: Where do you want to maintain the list of users? As you have a fancy cloud based identity solution, let’s assume you will use it to it’s full extent.

Allow List – or – Lock Everyone Out

First, we need to deny everyone access to the application through IDCS. We can easily do this by updating the setting on our application. Under Authentication and Authorization, click the “Enforce Grants as Authorization” check box. Save the changes and start a new APEX session causing the application to re-authenticate.

When authenticating to your APEX app, you should be presented with a message that says:

“You are not authorized to access the app. Contact your system administrator.”

Assign a Single User

In IDCS, review the application setup and navigate to the users tab. Here, users can be added individually. Add users with the Assign button. Test with a new browser session. Users assigned to the application can authenticate as expected.

Using Groups

Groups can also be used, but require an additional step. From the IDCS Admin Console, groups need to be created first. Once a group is created, users are assigned to that group.

A group is given access to an application. This can be done from the Group screen or the Application screen. One group can have multiple applications assigned to it and one application can have multiple groups assigned.

Demo of APEX Application Multiple Group Separation

In the case where we to change the features or behavior of an app based on the groups a user belongs to, (Example: Administrators), we will need additional information.

In this demo APEX application, we would like to show a special region for users that are a member of the APEX-IDCS-APP-ADMIN group.

APEX Preparations

The following are normal APEX development Activities. Create authorization scheme called USER_IS_ADMIN.

Name: USER_IS_ADMIN

Scheme Type: Is In Role or Group

Type: Custom

Names: APEX-IDCS-APP-ADMIN

Create a page region to protect and assign the security authorization to “USER_IS_ADMIN”

APEX Authentication Scheme Update

Update the APEX authentication scheme to include the “groups” in the Scope and in the Additional User Attribute to cause the “userinfo_endpoint” to be called.

Add the following PL/SQL Code in the SOURCE region of the Authentication Scheme

procedure load_dynamic_groups as
    l_group_names apex_t_varchar2;
begin
    --
    -- add all group names to l_group_names
    --
    for i in 1 .. apex_json.get_count('groups') loop
        apex_string.push (
            p_table => l_group_names,
            p_value => apex_json.get_varchar2 (
                        p_path => 'groups[%d].name',
                        p0     => i ));
    end loop;
    --
    -- save group names in session
    --
    apex_authorization.enable_dynamic_groups (
        p_group_names => l_group_names );
end;

Add the load_dynamic_groups in Login Processing → Post-Authentication Procedure Name

APEX Login Processing Apply Changes and Test

After successful authentication, the userinfo_endpoint will be called and the results will be made available to the Post-Authentication procedure. The JSON results are converted to list of groups and stored in an APEX session builtin for group management. The values can be queried using the APEX_WORKSAPCE_SESSION_GROUPS view.

This is just one example of utilizing values from the userinfo_endpoint. Additional values can also be read and used in the APEX application.

IDCS My Apps

When in IDCS, the Application definition can be configured with a LOGIN URL. The “Display in My Apps” check box allows the application to be displayed in an IDCS dashboard list of applications. The Application Icon can be customized to distinguish the application to your users. This will allow direct navigation to your APEX application from a users IDCS dashboard and looks snazzy while doing it.

IDCS has additional features including for displaying lists of applications, requesting access to applications, and customizing the permissions page. These are all configurable based on your organizations needs. Refer to the comprehensive documentation included with Oracle Identity Cloud Service

Troubleshooting

Here are some tips if you are having issues getting IDCS authentication working.

Unit test the REST call from APEX

You have APEX builder working. Run the following from your APEX SQL Workshop. (should work for any workspace) This will tell you if your database is allowed to make external calls and setup to do HTTPS secure traffic.

select apex_web_service.make_rest_request(
    p_url => 'https://[idcs-server]/.well-known/openid-configuration/',
    p_http_method => 'GET') as X
from dual;

ACL Error

If you receive an error similar to:

ORA-29273: HTTP request failed ORA-06512: at "SYS.UTL_HTTP", line 1130
ORA-24247: network access denied by access control list (ACL)

… you have not granted APEX the ability to make external calls. The APEX documentation has details on setting this up. Review the ACL structures and setup one that works with your security rules.

From APEX 19 docs – Enabling Network Services in Oracle Database
From Tim Hall – Oracle-Base – Fine Grained Access to Network – 11g 12c

Certificate Error

If you receive an error similar to:

ORA-29273: HTTP request failed
ORA-29024: Certificate validation failure
ORA-06512: at "SYS.UTL_HTTP", line 380

… you need to review your wallet setup. Oracle uses a certificate wallet to control and limit the trusted certificates which are allowed to conduct HTTPS encryption. Services like Oracle DBaaS do not come with a certificate wallet.

To resolve this, refer to the following:

Carsten Czarski – APEX, HTTPS, certificates and the Oracle Wallet ( detail )
Tim Hall – Oracle Base – UTL_HTTP and SSL (HTTPS) using Oracle Wallets
APEX Documentation (18) – Oracle APEX Wallet Configuration
Oracle Doc (12.1) – Using the orapki Utility to Manage PKI Elements

NOTE: This is NOT the TDE (Transparent Data Encryption) wallet. This is a certificate wallet like your browser has to accept HTTPS traffic. Do not confuse these.

Other Write-ups on the Authentication Topic

Header variable method setup from Oracle ATeam
IDCS to manage social logins from Oracle ATeam
Google Auth on Apex EA release from Adrian Png
Microsoft Auth on Apex EA release from Morten Braten

References

https://docs.oracle.com/en/cloud/paas/identity-cloud/blogs.html
http://openid.net/