Readme for the Database Identity sample Plugin

Introduction

It uses a database (generally the built-in SES database) to authenticate users, get groups, etc. This allows you to set up a full secure SES system for testing or demo purposes without relying on an external user directory system (such as Oracle Internet Directory or Microsoft Active Directory).

There were two reasons for creating this plugin:

  1. We didn't have any suitable sample Identity Plugins that customers / partners could use as a basis for writing their own, and
  2. I wanted an identity plugin that didn't rely on any external software like OID, AD, etc. This would enable me to demonstrate / test secure searching without relying on having a directory system installed or available.
  • It has no way of fetching groups
  • It doesn't work with the database crawler (I can't remember exactly why - I think it doesn't support the "username" attribute)

This plugin can either use database users, OR it can use a table of username / password pairs within the database. It can also resolve group information from a database table.

See index.html in the javadoc directory for more information.

Building and Installing the Plugin

Extract the files from the attached zip file into a scratch directory. Edit "build.bat" on Windows or "build.sh" on Linux to include the location of your SES installation.

Run build.bat / build.sh from the command line (your current working directory should be that where the build file is located). This will compile the java code to a jar file and copy that to the correct location in your SES installation.

Then follow the steps below:

Go to Global Settings -> System -> Identity Management Setup


Register new Identity Plugin...


Add the class name and jar file name...

Now choose "Improved Database Identity Plugin" and click "Activate":



You will be expected to supply plugin parameters.

The "Connect String" is the JDBC connect string to your Oracle database.

Note: the default value connects to the local SES database, when installed with all default options. Be aware that use of the internal SES database for any other purpose is not supported or licensed, so this is purely for testing or development. If you wish to make use of this setup in a production system, you should use an external database (you should also take steps to ensure the stored passwords are encryped - which they are not for this demo).

I've chosen to use the SYSTEM user here - it's probably better to use a different user you have created in the database. You can accept the default queries as supplied for now. After testing you may choose to create your own tables and vary the queries used here.

Click on "Finish" when done.


If you get an error "The plugin rejected the parameters" you must check your oc4j log file ( $ORACLE_HOME/oc4j/j2ee/OC4J_SEARCH/log/oc4j.log) for the error message from the plugin. It is likely that you missed a parameter, or had invalid combinations (such as providing an authentication query when "Use database users" was set to "true").

Now we need to set up the tables containing username / password pairs, and the groups memberships to be assigned to each user. This may be done using the included file setup.sql

Edit setup.sql and change the SYSTEM password to the SES admin password (or create a different username in the database, and use that username and password instead).

Then, in SQL*Plus (or SQL Developer) run the file "setup.sql" to create the tables and some sample users. For SQL*Plus I would use:

       
 sqlplus /nolog @setup.sql

    

This creates users and groups as follows:

user sesuser1 with password welcome1 is in groups group1 and group2.
user sesuser2 with password welcome2 is in groups group1 and group3.

To test that the installation has succeeded, open the SES query window. You should see a "Login" link at the very top right of the page, which would not have been there before. Click on this link, and login as user "sesuser1" with password "welcome1". If you log in successfully, everything is probably OK. If you don't manage to login successfully, check the oc4j log file for errors (see details of the file location above).

Debugging

Instead, I prefer to use copious debug output statements in the code. You can normally do this using the Logger method "debug", but occasionally the Logger will not be initialized and this will not work. In that case you can make use of the "pdebug" method in DbIdMgr.java. This opens a file, appends the debug string to it, and closes it again. The file name is hard-coded into the method - make sure it's suitable for your system.

Using Database Usernames

To use this feature just set the plugin parameter "Use database users" to "true". In this case the "Authentication Query" can be left blank. "Usercheck Query" can be supplied, but would normally be left blank and will default to checking the ALL_USERS table - make sure the database user you are using has read access to that table.

When using database users, you can still provide group queries. If you don't then no group functionality will be available.

User Authorization Cache


V1.0. Last modified: 6 November 2008 by Roger Ford