How to configure Active Directory authentication in Oracle APEX

Dominik Haczek

14 wrz 2024 • 8 min read

Oracle Application Express (APEX) is a powerful, web-based application development platform that allows developers to build scalable and secure applications with minimal coding. One of the key aspects of any application is authentication, and integrating Active Directory (AD) for authentication can provide a seamless and secure login experience for users. In this article, we will walk through the steps to configure Active Directory authentication in Oracle APEX.

Prerequisites

Before we begin, ensure you have the following:

An Oracle APEX instance installed and running.
Access to the Oracle APEX workspace for configuring when you want to set up AD authentication for an app; access to the APEX instance administration for configuring AD authentication for the workspace.
Active Directory details (obtain these from your AD admin):
1. Domain controller host and port
2. If SSL for LDAP is enabled, you will need the root certificate
3. Domain name and information on constructing the Distinguished Name (DN) string

Step-by-Step Guide for configuring AD authentication for an App

Login to your workspace.
Navigate to the Application Builder, select your app, then go to Shared Components. From there, navigate to Authentication Schemes and click Create.

Select "Based on a pre-configured scheme from the gallery".

Select LDAP Directory as the Scheme Type. Then, provide your Host, Port, and Distinguished Name (DN) String. If you're unsure what to enter as DN String, feel free to type anything for now, as this is a required field to save. We will discuss how to construct the DN String shortly.

⚠️

Do not use the Test LDAP Login button at this stage. I noticed that sometimes it does not function correctly if the authentication scheme has not been created yet or if changes made to an existing authentication scheme are not saved.

After creating the Authentication Scheme, you will notice that more options appear. It's beneficial to proceed with the configuration now that you have this visibility.

Now we can discuss the parameters you need to enter to make it work:
1. Name is an arbitrary identifier for your authentication scheme. It also serves as a static identifier since there is no separate field for it, unlike in some other modules in Oracle APEX.
2. Scheme Type: select LDAP Directory.
3. Host: The hostname of your Active Directory's Domain Controller.
4. Port: The port of your Active Directory's Domain Controller. The default is 389.
5. Distinguished Name (DN) String: And here's where the party starts. It will depend on the username you choose to authenticate your users. First, investigate your Active Directory to identify a pattern for the users. The possible options are described below.
6. Use Exact Distinguished Name (DN): In our scenario, we will use the exact DN, so we will leave Yes there.

That's it for now. We can leave the remaining options at their default settings. Let's discuss the possible options for DN String.

Display Name

To authenticate using the Display Name (also known as Name) attribute from Active Directory (AD), you must specify the DN string, as shown in the following example:

CN=Karen Berge,CN=admin,DC=corp,DC=Fabrikam,DC=COM

where:

CN: Short for "Common Name", this attribute specifies the name of an object in the directory. In this case, there are two CNs:

CN=Karen Berge: This is the name of a user or a person in the directory.
CN=admin: This suggests that Karen Berge is a member of the "admin" group or has an administrative role.

DC: Short for "Domain Component", this attribute specifies the domain or the organization. In this case, there are three DCs:

DC=corp: This is a subdomain or a department within the organization (e.g., "corp" for corporate).
DC=Fabrikam: This is the main domain or organization name (Fabrikam is a fictional company name often used in examples).
DC=COM: This is the top-level domain (TLD) indicating that Fabrikam is a commercial organization.

You can read more about how to construct a DN right here:

In our case, we will use this DN string:

CN=%LDAP_USER%,CN=Users,DC=dhho,DC=local

where:

%LDAP_USER% is a placeholder that will be replaced by the actual username or user identifier entered in the Username field on the login page.
CN=Users: This indicates that the entry is within the Users container.
DC=dhho is the first part of the domain name.
DC=local is the second part of the domain name, indicating that the domain is dhho.local.

Putting it all together, this DN specifies an entry for a user within the Users container of the dhho.local domain. When %LDAP_USER% is replaced with an actual username, it will pinpoint the exact LDAP entry for that user. For example, if %LDAP_USER% were replaced with jn, the DN would become CN=jn,CN=Users,DC=dhho,DC=local.

When you construct your DN string and input it into your application, remember to click Apply Changes. Then, enter the Authentication Scheme again and click Test LDAP Login.

Enter the Credentials for Test Login which is your AD user Display Name and password. Then click Test Login.

💡

If you receive a network error, you may need to add host and port to ACL. Please see the snippet below.

