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:
- The newly-generated Login page has a new checkbox page item named
P9999_PERSISTENT_AUTHwith a server-side condition to show the checkbox only when the
persistent_auth_enabledfunction in the
apex_authenticationpackage returns true.
- The new page’s
Loginprocess passes the value of this new
P9999_PERSISTENT_AUTHcheckbox to a new
p_set_persistent_authparameter of the
login()procedure in the
P9999_REMEMBERcheckbox has a new server-side condition to only render if the
persistent_auth_enabledfunction 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 =
- Label = Remember me
- Server-side Condition Type = Expression
- Server-side Condition =
- Maintain Session State = Per Session (Disk)
- Name =
- Added the additional argument to the existing
Loginprocess, referencing the value of this new page item:
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_REMEMBERcheckbox 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
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.