How-To Document

Change How Users are Authenticated

Date: 19-Jan-2006
Based on Application Express (formerly called HTML DB) version 2.0

After completing this How-To, you should understand:

  • How to edit an existing authentication scheme to change the method it uses for credentials verification.

Table of Contents

 

Introduction

When your application's login page calls the Oracle Application Express login API with a username and password, the engine calls the credentials verification method specified in the application's current authentication scheme. You have three choices about how credentials are verified from within the login API:

  • Implement the method yourself as a PL/SQL function returning boolean and put it in your application's schema.
  • Use the built-in LDAP authentication method, which checks username and password against the LDAP directory that you specify.
  • Use the built-in Oracle Application Express authentication method, which checks username and password against the Application Express account repository.


This how-to explains how you can change an existing authentication scheme that uses one of the above credentials verification methods so that it uses one of the other three methods instead.

It's also possible to use an external authentication service like Oracle AS Single Sign-On, but Oracle Application Express redirects to these services instead of showing a login page. This how-to focuses on authentication methods called during the processing of the application's login page. Please see this how-to for more instructions about using Oracle AS Single Sign-On with Oracle Application Express.

Software Requirements

Setting the Credentials Verification Method
  1. Log into Application Express
  2. Click Application Builder.
  3. Click on the icon of the application you wish to edit.
  4. Click Shared Components.
  5. Click Authentication Schemes.
  6. From the list of authentication schemes, click the edit icon for the scheme you want to change.
  7. This procedure applies only to authentication schemes that use a login page that calls the Oracle Application Express login API (wwv_flow_custom_auth_std.login). Before proceeding, check the 'Session Not Valid Page and 'Session Not Valid URL' attributes. If either of these attributes points to an Oracle Application Express page in this or another application, you're probably okay. If you're not sure, you can edit the login page in the Builder and inspect the after-submit processes for the login API call. Proceed if you find it. If 'Session Not Valid URL' is '-BUILTIN-' that indicates the built-in login page. The built-in login page uses the login API, so you may proceed in that case as well. If no login page is specified, e.g., in the case where 'Page Sentry Function' is '-DATABASE-' or '-PORTAL_SSO-' you should not continue with this procedure. Instead, you may want to create a new authentication scheme based on a pre-configured scheme from the gallery.
  8. Scroll down to the Login Processing region.
  9. To use the LDAP built-in method, in the authentication function field, enter -LDAP- and follow the instructions here to specify the LDAP configuration.
  10. To use the Oracle Application Express built-in method, in the authentication function field, enter -BUILTIN-. Users will be authenticated with username/password combinations stored in the Oracle Application Express internal account repository.
  11. To use your own custom method, in the authentication function field, enter return your_function;. The function, named whatever you like, either standalone or packaged, must be executable by your schema and must have the signature:
        function your_function (p_username in varchar2, p_password in varchar2) return boolean;
    
  12. The p_username and p_password arguments to the login API in the login page's after-submit process are passed on to your custom authentication function. (Actually p_username is UPPERed first.) The boolean result of your function determines whether the login API continues with session registration (true) or redisplays the login page with the 'Invalid Credentials' message (false).
  13. Click Apply Changes.
  14. Find the edited scheme in the report of available authentication schemes. Click make current to the right of the scheme's description to make it current for the application. Making a scheme current causes that authentication scheme to be used when the applicatio is run.
  15. Run the application. (Log out first if you have an active session that used the old scheme.) When you submit the login page, credentials verification will take place using the new credentials verification method.


Additional Resources

Oracle Application Express Home

Discuss this how-to in the Oracle Application Express Discussion Forum