BEGIN
    DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
        host => '192.168.10.51',
        lower_port => 389,
        upper_port => 389,
        ace => xs$ace_type(
            privilege_list => xs$name_list('connect'),
            principal_name => APEX_APPLICATION.g_flow_schema_owner,
            principal_type => xs_acl.ptype_db
        )
    );
END;
/

For networking problems, you can consult the documentation below as well:

Installation Guide

Database administrators must enable network services in Oracle Database to send outbound mail, invoke web services, or use template-based PDF report printing with external print servers in Oracle APEX.

Oracle Help Center

After receiving the Authenticated message, you know it works. Now you can set the AD Auth as the current scheme.

Try it on the app's actual login screen to see if it works.

SamAccountName

In Active Directory, the Common Name (CN) attribute is not typically used as the username. Instead, the sAMAccountName or userPrincipalName attributes are more commonly used. The sAMAccountName attribute is the default username attribute. It's the username that users enter to log in to the domain and Windows PC. If you want your users to log in with their sAMAccountName instead of their display name, which makes much more sense, you should construct following DN string:

DOMAIN\%LDAP_USER%

in my case, it will be:

DHHO\%LDAP_USER%

How do I know the domain? The easiest way to find out what the domain part should be is to locate the user in the AD and check their Account tab.

Now, the test:

💡

You can omit the DOMAIN\ part in your DN string. In that case, the user will need to provide the domain as part of their username.

UserPrincipalName

The userPrincipalName (UPN) attribute is another important attribute in Active Directory. It's a unique identifier for a user in the format of username@FQDN. The UPN is often used as the username for logging in to the domain, especially in modern Windows environments. UserPrincipalName resembles an email format, so you may want to use this method for providing a username during authentication. The pattern for that is:

%LDAP_USER%@FQDN

where FQDN stands for Fully Qualified Domain Name. It includes all Domain Components (DCs) in correct order, separated by dots (.).

So, in my case, it will be:

%LDAP_USER%@dhho.local

So now is the time for the test:

💡

Again, you can omit the @FQDN part in your DN string. In that case, the user will need to provide the FQDN as part of their username.

Let's see how it works without the FQDN part. So the DN string in the Authentication scheme will be

%LDAP_USER%

Let's see how it works:

Troubleshooting Distinguished Name string

There’s a lot to understand regarding the three ways to provide a simple username. Let’s say not everything went as smoothly as I demonstrated. There’s a useful PowerShell command for an AD administrator to explore the available options and see the mentioned attributes for a particular user.

 Get-ADUser -Identity <USERNAME>

Step-by-Step Guide for configuring AD authentication for a Workspace

Now, that we are armed with the knowledge we've got after configuring AD login for the application, this should be easy when it comes to Workspace.

Go to Manage Instance, then navigate to Security and select Authentication Control. Click the edit button (the button with the pencil icon) next to the LDAP Directory.

I believe you already know what to enter in the form fields, so I'll skip the description and provide you with a picture of the completed form.

💡

Before you proceed, make sure that the user you want to have access to the workspace in question is registered as a developer in the APEX workspace with exactly the same username (substituted for %LDAP_USER%) as in Active Directory. Otherwise, the user will not be able to log into the workspace. Take a look at the screenshot below. In addition, to access Instance Administration, you need a user with exactly the same name in Active Directory (AD) as with Instance Administration access. Here, the same rules apply as for regular workspace. In my case, this means I need an ADMIN user in AD, which can be a problem for the organization. But I can also add my JN user as an instance administrator.

Click Apply Changes. Then, enter the authentication scheme again and hit Make Current Scheme.

⚠️

If you make a mistake in the configuration, you will be locked out of your workspaces and instance administration. To revert to APEX authentication, run the following code in your database using a user with the APEX_ADMINISTRATOR_ROLE role.

begin
  apex_instance_admin.set_parameter('APEX_BUILDER_AUTHENTICATION','APEX');
  commit;
end;
/

So! Let's test it out.

Summary

Configuring Active Directory authentication in Oracle APEX can significantly enhance the security and user experience of your applications. By following the steps outlined in this article, you can seamlessly integrate AD authentication, providing a single sign-on experience for your users. If you encounter any issues, refer to the Oracle APEX documentation or consult with your AD administrator for further assistance.

Happy coding!

PS. In the next post, I will explain how to connect APEX to Entra ID (formerly Azure Active Directory). The process is completely different!