Sun ONE logo    
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

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.


  1. 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.


  2. 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.


  3. 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.


    1. 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.

    2. 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.

    3. 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.


    4. 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




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