Enabling Persistent Auth in an Existing APEX App

Overview

A new APEX 22.1 feature I’ve been eagerly waiting to use in my production APEX apps is persistent authentication. It will allow my users to avoid having to login again every time they open my app in their phone or browser. After enabling the feature at the instance level, I needed to slightly adjust my existing application’s login page to take advantage of this new capability. This article explains how I figured out the minimal changes needed to update my existing APEX application to use this new sought-after “Remember me” functionality.

Enabling Persistent Auth at Instance Level

Persistent authentication is controlled by an instance-level security option that is disabled by default, so I needed to enable it for my APEX instance. After logging in to APEX’s administration services, I chose Manage Instance > Security and set Allow Persistent Auth to Yes. The default 30-day lifetime met my application’s needs, but to change it you can adjust the value of the Persistent Authentication Lifetime Days property. This is the number of days that the persistent authentication will last before the user needs to enter their password again.

Using YAML Export with SQLcl to Diff Existing and New Login Pages

An existing application’s login page needs a few minor changes to offer the “Remember me” feature. In contrast, when creating a new application in APEX 22.1, ticking the Install Progressive Web App checkbox in the Features section of the Create Application wizard will generate a login page that supports it. I took advantage of this fact to create a new application called Temp App to compare its Login page 9999 with my existing application’s Login page 9999 to determine the minimum adjustments needed.

The easiest way to compare APEX artifacts in 22.1 is using the new readable YAML export format. SQLcl 22.1 supports the new READABLE_YAML value for the -expType option of its apex export command, so I ran the following commands to export my existing (103) and new Temp App (102) applications in readable YAML format so I could compare the two page 9999 Login pages’ metadata:

$ sql workspace_schema_username/password@host:port/service
sql> apex export -applicationId 103 -dir f103 -expType READABLE_YAML
sql> apex export -applicationId 102 -dir f102 -expType READABLE_YAML

Using Visual Code to compare the two application’s p09999.yaml files, I noticed the following three interesting differences:

1. The newly-generated Login page has a new checkbox page item named P9999_PERSISTENT_AUTH with a server-side condition to show the checkbox only when the persistent_auth_enabled function in the apex_authentication package returns true.

• The new page’s Login process passes the value of this new P9999_PERSISTENT_AUTH checkbox to a new p_set_persistent_auth parameter of the login() procedure in the apex_authentication package:

• The P9999_REMEMBER checkbox has a new server-side condition to only render if the persistent_auth_enabled function returns false.

The value of the persistent_auth_enabled function corresponds to the instance level security setting I enabled above, so these three differences result in having the login dialog behave the same as before if the instance-level persistent authentication setting is disabled, and to show the new “Remember me” checkbox if the persistent authentication instance-level setting is enabled.

Adjusting the Existing Login Page

After identifying the three important changes to make above, I edited my existing application’s Login page to do the following:

• Added a new checkbox page item with:
  • Name = P9999_PERSISTENT_AUTH
  • Label = Remember me
  • Server-side Condition Type = Expression
  • Server-side Condition = apex_authentication.persistent_auth_enabled
  • Maintain Session State = Per Session (Disk)
• Added the additional argument to the existing Login process, referencing the value of this new page item:

apex_authentication.login(
p_username => :P9999_USERNAME,
p_password => :P9999_PASSWORD,
p_set_persistent_auth => nvl(:P9999_PERSISTENT_AUTH,'N')='Y');

• Adjusted the server-side condition of the existing P9999_REMEMBER checkbox to be:
  • apex_authentication.persistent_cookies_enabled and not apex_authentication.persistent_auth_enabled

With these changes in place, the persistent authentication feature started working as expected in my existing application. However, while studying the differences between the login pages, I noticed one additional interesting change:

The method used to express the login page’s icon changed from using an icon property to instead use a file-url. This is due to another new feature in APEX 22.1 related to simplifying how an application’s icon can be configured at any time using a built-in or custom icon image.

Reflecting New App Icon in the Login Page

My application was still using the original default icon that got set by the APEX Builder when I first created the application. At the time, I took the default icon because I figured I’d be able to easily set the icon later. However, before 22.1 changing an application’s icon after creation was not obvious. Now in 22.1, doing so is very simple. To flex this additional newfound icon power, I visited my application’s Shared Components > User Interface Attributes settings page and clicked on the Change Icon button to set a new custom Vincent van Gogh icon.

Then, following the observation I noticed above, I copied the Reference path #APP_FILES#icons/app-icon-512.png of the “Large icon” version of the application icon image to the clipboard so I could paste it into the file-url property of the Login page’s static region, and then clicked on Apply Changes to make my new icon change permanent.

Returning to my Login page, I selected the static content region and removed the existing “app-icon” value in the Icon property, and set the value of the File URL property to #APP_FILES#icons/app-icon-512.png

With these changes, my application’s login page was now not only more beautiful but also more functional, and my end users don’t need to login every time anymore.