Introduction
Setting up custom authentication in Oracle APEX gives you complete control over how users are validated before gaining access to your application. This is especially useful when you need to integrate with an external user database, apply specific business rules, or support alternative login mechanisms like tokens, APIs, or multi-step verification. By replacing the default authentication logic with your own PL/SQL procedures or external service calls, you can design a secure and flexible authentication system tailored to your exact needs.
Setting up custom authentication in Oracle APEX allows you to define your own logic for validating users instead of using built-in methods like APEX accounts or LDAP. This approach is useful when you have a custom user table, need to integrate with external services, or want full control over login behavior. The process involves creating a custom authentication scheme, building PL/SQL logic for validation, and configuring your login page to work with that logic.
Start by navigating to Shared Components > Authentication Schemes. Click Create and select From Scratch. Choose Custom as the scheme type and give it a meaningful name, such as “Custom Login Handler.” Set this scheme as current so your application will use it.
Within the authentication scheme settings, scroll to the section labeled PL/SQL Function Returning Boolean. This function is responsible for deciding if the credentials entered by the user are valid. You will write or reference a PL/SQL function here. For example:
return auth_pkg.validate_user(:USERNAME, :PASSWORD);
Now create the package auth_pkg in your database with the following logic:
CREATE OR REPLACE PACKAGE BODY auth_pkg AS
FUNCTION validate_user(p_username IN VARCHAR2, p_password IN VARCHAR2) RETURN BOOLEAN IS
v_hash VARCHAR2(4000);
v_valid BOOLEAN := FALSE;
BEGIN
SELECT password_hash INTO v_hash
FROM app_users
WHERE username = UPPER(p_username);
IF v_hash = custom_hash(p_password) THEN
APEX_UTIL.SET_AUTHENTICATION_RESULT(0);
v_valid := TRUE;
ELSE
APEX_UTIL.SET_AUTHENTICATION_RESULT(1);
END IF;
RETURN v_valid;
EXCEPTION
WHEN NO_DATA_FOUND THEN
APEX_UTIL.SET_AUTHENTICATION_RESULT(1);
RETURN FALSE;
END;
FUNCTION custom_hash(p_text IN VARCHAR2) RETURN VARCHAR2 IS
BEGIN
RETURN DBMS_CRYPTO.HASH(UTL_I18N.STRING_TO_RAW(p_text, 'AL32UTF8'), DBMS_CRYPTO.HASH_SH256);
END;
END auth_pkg;
The function checks if the password entered matches the stored hash for the given user. You can replace this logic with anything appropriate for your system, including API calls or third-party integrations.
Next, modify your login page to use custom items for username and password, such as P101_USERNAME and P101_PASSWORD. Add a login button and create a process on submit with this PL/SQL code:
BEGIN
IF auth_pkg.validate_user(:P101_USERNAME, :P101_PASSWORD) THEN
APEX_AUTHENTICATION.POST_LOGIN(:P101_USERNAME);
ELSE
APEX_ERROR.ADD_ERROR(
p_message => 'Invalid login. Please try again.',
p_display_location => apex_error.c_inline_in_notification);
END IF;
END;
This will authenticate the user and start the session if credentials are correct. Make sure the page process runs Before Header, and that session state is correctly submitted for the username and password items.
In the authentication scheme, configure the Post-Logout URL to redirect to your login page. You can also customize session timeout behavior and whether users should be re-authenticated after timeout.
Setting up custom authentication also allows for additional enhancements. You can log failed login attempts, block accounts after multiple failures, or implement multi-factor authentication. You can also use the custom logic to assign roles or load additional user context into APEX session state.
With custom authentication, Oracle APEX gives you the flexibility to match your application’s security needs exactly. The APEX framework provides the necessary APIs and integration points so your authentication logic works seamlessly with APEX sessions, page authorization, and user access control.
Additional Info
Learn how to configure a custom authentication scheme in Oracle APEX.
Setting Up Custom Authentication
Learn how to configure a Custom Authentication Scheme in Oracle APEX.
Steps to Create a Custom Authentication Scheme:
Navigate to the Authentication Schemes Page
On the Workspace home page, click App Builder.
Select your application.
On the Application home page, click Shared Components.
The Shared Components page appears.
Create a New Authentication Scheme
Under Security, click Authentication Schemes.
On the Authentication Schemes page, click Create.
Select the Authentication Type
Choose "Based on a pre-configured scheme from the gallery" and click Next.
Configure Authentication Details
Name: Enter a descriptive name for the authentication scheme.
Scheme Type: Select Custom.
Define Custom Authentication Logic
Fill in the appropriate fields.
For details about each field, refer to the field-level Help.
Save the Authentication Scheme
Click Create Authentication Scheme to apply your changes.
Your custom authentication scheme is now set up and ready to be configured for login validation.
Conclusion
Custom authentication in Oracle APEX is a powerful feature that allows you to move beyond standard login processes and design a solution that fits your application’s unique security requirements. Whether you’re validating users against a custom table, connecting to a third-party system, or implementing advanced login flows, the APEX platform provides the tools and flexibility to build secure, maintainable, and highly configurable authentication solutions.
