Before users can access APEX applications, they have to log in. This is typically done by providing a user name and corresponding password. If the credentials match, then a user becomes authenticated and can proceed to use the application. If not, then the user will be prompted to try again. Too many invalid attempts, and the account may become disabled, requiring an administrator to intervene.
The mapping of a user repository to an APEX application is called an authentication scheme. Each application can have multiple authentication schemes embedded within it, but only one can be set as the current authentication scheme or the one that APEX will actually use when running the application.
Caution APEX is not an identity management solution and should never, ever be used as one. User credentials for all APEX applications should be stored in a centrally managed repository, such as an LDAP server. This way, as users are hired and fired, all of their access to any systems are immediately also activated or revoked by the administrator.
Since no two organizations are alike—or since, in many cases, no two departments within any single organization are alike—APEX provides a wide range of authentication options. Each option has its own settings that can be altered to meet the specific needs of the user repository. If one of the prebuilt authentication schemes still won’t cut it, there is a Custom authentication scheme that can be configured to do virtually anything.
This chapter will start by reviewing the different types of authentication schemes. It will then cover attributes that are specific to all types of authentication scheme. Since the type of authentication scheme does not change how APEX manages sessions, that process is identical no matter which scheme is used. The last part of this chapter will cover both the login and logout events in APEX in detail.
Types of Authentication Schemes
In most cases, organizations do not want to create another set of credentials for use with APEX—or any other technology, for that matter. A good identity management strategy has its core a centralized user repository for use across the entire enterprise. APEX subscribes to this strategy in that it is extensible enough to be integrated with virtually any type of user repository. This ensures that all credentials are managed outside of APEX yet allows developers to easily integrated with it for both authentication and authorization.
Out of the box, APEX provides a number of preconfigured authentication schemes. Some of these will work right out of the box, while others may take a little bit of configuration. When none of the preconfigured authentication schemes meets your business needs, the Custom scheme should be used. This scheme is extensible enough that virtually any external repository can be integrated with APEX.
When creating a new scheme in an application, that scheme will automatically become the current scheme. It is possible to later change which scheme is the current scheme. Simply edit the scheme that should be the current one, and click Make Current Scheme, as shown in Figure 8-1.
Figure 8-1 . Setting the current authentication scheme
Application Express Users
As described in Chapter 5, APEX contains its own internal repository of users. These users are specific and unique to a workspace and can be managed by either the workspace or instance administrator. APEX manages these credentials internally, and they are subject to the password complexity, longevity, and login attempt rules as defined at the workspace level.
On the surface, using APEX users seems like an attractive option, since there is zero work required to do so. The table and associated methods in which to manage the users are already created and integrated into their own API set as well as available in the application development environment. However, most organizations do not use APEX users for production applications, simply because it is another user repository that would have to be updated and maintained alongside others. Furthermore, APEX users’ restriction to a single workspace presents problems for an organization that uses applications across multiple workspaces.
For training exercises or even small, simple applications, using the Application Express Accounts scheme is acceptable. Be cautious when using this scheme for small applications, though, because small applications tend to grow into larger ones, and if Application Express Accounts are still being used, there could be potential issues with managing the access to those applications.
Enabling the Application Express Accounts scheme is quite simple. Typically, it is installed and set as the default scheme when creating a new application. If for any reason it needs to be re-added to an application, there is nothing at all to configure. Simply create a new authentication scheme or select one based on a preconfigured scheme from the gallery, and set the scheme type to Application Express Accounts.
Database Accounts
As its name implies, the Database Accounts authentication scheme will use database schema user names and passwords when authenticating to an APEX application. Like with APEX users, no additional settings need to be configured; simply add the Database Accounts scheme to your application, ensure that it is set as the current scheme, and that’s it.
The Database Accounts authentication scheme can be used when migrating an application from Oracle Forms because the end users in many Oracle Forms applications are database schemas. In this case, it is best that a migration strategy be put in place to move the end users to a more centralized repository, such as an LDAP server. Using Database Accounts will suffice for the short term, but most organizations are reluctant to give end users access to database schemas.
HTTP Header Variable
The HTTP Header Variableauthentication scheme allows APEX to use a value in the HTTP header for the currently authenticated user. This type of authentication is typically used in conjunction with a single sign-on server that sets an HTTP header variable to the value of the currently authenticated user.
When configuring this authentication scheme, a few additional options also need to be set, as outlined in Figure 8-2.
Figure 8-2 . Settings for the HTTP Header Variable authentication scheme
When using HTTP headers, it is useful to be able to see a list of all the currently set variables for a session. This can be achieved by adding a PL/SQL region to the page that contains the following snippet: owa_util.print_cgi_env;. This will render a region that contains all HTTP header variables and their current settings, as illustrated in Figure 8-3.
Figure 8-3 . The result of calling owa_util.print_cgi_env
Be sure to disable or, better yet, delete this region before deploying your application to production because the information displayed here can prove very useful for a malicious user.
LDAP Directory
Lightweight Directory Access Protocol (LDAP) is what most organizations have standardized on for a centrally managed user repository. All account management and options—such as password strength and reuse—are managed by the LDAP server, not by APEX. This provides a solid approach with regard to identity management because all credentials are in a single, centrally managed place.
By using an LDAP directory for authentication in an APEX application, the task of user management can be safely delegated to the designated people who manage the LDAP server. This way, when a user is either hired or fired from the organization, it is done centrally and will be respected by any application that uses LDAP credentials. Another benefit of using LDAP is that the specific LDAP vendor should not matter much. The LDAP Directory authentication scheme has been proven to work with almost any LDAP server, such as Oracle Internet Directory, Active Directory, and OpenLDAP, to name a few.
Depending on your LDAP server’s configuration, additional options will have to be supplied to the LDAP authentication scheme by way of the Settings region, as shown in Figure 8-4.
Figure 8-4 . The settings for the LDAP Directory authentication scheme
Despite these attributes, there are scenarios with some LDAP servers that require more functionality than can be declaratively defined. When that is the case, the Custom authentication scheme can be used, and the logic can be handled in a PL/SQL function that uses the DBMS_LDAP APIs.
No Authentication (Using DAD)
The No Authentication schemewill reuse whatever database user is defined in the database access descriptor (DAD). By default, the DAD for APEX will be set to use the user APEX_PUBLIC_USER for all connections. Thus, using this authentication method with a DAD that already contains a predefined user name and password is not very practical.
If no user name and password are defined in the DAD, then the user will be prompted to enter a valid set of database schema credentials. APEX will then use basic authentication to set the user to whatever the end user provided, if the credentials are valid. In other words, it will behave almost identically to how the Database Accounts authentication scheme does.
Open Door Credentials
The Open Door Credentials scheme has a unique purpose: to allow a developer to become any user by simply entering the user name. This authentication scheme was designed to simplify testing an application as different users without their respective credentials. Clearly, it has no place in a production environment but can prove quite useful during development.
Oracle Application Server Single Sign-On
When using the Oracle Application Server Single Sign-On (OASSSO) authentication scheme, there are a few extra steps that are required before this scheme will work. Either your specific application or APEX itself will need to be registered as a partner application with the OASSSO server. You can find specific details on how to configure APEX and OASSSO in Oracle Support Note #562807.1. According to the note, it has been tested with versions 2.0 through 4.1.1 of APEX and versions 9.0.4.2 through 10.1.2.x of Oracle Application Server.
OASSSO delegates all credential verification to the OASSSO server. This means that any application that uses this authentication scheme will not use the APEX login page but rather redirect and use the OASSSO login page. Upon successful authentication, the user will be redirected to the APEX application’s home page and can use the application without any other special considerations.
Custom
The Custom authentication schemeis the most versatile of the group because it can be tailored to meet almost any specific business rule or user repository. It is often used when the preconfigured authentication schemes fall short of being able to properly integrate with an existing user repository. In some cases, the Custom scheme is used to store user credentials in a database table, often for applications on the public Internet or where no centralized user repository is available.
The Custom authentication scheme contains a few attributes that are unique to it, as shown in Figure 8-5. Not all of these attributes are required for a Custom authentication scheme to work properly. In fact, many implementations of the Custom authentication scheme provide only an authentication function and nothing else.
Figure 8-5 . Settings specific to the Custom authentication scheme
The Custom authentication function’s premise is simple: return either TRUE or FALSE, based on whether the user successfully authenticated. The only restriction for the custom authentication function is that it must return a Boolean and contain exactly two input parameters: p_username and p_password.
When referring to the custom function, only the name of the function needs to be entered in the Authentication Function Name attribute. APEX will automatically use the user name and password items from the login page to pass the corresponding values to the custom function.
The sentry function is similar to the authentication function in that it also returns a Boolean, but that’s where the similarities end. The purpose of the sentry function is to ensure that a user’s session is still valid. It will be called before every page view and asynchronous transaction in an application. If a FALSE is returned, then APEX will kill the session and run the invalid session procedure, also specified here. It will then redirect to the location specified in the Session Not Valid section of the authentication scheme. A TRUE returned to the sentry function will mean business as usual, and the application will continue to function as intended.
If no function is specified for the sentry function, APEX will simply revert to its own built-in session management engine to determine whether a session is valid. If a custom sentry function is specified, then great care must be taken to ensure that it works properly and cannot be easily compromised or hacked. In most cases, leaving this field blank and relying on the internal APEX session management is sufficient.
The Invalid Session Procedure will execute when APEX detects an invalid session. This procedure can perform any task, such as logging the event or notifying an administrator. Lastly, the Post Logout Procedure will execute after a user logs out of an application. It will get called only if the user explicitly logs out by clicking the Logout link in the navigation bar. Simply closing or quitting the browser will not trigger this event from firing.
There is one more option that allows the user to enable legacy authentication values. When legacy authentication values are enabled, an additional group of attributes will appear, as shown in Figure 8-6.
Figure 8-6 . The Legacy Attributes section of a Custom authentication scheme
These attributes are included for backward compatibility with authentication schemes that were created in APEX 4.0 and previous versions. Starting with APEX 4.1, all authentication schemes were migrated so that they could fit into APEX’s plug-in architecture. As a result, many of the options that were embedded with each type of scheme are now available only with schemes where they make sense. For example, options that have to do with LDAP are exposed only when using the LDAP authentication scheme.
Since all of these options used to be available to any type of scheme, the Enable Legacy Authentication Attributes option allows a developer to view them, if needed. At some point, it is best to create a new authentication scheme and migrate any settings there.
APIs for Custom Authentication
When using a custom authentication scheme, a few APIs will come in handy. They are, alphabetical order, as follows:
- APEX_AUTHENTICATION
- APEX_CUSTOM_AUTH
- APEX_LDAP
- APEX_UTIL
Each of these APIs can provide a range of common functionality that will be needed for almost any Custom authentication scheme.
APEX_AUTHENTICATION
The first API—APEX_AUTHENTICATION—is designed to be used by an authentication scheme to perform common authentication actions, such as logging in and out, checking to see whether a session is valid, and getting the APEX session cookie, among other things. When a new application is created, APEX will automatically reference APEX_AUTHENTICATION as part of the login and get and set cookie processes on the login page and when logging out of an application.
The APEX_AUTHENTICATION API was introduced in APEX 4.1 to provide support for authentication schemes as plug-ins. It was not available in versions prior to 4.1. Applications that were created in APEX 4.0 or previous versions may still contain direct references to APEX_CUSTOM_AUTH instead of APEX_AUTHENTICATION. While they should continue to function normally, replacing calls to APEX_CUSTOM_AUTH with calls to APEX_AUTHENTICATION where possible should be considered but is currently not a critical task that needs to be performed.
APEX_CUSTOM_AUTH
Many of the functions and procedures in APEX_AUTHENTICATION are simply wrappers that will ultimately call APEX_CUSTOM_AUTH. One of the older APIs, APEX_CUSTOM_AUTH, can do most everything that APEX_AUTHENTICATION can do and then some. Also, many of the APIS in APEX_CUSTOM_AUTH offer more parameters than their counterparts in APEX_AUTHENTICATION. As your custom authentication scheme grows in complexity, you will find yourself making more references to APEX_CUSTOM_AUTH.
APEX_LDAP
If the built-in LDAP authentication scheme will not meet your needs, then a custom authentication scheme will have to be created. In almost all cases, the custom scheme will use the APEX_LDAP API. This API is a wrapper to the DBMS_LDAP API that is specifically designed to work in an APEX environment. Direct calls to DBMS_LDAP are still possible from a Custom authentication scheme but should be considered only when the APEX_LDAP does not have a suitable API.
APEX_LDAP provides commonly needed APIs, such as a call to verify LDAP credentials, a call to determine whether a user is a member of a specific LDAP group, and calls to get either a specific or all user attributes.
APEX_UTIL
Lastly, the APEX_UTIL API contains quite a number of procedures and functions that are typically used in conjunction with Custom authentication schemes. In addition to those procedures used for managing authentication, there are several that can be used to create, modify, and delete APEX users, too.
There are too many to describe all of them in detail, but there are a couple worth mentioning. First, there are a pair of APIs that can be used to override the maximum session length and idle time parameters defined at the application level. By calling either SET_SESSION_LIFETIME_SECONDS or SET_SESSION_MAX_IDLE_SECONDS, the value of the session duration and session idle time, respectively, can be changed. An example of this would be altering these values for a specific user as part of the post-authentication procedure.
The next API that is critical to understand is SET_AUTHENTICATION_RESULT. When called as part of a Custom authentication scheme, this API will set the authentication result in the Login Attempts report accordingly. Unfortunately, the API documentation is quite misleading because it claims that any value can be passed to this API. While technically that is true, there are specific values that will record specific events, as shown in Table 8-1.
Table 8-1. Codes and their corresponding authentication results for the SET_AUTHENTICATION_RESULT API
| Code | Authentication Result |
|---|---|
| 0 | Normal, Successful Authentication |
| 1 | Unknown User Name |
| 2 | Account Locked |
| 3 | Account Expired |
| 4 | Incorrect Password |
| 5 | Password First Use |
| 6 | Maximum Login Attempts Exceeded |
| 7 | Unknown Internal Error |
It is critical when using a Custom authentication scheme to call SET_AUTHENTICATION_RESULT for each and any of the events listed in Table 8-1. Failure to do so will produce erroneous data in the Login Attempts report, such as recording a Normal, Successful Login when an invalid user or password was entered.
Common Authentication Scheme Components
Despite the wide variety of authentication schemes available in APEX, all schemes do share some common attributes that function the same. These attributes control the basics of the authentication scheme—where to go when a session is invalid, when a user logs out, and settings for cookies. There is also a place to embed any PL/SQL functions and/or procedures that may be required in support of the different components of the authentication scheme.
Source
The Source region is used to enter an anonymous block of named PL/SQL code that will be referenced only from within the authentication scheme. This differs from all other PL/SQL regions in APEX, in that named functions and procedures need to be entered here versus a true anonymous block of PL/SQL.
Using this method is not required or recommended because any code embedded within the authentication scheme cannot be accessed from anywhere else, including similar authentication schemes in different applications. It is a much better idea to refer to named PL/SQL packages from within an authentication scheme because all the benefits of using PL/SQL packages are extended in this case. Additionally, multiple applications can call the same PL/SQL packages, making them more reusable and manageable should a change be required.
Session Not Valid
The Session Not Valid settings, as shown in Figure 8-7, are designed to provide a landing page for when a user attempts to access an application with an invalid session. There are essentially three options: the application’s login page, the built-in APEX login page, or a URL. In almost all cases, it is best to use the login page as defined in your application. However, there are times when a specific URL—such as an application that is used to allow only users to log in—is acceptable.
Figure 8-7 . The Session Not Valid settings
There is an additional option in the Session Not Valid section: Verify Function Name. This function is called after the page sentry function is called. While that seems redundant, it has a slightly different purpose. First, in most cases, the page sentry function is the internal APEX session management function and is not specified. Therefore, in most authentication schemes, the verify function is the only place that the session can be manually enforced.
The intended purpose of the verify function is also different from that of the page sentry function. The verify function is intended to check a business rule to determine whether the application should be available, whereas the page sentry function is intended to check the integrity of the actual session. They are intended to work in concert with one another, not be redundant. An easy-to-understand application that differentiates the use of the verify function would be one that checks the time of day and allows a user to access an application only during business hours.
Login Processing
The Login Processing settings, as illustrated in Figure 8-8, provide the developer with the ability to call a PL/SQL procedure both before and after the user attempts to log in to the applications. These can be used for any type of event, such as auditing the login attempt or calling a procedure to initialize the environment.
Figure 8-8 . The Login Processing settings
The Pre-Authentication event will not occur when using the HTTP Header Variable or Oracle Application Server Single Sign On authentication schemes because the authentication event occurs outside of APEX in those cases.
Post Logout URL
The Post Logout URL specifies where APEX will branch to after the user logs out of an application by explicitly clicking the Logout link. It is a little counterintuitive to set this to the home page because that page typically requires that the user be authenticated. However, if it is set to the home page, APEX will first check to see whether a valid session is present. In this case, there will not be a valid session present, so APEX will then redirect to the page specified in the Session Not Valid section. If the Post Logout URL is set to a URL, then APEX will branch to that URL upon logout.
Session Cookie Attributes
The last common section across all authentication schemes is Session Cookie Attributes. These attributes control how the APEX session cookie for an application is created. There are four options, as shown in Figure 8-9.
Figure 8-9 . The Session Cookie Attributes section
By default, APEX will assign the cookie used for an application a standard name in the format ORA_WWV_APP_NNN, where NNN is the application ID. The developer does not need to specify anything for this to occur; it is completely automated. This allows APEX to keep track of and keep session isolated for any number of distinct applications, given that the cookie associated with each is different and easily identifiable.
The Cookie Name attribute can be set to any value that the developer chooses. If, for instance, the developer set this value to MONSTER, when a user authenticates to the application, the name of the cookie set by APEX will be MONSTER. If the cookie name of a suite of applications is set to MONSTER, then as soon as the user authenticates to any one of them, they will be authenticated to all of them. All that would need to be added to each application is a way to refer to one another using the same session ID.
In fact, the APEX development environment uses this same technique so that when you authenticate to the Application Builder, your session is also valid in the SQL Workshop, Team Development, and Administration because each of those modules is a separate APEX application that happens to share the same cookie name.
Lastly, the Secure attribute is used to determine whether to allow the session cookie to be created when running over HTTP. If it is set to No, then APEX will permit the session cookie to be set when using HTTP. This is extremely dangerous and opens up your application to a great deal of risk because anyone who can view network packets can eavesdrop and grab the session cookie values and session ID as they are sent to your PC. Armed with these two values, it is possible for a malicious user to hijack your APEX session by constructing a fake cookie on their PC.
Therefore, this attribute should always be set to Yes, which will restrict APEX from sending a session cookie to the client when the connection is done over HTTPS. If this attribute is set to Yes and the user attempts to connect via HTTP, they will simply not be able to log in, despite that the correct credentials have been provided.
Mechanics of Authentication
Authenticating in APEX is actually quite simple. When an unauthenticated user attempts to access an application, that user must provide their credentials. If successful, the credential verification function will return a TRUE, and the user will be authenticated. If a FALSE is returned, it can mean only that there was an error if verifying the user’s credentials. APEX does not particularly care how the credentials are verified or what type of repository is used. It only cares that either a TRUE or FALSE is returned and knows what to do in either case.
Thus, the mechanics of authenticating to an APEX application are largely identical, aside from the specifics of how the credentials are verified. This is true across all types of authentication schemes—LDAP, HTPP Header, Application Express Accounts, and so on. The next session steps through the mechanics of what APEX does when a user logs in. For simplicity, the authentication scheme that will be used is the Application Express Accounts. Keep in mind that the mechanics would be the same regardless of the specific authentication scheme used.
The Login Page
When users attempt to access an APEX application, they typically do so by either typing in the URL or using a bookmark that contains at least a reference to the application ID. This request is sent to the APEX engine, which in turn begins to process it. Before the page is even rendered, one of the first checks to occur is to determine whether the user’s session is valid. This is done by the page sentry function. It will check both the session ID and session cookie values with those stored in the database and determine whether the session is, in fact, valid.
Since in this example you are starting from scratch, the page sentry function will immediately determine that the session is not invalid and take action. The action it will take is to look up where to go next in the Session Not Valid section of the corresponding authentication scheme. Assuming that you are using the APEX application login page, you will then be redirected to that page. Since that page is a public page, it will be allowed to render, even though you have not yet successfully authenticated.
By default, APEX will assign page 101 as the login page and page 1 as the home page when a new application is created. While it is possible to change this, it is best to keep with the de facto standards of 101 for login and 1 for home so that other developers will know where to look for them.
APEX will also assign a page alias of LOGIN_DESKTOP to page 101. This alias is used when defining the login page for a specific user interface. If the page alias is changed, the reference in the user interface attributes section will also have to be updated to match it. New in APEX 4.2, a user interface determines which set of pages to use when running an application based on whether the device is a desktop PC or a mobile browser. It is possible to create an application that contains a user interface for both desktop and mobile, each with their own separate login and home page. The User Interfaces section can be found under an application’s shared components, as shown in Figure 8-10.
Figure 8-10 . The User Interfaces section of an application
Editing the Desktop user interface will reveal where the home and login pages of an application are defined in APEX 4.2 for that specific user interface, as illustrated in Figure 8-11. In previous versions of APEX, the login and home page were defined in the Security Attributes section.
Figure 8-11 . The attributes of the Desktop user interface, including home and login pages
When created, the application login page will contain a number of precreated processes, as shown in Figure 8-12. In most cases, there is no need to modify these processes. In fact, altering or disabling them may cause APEX’s login mechanism to stop working.
Figure 8-12 . The standard APEX login page as viewed in the application development environment
Login Page Processes
The first process that gets executed when the login page runs is called Get Username Cookie. This process will attempt to read a value from a cookie called LOGIN_USERNAME_COOKIE, which contains the last used user name for this application. Using the Web Developer add-on, it is simple to view this and any another cookies, as shown in Figure 8-13.
Figure 8-13 . The LOGIN_USERNAME_COOKIE, as shown with the Web Developer add-on
Cookies are nothing more than text files that a browser reads and writes to in order to maintain a value-attribute pair that can persist longer than a single page view. Developers have long used cookies to store session-specific information so that as a user goes from one page view to another, the value of the cookie can be used to determine whether their session is valid. Many web sites, regardless of their underlying technologies, also use cookies in this manner.
APEX uses cookies for both the application development environment as well as any user-developed applications. The APEX developers made it a point to store very little information in the cookies because any data stored there is not terribly secure. This best practice is a good model for any developer or any web application.
If the LOGIN_USERNAME_COOKIE cookie exists, then the process will set the value of the page item P101_USERNAME to the value of the cookie. In APEX 4.1 and 4.2, this is done via the APEX_AUTHENTICATION API, as shown in Listing 8-1.
Listing 8-1. The Source of the Get Username Cookie Process in APEX 4.2
:P101_USERNAME := apex_authentication.get_login_username_cookie;
Prior to APEX 4.1, a call to owa_cookie had to be made, similar to how the Set Username Cookie setting worked. You can see this call in Listing 8-2.
Listing 8-2. The Source of the Get Username Cookie Process in APEX 4.1 and Prior Releases
declare
v varchar2(255) := null;
c owa_cookie.cookie;
begin
c := owa_cookie.get('LOGIN_USERNAME_COOKIE'),
:P101_USERNAME := c.vals(1);
exception when others then null;
end;
Once the value of the last user name used is fetched from the cookie, the user is presented with the login page, where they are prompted to enter their credentials. There is nothing proprietary about the user name and password fields because they are standard APEX items. The only consideration is that the password field has an attribute called “Does not save state.” This attribute will be set to Yes by default and should left that way. By doing so, it will prevent the password from ever being written to APEX’s session state, where it could be viewed by an administrator or DBA. The value of the password will be available in memory for only the page-processing phase of this page so that it can be checked against the stored password.
Once the login page is submitted, the first process to execute is called Set Username Cookie. This process will store the user name used in the LOGIN_USERNAME_COOKIE cookie by making a call to the APEX_AUTHENTICATION API, as shown in Listing 8-3.
Listing 8-3. The Source of the Set Username Cookie Page Process in APEX 4.2
apex_authentication.send_login_username_cookie (
p_username => lower(:P1001_USERNAME) );
Versions prior to APEX 4.1 set the same cookie with the same value but made calls directly to the owa_cookie package, as shown in Listing 8-4.
Listing 8-4. The Source of the Set Username Cookie Page Process in APEX 4.0 and Prior Releases
begin
owa_util.mime_header('text/html', FALSE);
owa_cookie.send(
name=>'LOGIN_USERNAME_COOKIE',
value=>lower(:P101_USERNAME));
exception when others then null;
end;
The user name will be stored only as long as the browser session is valid. If the user logs out of an application, the user name will be fetched and automatically entered into the user name field when redirected to the login page. If the user quits the browser and then restarts it later and attempts to access the application, the user name will no longer be stored, and the corresponding field on the login page will be blank.
Next, the actual authentication event occurs when the login process is executed. Regardless of which authentication scheme is being used, APEX will call the same API and pass in two parameters: the user name and password supplied by the user via the login page. In APEX 4.1 and 4.2, the APEX_AUTHENTICATION API is called with only two parameters, as shown in Listing 8-5.
Listing 8-5. The Source of the Login Page Process in APEX 4.2
apex_authentication.login(
p_username => :P101_USERNAME,
p_password => :P101_PASSWORD
);
In APEX 4.0 and prior versions, a different API—wwv_flow_custom_auth_std—is called. Not only are the user name and password passed to this API, but so are the application session and home page, as shown in Listing 8-6.
Listing 8-6. The Source of the Login Page Process in APEX 4.0 and Previous Releases
wwv_flow_custom_auth_std.login(
P_UNAME => v('P101_USERNAME'),
P_PASSWORD => :P101_PASSWORD,
P_SESSION_ID => v('APP_SESSION'),
P_FLOW_PAGE => :APP_ID||':1'
);
Once the API in the login process is called, APEX will look up and call the current authentication scheme, passing in the credentials provided by the user. That authentication scheme will do the actual authentication check—be it at an LDAP server or HTTP header value or a custom function—and return either a TRUE or FALSE to the API. If successful, the APEX session and corresponding cookie will be created.
At this point, APEX will write a row to the WWV_FLOW_SESSIONS$ table, which is in the APEX_040200 schema, as shown in Figure 8-14.
Figure 8-14 . A row from WWV_FLOW_SESSIONS$, showing the session ID and hashed session ID
The value in the ID column corresponds to the APEX session ID and should match the value found in the URL. The SESSION_ID_HASHED value is stored in the APEX session cookie, which is used to check the validity of that user’s session. Its name will vary based on the application that the user is running. In Figure 8-15, the cookie’s name is ORA_WWW_APP_157 because the ID of the application running is 157.
Figure 8-15 . The main APEX session cookie
Lastly, the value in the SECURITY_GROUP_ID column maps to the PROVISIONING_COMPANY_ID in the WWV_FLOW_COMPANIES table, as shown in Figure 8-16.
Figure 8-16 . A row from WWV_FLOW_COMPANIES, showing how the PROVISIONING_COMPANY_ID maps to the SECURITY_GROUP_ID column in the WWV_FLOW_SESSIONS$ table
Back when Oracle APEX was called Oracle Flows, workspaces were referred to as companies. Hence, the name of the base table matches the old name. This table is, of course, used to store information about the workspace. Thus, the value stored in the APEX session cookie can be tracked to the sessions table and then to the workspace table, providing APEX with all the details it needs to securely manage sessions.
After the session cookie is set, one last process will clear the page cache for the login page. This is done to ensure that the user name and password values do not remain in session state, where a workspace administrator or DBA could compromise them. Once the session state for the login page is cleared, the user is directed to the home page of the application as defined in the user interface section and will officially be authenticated, as shown in Figure 8-17.
Figure 8-17 . A successfully authenticated APEX session
Notice that the session ID in Figure 8-17 is set to 14788437140955. Back in Figure 8-14, the value of the ID column was also set to 14788437140955. Again, this is how the APEX session ID is linked to the APEX session cookie.
If the credentials that the user supplied are invalid, then the user will be redirected to the login page and given the opportunity to try again. Depending on the instance settings, each additional attempt at logging in may result in a delay. This is done to combat a malicious user who is trying to guess what a user’s password is by brute force.
Logging Out
Once the user is authenticated, the session associated with them will remain valid until one of the following events occurs:
- The session duration is exceeded.
- The session idle time is exceeded.
- The session is purged by the ORACLE_APEX_PURGE_SESSIONS job.
- The session is purged by an APEX administrator.
- The session ID in the URL is altered/removed.
- The session cookie is altered/removed.
- The user quits the browser.
- The user clicks the logout link.
Any of these events will cause the session to be invalidated and cause APEX to redirect to the URL as specified in the Session Not Valid section of the current authentication scheme. It doesn’t really matter which event occurs, because once a session is terminated, there is no way for the user to rejoin that session. All they can do is log in again with their credentials and establish a new session.
By default, every APEX application will contain a navigation bar entry called Logout. The target of this navigation bar entry is set to &LOGOUT_URL., which is a built-in item that will be replaced with a call to the APEX_AUTHENTICATION API, as shown in Listing 8-7.
Listing 8-7. The URL Associated with the Logout Navigation Bar Entry
http://servername.com/apex/apex_authentication.logout?p_app_id=154&p_session_id=11260269600710
When the Logout navigation bar is clicked, the user’s session will be terminated, and any values stored in session state will be deleted. If the user instead quits the browser without clicking the Logout link, only the session state will be terminated. The values stored in session state will persist in the internal APEX tables until they are purged by the ORACLE_APEX_PURGE_SESSIONS job, which runs every eight hours by default. All session cookies will also be deleted in the event that the user bypasses clicking Logout and quits the browser.
It is important to note that if a user simply closes the browser tab and other tabs are open, the associated APEX session is not terminated. When a browser tab is closed, the APEX session cookie does not get removed and is still valid. A user could search though their browser history and find a URL that contains the previously used session ID and rejoin that session. This is not cause for alarm because only the user who previously mapped to that session can rejoin it if a browser tab is closed. Another user on another PC—or even the same user on the same PC in a different browser—will be unable to rejoin that session, even when using a URL that contains the session ID.
Summary
APEX authentication schemes are both simple and sophisticated at the same time. Their simplicity lies in the fact that all they do is return a Boolean value. Their sophistication comes from the virtually limitless procedures and functions that can influence the value returned. With just a little configuration, the needs of most organizations can be met by one of the built-in authentication schemes. If this is not the case, the capabilities of the Custom authentication scheme can be used.