Introduction

In our previous blogs, we set up a Customer-Managed ORDS for an Autonomous Database in Oracle Cloud and secured it with SSL. Now, let's dive into configuring ORDS to use something like SAML for Single Sign-On. Oracle APEX is great because it supports both SAML and OpenID Connect for authentication. In this blog, we'll walk through setting up SAML Single Sign-On for an APEX instance using Microsoft Entra-ID as the Identity Provider.

SAML is an XML-based protocol that helps exchange security information on the Web, enabling Single Sign-On. This means users can log in once and access multiple services seamlessly.

For this setup, we'll need to configure the Autonomous Database to use ORDS in a Customer-Managed environment. This is because, with the default ORDS on the Autonomous Database, you can't modify any of the ORDS configuration options. By installing and configuring a Customer-Managed environment for ORDS, we can adjust the ORDS settings, specifically our SAML configuration, to suit our needs.

Prerequisites

Before we dive in, please make sure you have completed the following prerequisites listed below. This will enable you to move through this guide seamlessly.

• Follow the previous blogs to set up a Customer-Managed ORDS. ✅

• Azure AD Account ✅

All set? Let's go! 🚀

Cross-Origin Resource Sharing with SAML

The SAML authentication flow needs Oracle REST Data Services (ORDS) to allow cross-origin requests from your Identity Provider to Oracle APEX. Normally, ORDS doesn't permit cross-origin requests to its PL/SQL gateway, which includes Oracle APEX. To fix this, you'll need to configure ORDS to recognize your Identity Provider as a trusted origin by setting the security.externalSessionTrustedOrigins configuration parameter.

So, go ahead and open your terminal and connect to your Compute Instance where ORDS is running. Then, type in the following command:

sudo su oracle
ords --config $ORDS_CONFIG config set security.externalSessionTrustedOrigins "https://your-app-domain.com,https://login.microsoftonline.com"

Here's a breakdown of what each part of the command does:

• ords: This is the command-line tool for Oracle REST Data Services.

• --config $ORDS_CONFIG: This flag specifies the path to your ORDS configuration directory. The $ORDS_CONFIG variable should be set to the location where your ORDS configuration files are stored.

• config set security.externalSessionTrustedOrigins: This part of the command sets the trusted origins for external sessions. You will need to provide a list of trusted domains or IP addresses that are allowed to initiate sessions with your ORDS instance.

• https://your-app-domain.com,https://login.microsoftonline.com: This is a comma-separated list of the trusted domains. Replace https://your-app-domain.com with the actual domain of your application and https://login.microsoftonline.com with the domain of your Identity Provider, such as Microsoft Online for Entra-ID.

Once you have set the trusted origins, it is a good practice to verify the configuration to ensure that it has been applied correctly. You can do this by checking the configuration files or using ORDS management tools.

ords --config $ORDS_CONFIG config list

This command will show you all the current settings, so you can make sure your changes went through just fine.

Set up Entra-ID

Next, let's move on to Azure Entra ID. Here, we'll create an Enterprise application and manage Users and Groups. So let´s start with that 😉

Create an Entra-ID Enterprise App for Single Sign-On

The first step that we want to do is to create a new Enterprise App in Entra-ID and get the metadata.

Go to Portal.azure.com and click on Microsoft Entra ID. Next, click Enterprise Applications, and then Create your own application. The Add your own application pane displays. Specify a name, for example, APEX-SAML-SSO, and then click Create. In a few seconds, the application will be ready to configure. The Application Overview page displays.

Let's move forward and set it up.

Configure Single Sign-On for the Entra-ID Enterprise App

Alright, now that we're on the Getting Started page, let's go ahead and select Set up Single sign-on. Then select SAML as a Single Sign-On method.

The Set up Single Sign-On with SAML page is displayed. Let's go ahead and fill in some Basic SAML Configuration settings. Just scroll to the Basic SAML Configuration section and click Edit in the upper-right corner.

Enter the Entity-ID and the Reply URL, which are key parts of setting up Single Sign-On (SSO) with SAML. The Entity-ID is a unique identifier for your app in the SAML setup. It's usually a URL or URI that represents your app. The Reply URL, also known as the Assertion Consumer Service (ACS) URL, is where the SAML assertion goes after a user logs in successfully. Both the Entity ID and the Assertion Consumer URL will be the same.

https://your-app-domain.com/ords/apex_authentication.saml_callback

The format of this URL typically includes your application's base URI followed by the specific endpoint for SAML authentication. For example, if your application's base URI is https://your-app-domain.com/ords, the complete callback URL would be https://your-app-domain.com/ords/apex_authentication.saml_callback. This endpoint is essential for handling AJAX callbacks from the identity provider, ensuring that once a user is authenticated, the necessary authentication assertions are correctly processed by your application. Make sure to replace the placeholder with your actual application's base URI to ensure seamless integration and functionality.

https://tm-apex.de/ords/apex_authentication.saml_callback

Optionally, you have the choice to enter a Logout URL, which is used to redirect users to a specific page after they log out of the application. In this scenario, you can use the same URL that was previously entered as both the Identifier and the Reply URL. By doing this, you maintain a seamless user experience, as the Logout URL will guide users back to the designated location, ensuring they are properly signed out of the application.

Finally click Save.

Next, let's adjust the SAML Certificates settings. Simply scroll down to the SAML Certificates section and click Edit in the top-right corner.

