                             Object Computing, Inc.
                          Java News Brief (July 2002)
         Developing an Enterprise Security Model Using JAAS and JBoss
                                     By
                      Brian M. Coyner, Software Engineer

--------------------------------------------------------------------------------

Thank You for downloading my sample application.  This bundle contains
two sets of applications.  The first application set are example JAAS
implementations that shows how to create and use the JAAS framework outside
of a J2EE server (from section 2).  The second application is a fully deployable
J2EE application configured for JBoss.

All code contained within this bundle comes as is.  Use at your own risk!  ;-)

Tested On
---------
Windows 2000

Required Software
-----------------
JBoss (2.4.5) - free, J2EE-compatible server
   www.jboss.org
JUnit (3.7) - Unit Testing framework
   www.junit.org
MySQL (3.23.38) - Open source relational database
   www.mysql.org
Ant (1.4.1) - Open source build tool
   jakarta.apache.org/ant
JDK (1.4)
   java.sun.com/j2se/1.4

Installation Procedures
-----------------------
To install the necessary tools please follow the directions below.

You should have already unzipped the bundle because you
are reading this file.  The directory where you unzipped
the files will be known as the SECURITY_DIR.

The easiest way to get your environment setup to run the example
applications is to follow the instructions step by step.  If you chose
not to follow these directions then you are on your own (but I will
help you out as much as possible).

1.) Download and copy all thirdparty tools to SECURITY_DIR/install/thirdparty
    The names of these files must be exact in order for the intallation 
    script to work correctly!

    a.) Ant 1.4.1
        http://jakarta.apache.org/builds/jakarta-ant/release/v1.4.1/bin/
           - jakarta-ant-1.4.1-bin.zip
           - jakarta-ant-1.4.1-optional.jar

    b.) JBoss 2.4.5 Final
        http://sourceforge.net/project/showfiles.php?group_id=22866
           - jboss-2.4.5.zip

    c.) JUnit 3.7
        http://www.junit.org/index.htm
           - junit3.7.zip

    d.) MySQL JDBC Driver
        http://www.mysql.com/downloads/api-jdbc.html
           - mm.mysql-2.0.4-bin.jar

    e.) MySQL Server
        http://www.mysql.com/downloads/mysql-3.23.html
           - Download the server for your platform.

2.) Your SECURITY_DIR/install/thirdparty should look like

    - jakarta-ant-1.4.1-bin.zip
    - jakarta-ant-1.4.1-optional.jar
    - jboss-2.4.5.zip
    - junit3.7.zip
    - mm.mysql-2.0.4-bin.jar
    - mysql-win.zip (or something very similiar... this is the server)

3.) Execute the follow script to install the tools
    SECURITY_DIR/install/install.bat
       - sorry but I did not provide a unix script

    This script 'bootstraps' the ant installation process and then
    invokes an ant script to install the rest of the tools.

    After the script runs you should see something similiar to the following
    output:
    ----------------
    C:\Projects\oci\security\install>install
    Unzipping Ant distribution...
    Copying Ant's optional tasks JAR file...
        1 file(s) copied.
    Using Ant to install remaining tools...
    Buildfile: build.xml

    junit:
        [echo] Installing JUnit 3.7...
        [unzip] Expanding: C:\Projects\oci\security\install\thirdparty\junit3.7.zip
           into C:\Projects\oci\security\tools

    jboss:
        [echo] Installing JBoss 2.4.5 Final...
        [unzip] Expanding: C:\Projects\oci\security\install\thirdparty\jboss-2.4.5.zip
           into C:\Projects\oci\security\tools
        [copy] Copying 1 file to C:\Projects\oci\security\install\jboss-2.4.5\lib\ext
        [copy] Copying 1 file to C:\Projects\oci\security\install\boss-2.4.5\bin

    install:
        [echo]
            JDK Version=1.4.0
            JAVA_HOME=c:\projects\dev\jdk1.4\jre

            Unless you saw error messages, everything is now installed.
            You should set the following environment variables:
                JBOSS_DIST=C:\Projects\oci\security\tools\JBoss-2.4.5
                ANT_HOME=C:\Projects\oci\security\tools\jakarta-ant-1.4.1
                JUNIT_HOME=C:\Projects\oci\security\tools\junit3.7

            Please follow the directions in the readme.txt file on how to
            download and install the MySql Server.

    BUILD SUCCESSFUL
    ----------------

    **** You will also want to update your PATH to include $ANT_HOME\bin ****

4.) Now install the MySQL server

       - extract the contents of the
         SECURITY_DIR/install/thirdparty/mysql-win.zip (or equivalent) and
         install.  (on windows double-click setup.exe)

       - Once the MySql server has been installed you need to start the
         server.  Change to the directory where you installed the MySql server.
         On windows execute the following command:
            bin/mysqld --standalone

Your environment should be setup correctly to start running the examples.  Now
let's deploy our application to JBoss and see if it all works.

1.) Change to the following directory
      - SECURITY_DIR/src/main/scripts
      This is where our small J2EE application lives.

