JDBC Realm Authentication Sample Application

> JDBC Realm Authentication Sample Application
> The JDBC realm sample code demonstrates by example how to develop a custom authentication realm for Sun ONE Web Server. A custom authentication realm can be plugged into Sun ONE Web Server to perform user authentication for Java web applications hosted by the Sun ONE Web Server web container. This sample realm implementation performs authentication against a database (using JDBC), however, you can modify it to authenticate against any backend you need by developing the appropriate logic and compiling your own custom realm. Refer to the javadoc comments in JDBCRealm and JDBCLoginModule for further guidance on custom realm development.

> This sample application document contains the following sections:

> Overview

> Compiling and Assembling the Sample Application

> Running an authentication sample

> Troubleshooting

> Overview

> The JDBC Realm Authentication sample demonstrates how to develop a custom authentication realm and use it with any authentication web application.

> Precompilation Tasks
> Before you begin to compile and deploy the code, there are some housekeeping tasks that must be performed.

> For information about creating and maintaining the database, refer to the database documentation.
> For information about using the PointBase database with Sun ONE Web Server, refer to How to run sample applications with Pointbase.
> For information about using the Oracle database with Sun ONE Web Server, refer to How to run sample applications with Oracle.
> If you want to run the sample on an Oracle database, you must use the following script to create the table 'user_tbl' with data: <install_root>/plugins/java/samples/webapps/security/jdbcrealm/src/sql/dbscript-ora.sql.

> If you want to run the sample on a PointBase database, you must use the following script to create the table 'user_tbl' with data: <install_root>/plugins/java/samples/webapps/security/jdbcrealm/src/sql/dbscript-pb.sql.

> Add the following line to the login.conf in the <instance_root>/config/login.conf
> jdbcRealm { samples.security.jdbcrealm.JDBCLoginModule required debug=false; };

> Compiling and Assembling the Sample Application

> This section contains instructions for compiling and assembling the sample application.

> Compile and assemble the JDBC and web application.

> Execute ant under <install_root>/plugins/java/samples/webapps/security/jdbcrealm/src
> It will create the jdbcrealm.jar under the <install_root>/plugins/java/samples/webapps/security/jdbcrealm directory.
> Open the server.xml file of the web server instance.
> (a) Add the following to the classpathsuffix:
> <install_root>/plugins/java/samples/webapps/security/jdbcrealm/jdbcrealm.jar
> For example, check the following sample JAVA element (/ws61 is the <install_root>):

>     Change it from

>        <JAVA javahome="/ws61/bin/https/jdk" serverclasspath="/ws61/bin/https/jar/webserv-rt.jar:
>        ${java.home}/lib/tools.jar:/ws61/bin/https/jar/webserv-ext.jar:/ws61/bin/https/jar/webserv-jstl.jar:
>        /ws61/bin/https/jar/ktsearch.jar" classpathsuffix="" envclasspathignored="on" debug="false"
>        debugoptions="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n" dynamicreloadinterval="2">
>        ........
>        ........
>        </JAVA>

>     to

>        <JAVA javahome="/ws61/bin/https/jdk" serverclasspath="/ws61/bin/https/jar/webserv-rt.jar:
>        ${java.home}/lib/tools.jar:/ws61/bin/https/jar/webserv-ext.jar:/ws61/bin/https/jar/webserv-jstl.jar:
>        /ws61/bin/https/jar/ktsearch.jar" classpathsuffix="/ws61/plugins/java/samples/webapps/security/jdbcrealm/jdbcrealm.jar"
>        envclasspathignored="on" debug="false"
>        debugoptions="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n" dynamicreloadinterval="2">
>        ........
>        ........
>        </JAVA>

>     (b) Do the following for creating a new realm called "jdbc"

>         1. Log in as administrator through the Administration GUI.

>         2. Select the manage server -> select "Java" menu option -> select "Security Realms" and then select "New" button.

>         3. For "Realm Name" field enter "jdbc", "Classname" field enter "samples.security.jdbcrealm.JDBCRealm" and enter the following properties.
>            (A) name="dbusername"    value="<your database user name>"/>
>            (B) name="dbpasswd"      value="<your database password>"/>
>            (C) name="userpasswdcol" value="passwd"/>
>            (D) name="usergroupcol"  value="groups"/>
>            (E) name="jaas-context"  value="jdbcRealm"/>
>            (F) name="usernamecol"   value="userid"/>
>            (G) name="usertable"     value="user_tbl"/>
>            (H) name="dbdrivername"  value="<your database driver name>"/>
>            (I) name="dburl"         value="<your database url>"/>

>            NOTE: (The value for dbdrivername and dburl properties)
>            For a PointBase server database:
>            name="dbdrivername" value="com.pointbase.jdbc.jdbcUniversalDriver"/>
>            name="dburl"        value="jdbc:pointbase:server://<host name>/<database name>"/>
>            For an Oracle database:
>            name="dbdrivername" value="oracle.jdbc.driver.OracleDriver"/>
>            name="dburl"        value="jdbc:oracle:thin:@<host name>:<port>:<sid>"/>

>         4. Select "Java" menu option -> select "Java Security", Change the "Default Realm" to "jdbc" and then click "OK" button.

>     (c) Save that server.xml and restart the server.

> You can use any authentication web application. For example,
> you can use the basic authentication sample.
> Make sure the basic authentication sample is deployed and working fine.

> You can clean the web application project area by executing the following command.
> This will remove the sample application build directory.
> ant clean

> Running an authentication sample

> You can run the basic authentication application through the following URL:

> http://<web_server_host>:<port>/webapps-security-basic

> Login as "j2ee" with password "secret."
> It will display the message "Welcome to our BASIC secure zone!"

> Troubleshooting

> If you run the sample application more than once, make sure you close all instances of the browser so that the session information is not stored. Otherwise, it will not prompt you for the user name and password. Make sure you close your email sessions as well, so that all stored session information is destroyed.

> If you encounter problems when running the application, review the log files at <instance_root>/logs/errors to determine what went wrong.

> Copyright © 2003 Sun Microsystems, Inc. All rights reserved.