Change the Signing Option from "Sign SAML assertion" to "Sign SAML response and assertion" and make sure the Signing Algorithm is set to SHA-256. Once you've done that, just click Save.

Once you're finished, go ahead and download the Base64 Certificate. You'll need it later in Oracle APEX.

Finally, make sure to note down the Login URL and Microsoft Entra Identifier. You'll also need these later in Oracle APEX.

That´s it. You've completed the configuration part for Entra-ID. Now we can move on to setting up the configuration in Oracle APEX.

Set up Entra-ID as an Identity Provider for Oracle APEX

The first part is complete, so go back to APEX and log in to "Administration Services".

Configure the SAML Sign-In Authentication Scheme for your instance

Then navigate to “Manage Instance > Security > Development Environment Authentication Schemes” and click the pencil icon next to SAML.

First, let's set up some configurations under SAML for Internal and Workspace Applications: APEX Attributes.

• Enable SAML for Applications. This allows workspace applications to use SAML authentication.

• Enter the Issuer attribute that Oracle APEX sends. This attribute defaults to the callback URL (e.g. tm-apex.de/ords/apex_authentication.saml_ca..).

• Then we need an RSA Certificate and Private key on the APEX side. To generate a new certificate and private key for your Oracle APEX setup, you can use the openssl command-line tool. Open your terminal or command prompt. Then, enter the following command:

    openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -nodes -days 365
  

  Here's a breakdown of what each part of the command does:

  • openssl req: This initiates a certificate signing request, which is the first step in creating a new certificate.

  • -x509: This option tells OpenSSL to create a self-signed certificate instead of a certificate request.

  • -newkey rsa:2048: This generates a new RSA key pair with a key size of 2048 bits, ensuring strong encryption.

  • -keyout key.pem: This specifies the file where the private key will be saved. In this case, it will be saved as key.pem.

  • -out cert.pem: This specifies the file where the certificate will be saved. It will be saved as cert.pem.

  • -nodes: This option indicates that the private key should not be encrypted with a passphrase. This is useful for automated processes where entering a passphrase would be impractical.

  • -days 365: This option sets the validity period of the certificate to 365 days, meaning it will be valid for one year from the date of creation.

After running this command, you will be prompted to enter some information, such as your country, state, organization name, and email address. This information will be included in the certificate. Once completed, you will have a key.pem file containing your private key and a cert.pem file containing your self-signed certificate.

Finally, it looks something like this:

Once you're finished, scroll down to SAML for Internal and Workspace Applications: Identity Provider Attributes.

• Enter the Issuer attribute from the identity provider's metadata, which is the Microsoft Entra Identifier.

• Paste the Base64 Certificate content from the identity provider's metadata.

• Enter the identity provider's sign in URL, which is the Login URL.

Finally, it ends up looking something like this:

To save your changes, just click Apply Changes.

Configure the SAML Sign-In Authentication for your APEX App

Now that we have successfully set up SAML for our instance, using it for authentication in an APEX app is super easy! With the SAML configuration in place, integrating it into your APEX application is much simpler than you might expect. Unlike Social Sign-In, where you might have had to create Web Credentials or follow multiple steps, SAML streamlines the process significantly. To enable SAML authentication in your APEX app, you simply need to select SAML as your current authentication method from the available options.

So, log in to the APEX Builder, click the App Builder icon, and choose the application where you want to use SAML for authentication. Then, click Shared Components, find the Security section, and click on the Authentication Schemes link.

On the Authentication Schemes page, click Create. Keep the option Based on a pre-configured scheme from the gallery selected, and then click Next.

Give it a unique name, like SAML Sign-In, and choose the Scheme-Type SAML Sign In. Under Settings, make sure that Use SAML Attributes of is set to Instance. Finally, click Create Authentication Scheme.

The last step is to click on the Authentication Scheme and set it as the current scheme.

And that's it! By following these steps, you have successfully set up SAML authentication for your APEX application.

The final Test

To make sure everything's working fine, just run the application. You should see the Microsoft Entra-ID Login Dialog pop up. This means your SAML authentication setup is good to go! If you see this login prompt, it shows that the integration with the identity provider is successful, letting users sign in with their Microsoft Entra-ID credentials. In case the dialog does not appear, it may be necessary to revisit the configuration steps to ensure that all settings have been accurately applied. Make sure the Issuer attribute, Base64 Certificate, and Login URL match the identity provider's details. Once you've confirmed everything, try running the application again to see if the login dialog appears.

Choose the account you want to use, or simply enter your username/email and password, then click the Sign-In button to log in to your APEX App and here we go 🚀

Conclusion

In conclusion, setting up Single Sign-On (SSO) for Oracle APEX using Entra-ID and SAML on Oracle Autonomous Database boosts security and makes things easier for users by letting them access multiple services with just one login. This guide has taken you through all the steps, from setting up a Customer-Managed ORDS environment to configuring Entra-ID and Oracle APEX for SAML authentication. By following these steps, organizations can make their authentication processes smoother, cut down on password overload, and enhance security overall. Integrating SAML with Oracle APEX not only makes user management simpler but also keeps up with modern identity management practices, ensuring a strong and efficient way to handle authentication.

References

• Hyand Knowledgebase

• SAML Sign-In

• SAML authentication with Microsoft Entra ID