How-To Document

Authenticate Users Using an LDAP Server

Date: 22-Jan-2004
Updated: 28-Jan-2008

After completing this How-To, you should understand:

  • How to create a new authentication scheme that uses LDAP for credentials verification.

  • How to alter an existing authentication scheme to make it use LDAP for credentials verification.
  • How to use the LDAP test tool.

Table of Contents

 

Introduction

When your application's login page calls the Oracle Application Express login API with a username and password, the Oracle Application Express engine calls the credentials verification method specified in the application's current authentication scheme. You can implement this method yourself as a PL/SQL function returning boolean and put it in your application's schema. This allows you to perform username/password verification however you like (your own tables, LDAP lookup, 3rd-party API, etc.). As a convenience, Oracle Application Express offers some built-in credentials verification methods. One of those uses DBMS_LDAP to access the LDAP directory that you specify in the authentication scheme attributes. You can use this method if:

  • There is an LDAP directory accessible to the server that hosts your Oracle Application Express instance, and
  • The LDAP directory has entries that correlate usernames with passwords, and
  • The LDAP directory can be accessed as shown in this PL/SQL code snippet:
                                             
          l_boolean := dbms_ldap.simple_bind_s( l_session, p_dn, p_password );
                                          
    ...where l_session is the session handle, p_dn is the distinguished name containing the username, and p_password is the password. An example of p_dn for username 'joe' might be:
                                             
          cn=joe,l=amer,dc=oracle,dc=com
                                          
Ask your admin if the LDAP directory will allow username/password verification using this interface. (The complete function is shown at the bottom of this how-to.) If so, you can use Application Express's built-in LDAP support in your authentication scheme. If not, you still may be able to use an LDAP directory for authentication, but you'll have to write a PL/SQL wrapper function to access LDAP according to your installation's interface requirements. You can then use the function that you write as the 'Authentication Function' attribute of your authentication scheme using the syntax: return function_name;

Note: You must already have run catldap in your database to create the LDAP packages. If in doubt, please read your Application Express installation file: doc/ldap.html.



Creating an Authentication Scheme that uses the Built-in LDAP Authentication Method

  1. Navigate to Application Builder home page
  2. Select the desired application
  3. Click the Shared Components icon
  4. Under Application, click Definition
  5. Select the Security tab and then the Authentication icon.
  6. Click Create Scheme.
  7. Under Create Scheme, select Based on a pre-configured scheme from the gallery.
  8. Under Gallery, select Show Login Page and Use LDAP Directory Credentials.
  9. Click Next.
  10. Under Specify Login Page, Select Use Built-In Login Page, Use Page XXX As Login Page, or if no login page exists, Create New Login Page.
  11. Click Next.
  12. Under LDAP Settings, Enter the LDAP configuration parameters. LDAP Host, LDAP Port, and LDAP DN string are required. Obtain the correct values for these from an administrator, if necessary. You must replace the username component of the DN string with the placeholder '%LDAP_USER%'. For example, if an actual DN string for user 'joe' would be:
        cn=joe,l=amer,dc=oracle,dc=com
    
    Enter the following for the LDAP DN String parameter:
        cn=%LDAP_USER%,l=amer,dc=oracle,dc=com
    
    The engine will take the value of upper(p_username) passed to the login API and replace %LDAP_USER% with it before making the call to DBMS_LDAP.SIMPLE_BIND_S.

  13. If you need to modify the value of p_username before substituting it for the %LDAP_USER% placeholder in the dn, you can specify a function to do that first. Enter 'return your_function;' (without quotes) as the value of the LDAP Username Edit Function. The function must be executable by your application's schema and must have the signature:
        function your_function(
            p_username in varchar2)
            return varchar2;
    
    If you do specify such a transformation function, the value substitued for %LDAP_USER% in the p_dn argument to SIMPLE_BIND_S will be:
        your_function(upper(p_username));
    
  14. After entering all required LDAP attributes, click Next. Enter any name you like for the new authentication scheme. Click Create.
  15. Find the new scheme in the report of available authentication schemes. Click the 'make current' link to the right of the scheme's description to make it current for the application.
  16. Run the application. When you submit the login page, credentials verification will take place using the LDAP configuration.

Altering an Existing Authentication Scheme to use the Built-in LDAP Authentication Method

  1. Navigate to Application Builder home page
  2. Select the desired application
  3. Click the Shared Components icon
  4. Under Application, click Definition
  5. Select the Security tab and then the Authentication icon.
  6. From the list of authentication schemes, click the edit icon for the scheme you want to change.
  7. Scroll down to the Login Processing region.
  8. In the Authentication Function box, enter -LDAP-, or click the LDAP quick link just below the box.
  9. Enter the LDAP Host, LDAP Port, LDAP DN String, and optionally, the LDAP Username Edit Function values as described earlier in this document.
  10. To ensure that LDAP authentication is compatible with the other settings of the authentication scheme, you'll need to check the Page Session Management region to ensure that the Page Sentry Function is not '-DATABASE-' (leave it blank), and that the Session Not Valid URL is not '-PORTAL_SSO-' (blank it out and select a login page in the Session Not Valid Page LOV instead). You'll also need to specify a Logout URL if it isn't already specified. Check out one of the pre-configured authentication schemes for an example of a generic logout URL.
  11. Click Apply.
  12. 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.
  13. Run the application. When you submit the login page, credentials verification will take place using the LDAP configuration.

Using the LDAP Test Tool

  1. Navigate to Application Builder home page
  2. Select the desired application
  3. Click the Shared Components icon
  4. Under Application, click Definition
  5. Select the Security tab and then the Authentication icon.
  6. From the list of authentication schemes, click the edit icon for a scheme that uses LDAP authentication.
  7. Scroll down to the Login Processing region and find the LDAP Host field.
  8. Click the LDAP Test Tool link. A popup window shows the current LDAP settings and will allow you to enter sample username/password combinations with which you can test the configuration.
LDAP Authentication Function
                                     
function authenticate( p_dn in varchar2, p_password in varchar2, p_ldap_host in varchar2, p_ldap_port in number) return boolean as l_retval pls_integer; l_retval2 pls_integer; l_session dbms_ldap.session; begin if p_password is null then return false; end if; l_retval := -1; dbms_ldap.use_exception := TRUE; begin l_session := dbms_ldap.init( p_ldap_host, p_ldap_port ); l_retval := dbms_ldap.simple_bind_s( l_session, p_dn, p_password ); l_retval2 := dbms_ldap.unbind_s( l_session ); return true; exception when others then l_retval2 := dbms_ldap.unbind_s( l_session ); return false; end; exception when others then return false; end authenticate;

 

Additional Resources

Oracle Application Express Home

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