Samples Index

JDBC Realm Authentication Sample Application

This sample application demonstrates using a custom security realm. It uses the basic-auth or form-auth sample.

Setting up the environment

Before you deploy or run the application, you must ensure that a database resource has been configured for Application Server. The included asant deployment script automatically performs this step for you. But if you are using another deployment mechanism, you must perform it manually.

You can use any JDBC-compliant relational database server, but resources are provided for the following:

• Derby: Derby comes with Application Server. For more information, see Using the Derby Database with Sample Applications.
• PointBase: a small-footprint Java relational database. For more information, see Using PointBase with the Samples.
• Oracle: One of the most popular relational databases. For more information, see How to run samples with Oracle database server.

Now, perform the following steps:

1. Start the Derby database, as described in Using the Derby Database with Sample Applications. The default admin username and password are security/security which is configured by invoking ant target create-auth-realm.
2. Make sure the PUBLIC.user_tbl table exists and it contains some user records, by running ant target local.configure.db.
3. Add the following line to the configuration file domain_root_dir/domain_name/config/login.conf:

   jdbcRealm { samples.security.jdbcrealm.JDBCLoginModule required };
   

4. Connect to the Admin Console and select the instance of Application Server to which to deploy the application.
5. From the left column select Security > Realms. Add the new realm "jdbc". Then add the classpath as: samples.security.jdbcrealm.JDBCRealm
6. Click on Security on the left panel. You will see Security pane on the right.
7. Select the Default Realm as jdbc.
8. Cick on jdbc on the left hand column under Security > Realms > jdbc
9. Click on Add Property and add the properties listed in the section below, depending on the database you are using.
10. IMPORTANT: Restart the server before deploying or running the application.

Database Properties

Add the following properties for all databases.

Properties for all Databases

Property Name	Property Value
dbusername	security
dbpasswd	security
userpasswdcol	passwd
usergroupcol	groups
jaas-context	jdbcRealm

To connect to Derby database add the following properties.

Properties for Derby

Property Name	Property Value
usernamecol	uid
usertable	PUBLIC.user_tbl
dbdrivername	org.apache.derby.jdbc.ClientDriver
dburl	jdbc:derby://hostname:1527/DerbyDB

To use PointBase, add these properties.

Properties for PointBase

Property Name	Property Value
usernamecol	uid
usertable	PUBLIC.user_tbl
dbdrivername	com.pointbase.jdbc.jdbcUniversalDriver
dburl	jdbc:pointbase:server://hostname:9092/sun-appserv-samples

To use Oracle, add these properties:

Properties for Oracle

Property Name	Property Value
usernamecol	userid
usertable	user_tbl
dbdrivername	oracle.jdbc.driver.OracleDriver
dburl	jdbc:oracle:thin:@server:port:SID

With Oracle, create the user/password as security/security using the scripts mentioned in this document. Once the username is created you have manually create the user_tbl and insert the data in the table using sqlplus. To do this, use the script app_dir/setup/sql/dbscript-ora.sql.

Modify the domain.xml File

The domain.xml file should look like this when you are done with your edits:

<java-config classpath-suffix="${com.sun.aas.installRoot}/pointbase/lib/pbclient.jar
   ${path.separator}${com.sun.aas.installRoot}/pointbase/lib/pbembedded.jar
   ${path.separator}${com.sun.aas.javaRoot}/domains/domain1/lib/jdbcsecurity.jar"
   debug-enabled="false" debug-options="-Xdebug
   -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=1044"
   env-classpath-ignored="true" java-home="${com.sun.aas.javaRoot}" javac-options="-g"
   rmic-options="-iiop -poa -alwaysgenerate -keepgenerated -g"
   server-classpath="${com.sun.aas.javaRoot}/lib/tools.jar
   ${path.separator}${com.sun.aas.installRoot}/lib/install/applications/jmsra/imqjmsra.jar
   ${path.separator}${com.sun.aas.imqLib}/jaxm-api.jar
   ${path.separator}${com.sun.aas.imqLib}/fscontext.jar
   ${path.separator}${com.sun.aas.installRoot}/lib/ant/lib/ant.jar
   ${path.separator}/usr/lib/audit/Audit.jar">

Change the Deployment Descriptor

Before building the application, edit the Web deployment descriptor file app_dir/web/WEB-INF/web.xml. Change this line:

<realm-name>default</realm-name>

<realm-name>jdbc</realm-name>

If you want to use Form-Auth as your testing sample instead, change the realm name from "basic-file" to "jdbc".

Building, Deploying, and Running the Application

The general instructions for building, deploying, and running sample applications are provided in Building, Deploying, and Running Sample Applications. In reading this document, use the following application-specific variables for this application:

• install_dir is the directory where Application Server is installed.
• app_dir is the application base directory: install_dir/samples/security/realms/apps/rdbms.

Follow this general procedure:

1. Build the Application. The build file, build.xml, is in the app_dir directory, specifically, install_dir/samples/security/realms/apps/rdbms. This generates jdbcsecurity.jar file in app_dir/build/assemble/jar/.

   Add jdbcsecurity.jar to classpath-suffix element of domain_root_dir/domain_dir/domain.xml. See Directories and Variables for information on the location of domain_root_dir.

   Copy jdbcsecurity.jar from app_dir/build/assemble/jar to domain_root_dir/domain_dir/lib.

2. Build the basic-auth sample application.
3. Deploy the Application The EAR file is install_dir/samples/security/realms/apps/rdbms/bmp-simple.ear.
4. Run the Application. Use the following URL: http://hostname:port/basic/index.jsp. Log on as "j2ee" with password "secret".

Troubleshooting

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

Although the war, ear, context-root and servlet alias names in this sample are all "WebBasicApp", it is not necessary that it be so. The application will work as expected if the names of each of these attributes is unique. Rebuild the app after changing the context-root (in application.xml), the servlet alias (in web.xml) and the war and ear names (in the Ant build.xml), redeploy and test the sample to confirm this.

If you encounter problems when running the application, review the log files at install_dir/domains/domain1/logs/server.log to learn what exactly went wrong.

If you encounter problems in server.log similar to this when running the application:

[#|2004-06-13T15:41:41.195-0400|WARNING|sun-appserver-pe8.1|javax.enterprise.system.core.security|_ThreadID=10;
  |SEC1000: Caught exception.
com.sun.enterprise.security.auth.realm.BadRealmException: java.lang.ClassNotFoundException:
samples.security.jdbcrealm.JDBCRealm at com.sun.enterprise.security.auth.realm.Realm.
  doInstantiate(Realm.java:203)

Be sure to add the jdbcsecurity.jar file that contains the JDBCRealm.class to classpath-suffix element of the install_dir/domains/domain1/domain.xml file, as described previously.

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