2.) Execute the following command
      - ant clean deploy-all

      You should see the following output (or something similiar)
      ----------------
      C:\Projects\oci\security\src\main\scripts>ant clean deploy-all
      Buildfile: build.xml

      clean:
          [delete] Deleting directory C:\Projects\oci\security\src\main\build
          [delete] Deleting directory C:\projects\oci\security\tools\jboss-2.4.5\conf\oci_security

      deploy-all:
          [echo] +++ Deploying Security MBean...

      prepare:
          [mkdir] Created dir: C:\Projects\oci\security\src\main\build
          [mkdir] Created dir: C:\projects\oci\security\tools\jboss-2.4.5\conf\oci_security
          [copy] Copying 14 files to C:\projects\oci\security\tools\jboss-2.4.5\conf\oci_security

      compile-srp:
          [javac] Compiling 5 source files to C:\Projects\oci\security\src\main\build

      jar-srp:
          [jar] Building jar: C:\Projects\oci\security\src\main\build\srp_db_mbean.jar

      deploy-srp:
          [copy] Copying 1 file to C:\projects\oci\security\tools\jboss-2.4.5\lib\ext

          [echo] +++ Deploying Security EJB...

      prepare:

      compile:
          [javac] Compiling 11 source files to C:\Projects\oci\security\src\main\build

      jar:
          [jar] Building jar: C:\Projects\oci\security\src\main\build\securityEJB.jar

      ear:
          [ear] Building ear: C:\Projects\oci\security\src\main\build\security.ear

      deploy:
          [copy] Copying 1 file to C:\projects\oci\security\tools\jboss-2.4.5\deploy

      BUILD SUCCESSFUL

      Total time: 12 seconds
      ----------------

      *** NOTE: If you do not run deploy-all the first time then the
          SRP Service MBean that I wrote will not get deployed!  This will
          cause weird JNDI 'srp' not bound exceptions.

      *** NOTE: If the MySQL server is not started then JBoss will not
          start correctly because JBoss connects to the database when the
          server starts to build a connection pool.

3.) Change to the SECURITY_DIR/tools/jboss-2.4.5/bin directory and execute
    the following command:

       run-security.bat

       This is a modified batch file as described in section 3 of my
       article.  The only difference is that this script passes in the
       configuration name directory 'oci_security' and adds a security
       policy.

    *** Verify that the server is using the 'oci_security' configuration
        directory.  At the top of the server's console you should see something
        like:

            Using configuration "oci_security"

    Now the server should be started.

4.) From the SECURITY_DIR/src/main/scripts directory execute the
    following command:

        ant unitTests

    You should see something like the following:

    --------------------
    C:\Projects\oci\security\src\main\scripts>ant unitTests
    Buildfile: build.xml

    dbLoader:
        [sql] Executing file: C:\Projects\oci\security\src\main\scripts\data.sql
        [sql] 44 of 44 SQL statements executed successfully

    unitTests:
        [junit] Running com.ociweb.client.unittest.UT_Login
        [junit] log4j:ERROR No appenders could be found for category (org.jboss.security.srp.jaas.SRPLoginModule).
        [junit] log4j:ERROR Please initialize the log4j system properly.
        [junit] Tests run: 5, Failures: 0, Errors: 0, Time elapsed: 16.954 sec
        [junit] Testsuite: com.ociweb.client.unittest.UT_Login
        [junit] Tests run: 5, Failures: 0, Errors: 0, Time elapsed: 16.954 sec
        [junit]
        [junit] Testcase: testSingleLogin took 15.112 sec
        [junit] Testcase: testInvalidUsername took 0.31 sec
        [junit] Testcase: testInvalidUserAndPassword took 0.12 sec
        [junit] Testcase: testInvalidPassword took 0.371 sec
        [junit] Testcase: testTwoThreads took 1.001 sec
        [junit] Running com.ociweb.client.unittest.UT_UserMgr
        [junit] Tests run: 4, Failures: 0, Errors: 0, Time elapsed: 10.475 sec
        [junit] Testsuite: com.ociweb.client.unittest.UT_UserMgr
        [junit] Tests run: 4, Failures: 0, Errors: 0, Time elapsed: 10.475 sec
        [junit]
        [junit] Testcase: testValidUserStatisticsAccess took 8.843 sec
        [junit] Testcase: testInvalidUserStatisticsAccess took 0.671 sec
        [junit] Testcase: testValidUserManagementAccess took 0.551 sec
        [junit] Testcase: testInvalidUserManagementAccess took 0.4 sec
        [junit] Running com.ociweb.client.unittest.UT_CatalogMgr
        [junit] Tests run: 4, Failures: 0, Errors: 0, Time elapsed: 10.365 sec
        [junit] Testsuite: com.ociweb.client.unittest.UT_CatalogMgr
        [junit] Tests run: 4, Failures: 0, Errors: 0, Time elapsed: 10.365 sec
        [junit]
        [junit] Testcase: testValidInventoryAccess took 7.951 sec
        [junit] Testcase: testInvalidInventoryAccess took 0.561 sec
        [junit] Testcase: testValidMakePurchaseAccess took 0.411 sec
        [junit] Testcase: testConcurrentCatalogAccess took 1.442 sec

    BUILD SUCCESSFUL
    -----------------

    *** The Unit Tests may seem slow or not working... this is because
        the SRP authentication is chugging along.  Just wait.  On average it
        will take about 45 seconds to execute all of the tests.

    *** You will also see a Log4J error when running the unit tests.
        You can safely ignore this.

Well hopefully you did not have any problems getting the examples to run.  Feel
free to hack up the examples to learn more about the code.  ;-)

