The Security Assertion Markup Language 2.0 (SAML2) is an XML-based markup language and an open standard for identity and service providers to communicate authentication and authorization information. Software-as-a-Service (SaaS) providers like Oracle, Google, Microsoft and many others, use SAML2 for identifying and providing access to users. For example, if your organization is subscribed to Google’s G Suite, the same credential used to login to Gmail, can also seamlessly provide access to Slack.

There are many advantages to using Single Sign-on (SSO). The most obvious reason is that users do not have to maintain an excessive number of account credentials, thereby reducing password fatigue. It also provides a more productive user experience as application users can navigate seamlessly between systems without having to re-enter user ID and passwords. For IT managers, it simplifies the overall infrastructure and user management support. Additionally, using a matured user management system means avoiding the need to “reinvent the wheel” and repeated cycles of security testing. Last but not least, reputable Identity Providers (IdP) often offer extra features such as multi-factor authentication to further protect logins. These can sometimes be costly or time-consuming to implement.

No out-of-the-box solutions, but not to worry

There are currently no out-of-the-box solutions for authenticating Oracle Application Express (APEX) applications using SAML2. However, integrating this Single Sign-on technology doesn’t need to be hard. The following recipe will show you how.

Ingredients
⦁ Oracle Linux 7.4
⦁ Apache HTTP Server version 2.4 or later. In addition to the modules installed by the package manager, the following two modules must also be installed:
⦁ mod_auth_mellon
⦁ mod_ssl
⦁ Java EE application server, e.g. Oracle WebLogic, Apache Tomcat
⦁ Oracle Database 11g R2 or later
⦁ APEX version 4.2 or later

The ideal setup would look something like this:

Instructions
A. Initial Setup and Installation of mod_auth_mellon

⦁ Install mod_auth_mellon using the package manager. On Oracle Linux 7.4:
$ yum install -y mod_auth_mellon
⦁ Create the directory /etc/httpd/mellon:
$ mkdir /etc/httpd/mellon
⦁ Set this as the current working directory:
$ cd /etc/httpd/mellon
⦁ Download the file mellon_create_metadata.sh, e.g:
$ wget https://raw.githubusercontent.com/UNINETT/mod_auth_mellon/master/mellon_create_metadata.sh
⦁ Make the file executable:
$ chmod a+x mellon_create_metadata.sh
⦁ Create the SAML2 metadata, by providing the Entity ID and Mellon endpoint. In the example, the domain is mysp.contoso.com. Replace this with an appropriate fully qualified domain name (FQDN) that is resolvable. Change the paths for the Entity ID and endpoint accordingly.
$ ./mellon_create_metadata.sh https://mysp.contoso.com/entityid https://mysp.contoso.com/myendpoint
Output files:
Private key: https_mysp.contoso.com_entityid.key
Certificate: https_mysp.contoso.com_entityid.cert
Metadata: https_mysp.contoso.com_entityid.xml
Host: mysp.contoso.com

Endpoints:
SingleLogoutService: https://mysp.contoso.com/myendpoint/logout
AssertionConsumerService: https://mysp.contoso.com/myendpoint/postResponse

Note the inputs and outputs from the script creating the SAML2 metadata for your server.

