Dynamically Switch Authentication in Oracle APEX Using the Configuration Procedure

Oracle APEX PL/SQL Authentication

One app. Two servers. Zero hardcoded auth logic.

Dasshini Ravi  ·  April 16, 2026

The Authentication Configuration Procedure is the most underused feature in Oracle APEX. Here's how to use it to run one codebase across environments with completely different auth schemes — automatically.

I once maintained two copies of the same APEX application — one for testing with custom PL/SQL auth, one for production with LDAP. Every bug fix, every UI tweak, every feature had to be applied twice. It was the kind of thing you accept as normal until someone shows you there's a better way.

The better way is the Authentication Configuration Procedure — a PL/SQL hook that fires before the user even sees the login page, letting you switch auth schemes at runtime based on any data you want. No manual switching. No duplicate apps.

---

What actually happens at session start

When a new APEX session begins, before the login page renders, APEX looks for a registered configuration procedure and calls it. You receive a record of type apex_authentication.t_configuration passed in and out by reference. Whatever you write into that record becomes the session's auth configuration.

The procedure signature is fixed — you cannot change it:

procedure my_auth_config (
  p_conf IN OUT NOCOPY apex_authentication.t_configuration
)

Three attributes on that record do the work:

→

authentication_name — switches the active auth scheme by name

→

tenant_id — stamps a tenant identity on the session for row-level isolation

→

substitutions — injects values into OAuth token placeholders

All three are optional. In most cases you'll only need the first two.

The problem, made concrete

Testing server

test-server.company.com:1234

Custom PL/SQL auth

Tenant: TENANT_TEST

Production server

prod-server.company.com:4321

LDAP / Active Directory

Tenant: TENANT_PROD

Same application export. Different behavior — driven entirely by the hostname the request arrives on. The configuration procedure reads the runtime hostname and picks the right scheme from a table. All the logic is in data, not code.

Implementation

• 1

  Create the config table

  One row per server. The procedure queries this at runtime. Keep it simple — hostname, tenant code, and the exact auth scheme name as it appears in APEX.

  CREATE TABLE app_tenants (
    hostname    VARCHAR2(200) PRIMARY KEY,
    tenant_code VARCHAR2(50)  NOT NULL,
    auth_scheme VARCHAR2(100) NOT NULL
  );
  
  -- Testing server row
  INSERT INTO app_tenants VALUES (
    'test-server.company.com:1234',
    'TENANT_TEST',
    'Custom Auth'
  );
  
  -- Production server row
  INSERT INTO app_tenants VALUES (
    'prod-server.company.com:4321',
    'TENANT_PROD',
    'LDAP Auth'
  );

  ⚠ The auth_scheme value must match the Name field in Shared Components exactly — including capitalization. A mismatch silently falls through to the default scheme with no error raised.
• 2

  Create the procedure

  Deploy identical code on both servers. The different behavior comes entirely from the table, not the procedure itself.

  CREATE OR REPLACE PROCEDURE my_auth_config (
    p_conf IN OUT NOCOPY apex_authentication.t_configuration
  )
  IS
    l_host        VARCHAR2(200);
    l_auth_scheme VARCHAR2(100);
    l_tenant_id   VARCHAR2(100);
  BEGIN
    -- Read hostname from the HTTP request
    l_host := sys.owa_util.get_cgi_env('HTTP_HOST');
  
    -- Look up auth scheme and tenant for this server
    SELECT auth_scheme, tenant_code
      INTO l_auth_scheme, l_tenant_id
      FROM app_tenants
     WHERE LOWER(hostname) = LOWER(l_host);
  
    -- Switch the auth scheme at runtime
    p_conf.authentication_name := l_auth_scheme;
    p_conf.tenant_id            := l_tenant_id;
  
    apex_debug.info(
      'Auth config: host=%s scheme=%s tenant=%s',
      l_host, l_auth_scheme, l_tenant_id
    );
  
  EXCEPTION
    WHEN NO_DATA_FOUND THEN
      apex_debug.error('No config found for host: %s', l_host);
  END my_auth_config;

  That single assignment — p_conf.authentication_name := l_auth_scheme — is the entire switch. Everything else is lookup and logging.
• 3

  Register in Security Attributes

  Navigate to Shared Components → Security Attributes → Authentication Configuration Procedure. Enter my_auth_config and click Apply Changes. APEX will invoke your procedure on every new session from this point forward.

  [ Screenshot: Security Attributes page — "Authentication Configuration Procedure" field highlighted ]

---

Five things that will burn you if you skip them

1

Enable "Switch in Session" on every target scheme. Without this checkbox, the switch is silently ignored. This is the single most common reason the feature appears to do nothing.

2

Always use LOWER() on both sides of the hostname comparison. Some servers return mixed-case values — Test-Server instead of test-server — and the lookup quietly fails.

3

URL-based scheme switching stops working once you register a config procedure. The APEX_AUTHENTICATION=xxx URL parameter is intentionally disabled — this is a security feature, not a bug.

4

The procedure must be deterministic. APEX may call it more than once per session. Always return the same values for the same hostname — no randomness, no side effects.

5

Grant execute explicitly. The APEX parsing schema must have execute privilege on the procedure, or it fails silently at session start with no useful error.

✅ Pro tip: Add the apex_debug.info() call inside the procedure before anything goes to production. Enable View Debug in the developer toolbar and confirm the procedure fires and resolves the correct scheme. It takes ten seconds and will save you an hour of head-scratching.

What you end up with

One application export. One codebase. Deploy it to as many servers as you need — each one reads its own row from the config table and gets the right authentication scheme, the right tenant identity, and no manual intervention required.

Once you build this once, hardcoding auth schemes in APEX becomes genuinely unthinkable. The Authentication Configuration Procedure is one of those features that pays back its setup cost on the very first deployment.