The key information you will need:
⦁ Entity ID (https://mysp.contoso.com/entityid) – this is used to identify your SP to the IdP.
⦁ ACS URL (AssertionConsumerService, https://mysp.contoso.com/myendpoint/postResponse) – this is the callback when the IdP successfully identifies the user. The Service Provider (SP) is expected to know what URL to redirect the request to after successful authentication.
⦁ Logout URL – use this to terminate user sessions.

B. Configure the Identity Provider

The following provides instructions for configuring the service provider (SP) to use Google G Suite as the IdP. You must have access to the administrators’ console to continue. If this is not the case, please contact your administrator perform the configuration on your behalf.
⦁ Firstly, login to the G Suite administrators’ console and access (click) the organization’s Apps (see red arrow).

⦁ Secondly, select “SAML apps”.

⦁ Thirdly, create a new SAML app association by clicking on the button on the bottom-right of the screen.

⦁ Then, Choose custom app, click “Setup my own custom app” at the bottom of the dialog.

⦁ The IdP metadata file will be generated. (1) Download this file and upload to the web server’s directory for storing the Mellon metadata files, e.g. /etc/httpd/mellon/GoogleIDPMetadata-contoso.com.xml. (2) Click “Next” when this is done.

⦁ (1) Enter the application’s name, and (2) click next to continue

⦁ (1) Enter the ACS URL and EntityID obtained from Part A, Step 6
. (2) Click next to continue.

⦁ Click “Finish”. Attribute mappings can be done later if needed.

⦁ Verify that the SAML app was created successfully.

C. Update the Apache HTTP Server Configuration

⦁ Add the following to the Apache2 configuration file, e.g. /etc/httpd/conf.d/ssl.conf:
# Adds Mellon session information to all requests to the web server
MellonEnable "info"

# Use the filenames provided by the mellon_create_metadata.sh script
MellonSPPrivateKeyFile https_mysp.contoso.com_entityid.key
MellonSPCertFile https_mysp.contoso.com_entityid.cert
MellonSPMetadataFile https_mysp.contoso.com_entityid.xml

# Add the full path to the IdP metadata that was downloaded when
# configuring the IdP
MellonIdPMetadataFile /etc/httpd/mellon/GoogleIDPMetadata-myidp.com.xml

# The endpoint path used when generating the SP metadata
MellonEndpointPath /myendpoint

# Add the following line to enable Mellon for the ORDS path
MellonEnable "auth"
ProxyPreserveHost On
ProxyPass https://localhost:8443/ords/
ProxyPassReverse https://localhost:8443/ords/

# Google returns the username as the MELLON_NAME_ID.
# We can inject this to the proxied request (to ORDS) and use the header
# variable for sign on.
RequestHeader add X-APPUSER %{MELLON_NAME_ID}e

⦁ Restart the Apache service:
$ systemctl restart httpd

D. APEX Application Authentication

Create an authentication scheme using the HTTP Header Variable template. The variable name to use is based on what is injected by the reverse proxy.

Specify the logout URL based on the values noted in section A. In addition to the URL, the parameter ReturnTo must also be specified. Finally, use the substitution parameter %POST_LOGOUT_URL%.

When a user signs out, the SP redirects to the IdP’s logout URL specified in the metadata before terminating the session on the service-side. Sessions on both ends must be terminated to prevent further access. Note that the IdP metadata from Google is missing the SingleLogoutService element and the following must be added to the IdP’s metadata file, after the element:

Security Considerations

We are reliant on the IdP to support the SAML Single Logout protocol. A user may initiate a sign out from either the IdP or SPs tied to the same session. If the IdP does not propagate the request, then there is a risk that the user will have continued access to your application. Therefore, most identity providers like Google and Microsoft, recommend that you close all browsers when you sign out.

Mellon’s default session length (see the configuration option MellonSessionLength) is one day. Therefore, consider reducing this value to mitigate this risk. When the Mellon session expires, it will reattempt to assert your identity. Users don’t need to reauthenticate if the IdP session remains valid.

Last but not least, as the approach uses APEX’s HTTP Header Authentication, it is critical to remember that no unauthorized user or system has direct access to the ORDS instance on the network. In the example above, it is expected that the server is hosted in a demilitarized zone (DMZ) and thus accessible by either the Internet or Intranet. If so, be doubly sure that the firewall is configured and running correctly. Only traffic to the reverse proxy ports (e.g. 443) should be permitted. It is also recommended that the application server hosting ORDS (e.g. Tomcat, WebLogic) be situated in a secured internal network that only system administrators have access to. And even so, these servers should permit HTTP/HTTPS requests only from the web proxy’s IP address and nowhere else. Failing which, a malicious actor could inject the appropriate HTTP Header variable and gain unauthorized access to the APEX applications and/or workspace!

See my Webinar on the fundamentals of identifying and managing access to APEX applications and components. It includes discussion of modern frameworks like OAuth2, SAML2, SCIM & more!

Finally, Download this pdf for additional information on enabling APEX SAML2 SSo with Microsoft Azure Active Directory (Office 365).