Sun Java System Identity Server 2004Q2
Sample
 
Main Page

JDBC Auth Module

This document explains how to compile, deploy and run the JDBC Auth Module program. 

About JDBC Auth Module

This module enables authentication of users against an external database.The module can leverage container-provided connection pools and has a pluggable password transform for dealing with varying password formats.The module also allows configuration of the SQL statement that is used to retrieve the password in the database.

Steps to compile theJDBC Auth Module program on Solaris

  • Set the following variables in the Makefile. This Makefile is in the same directory ("<install-root>/SUNWam/samples/authentication/spi/jdbc ) as the JDBC Auth Module program files.
    • JAVA_HOME

    • Set this variable to your installation of JDK. The JDK should be newer than JDK 1.3.1.
    • CLASSPATH

    • Set this variable to refer to to the following jars found in the <install-root>/SUNWam/lib directory.
      am_services.jar, am_sdk.jar
      (Note: Include jaas.jar in your classpath if you are using JDK version less than JDK1.4)
    • BASE_CLASS_DIR

    • Set this variable to the directory where all the Sample compiled classes are located.
    • JAR_DIR

    • Set this variable to the directory where the JAR files of the Sample compiled classes will be created.
  • Go to the <install-root>/SUNWam/samples/authentication/spi/jdbc directory and run gmake.

Steps to deploy the JDBC Auth Module program

  • Copy JDBC.jar from JAR_DIR to <install-root>/SUNWam/web-src/services/WEB-INF/lib.
  • Choose appropriate driver which supports JDBC 3.0 API and copy it to your desired location.
  • Update classpath with JDBC.jar in the Web Container from which this sample has to run. For use with Sun ONE Webserver, go to server instance's config directory  /<WS-home-dir>/https-<WS-instance-name>/config/. For Sun ONE App Server <AS-home-dir>/domain/domain1/server1/config/ and update server.xml with new classpath.for all other containers consult their documentation.
  • Copy JDBC.xml from <install-root>/SUNWam/samples/authentication/spi/jdbc to <install-root>/SUNWam/web-src/services/config/auth/default.
  • Redeploy servies war file by running corresponding install script depending upon the web container on which these samples are deployed. for example if samples are deployed on Sun(tm) ONE App Server7.0, run amas70config, for Sun(tm) ONE Web Server run amws61config script found under <install-root>/SUNWam/bin
  • Load amAuthJDBC.xml via amadmin 
    •  cd <install-root>/SUNWam/bin
    • ./amadmin --runasdn uid=amAdmin,ou=People,<default_org>,<root_suffix> --password <password> --schema amAuthJDBC.xml
  • Place amAuthJDBC.properties in <install-root>/SUNWam/locale/

  •  
  • Restart web container (e.g  /<WS-home-dir>/https-<WS-instance-name>/start, /<AS-home-dir>/domains/domain1/server1/bin/start for Web Server and App server respectively) 
Steps to load JDBC Auth module into Identity Server

Using IS Admin Console

  • Login to Identity Server Console as amadmin, using the URL: http://<host>.<domain>:<port>/<Console-Deploy-URL> 
  • Select "Service Configuration" frame "Service Configuration" frame select "Core" within "Authentication" 
  • Add class file name com.iplanet.am.samples.authentication.spi.jdbc.JDBC to "Pluggable Auth Modules Classes"
  • Click on save button to save the changes in console.
Using Commandline (amadmin)
  •  Write a sample.xml file as shown below, which will add JDBC module entry into allowed modules and authenticators list.
    <!--
          Copyright (c) 2003 Sun Microsystems, Inc. All rights reserved
         Use is subject to license terms.
    -->
     
     

     <!DOCTYPE Requests
          PUBLIC "-//iPlanet//iDSAME 5.0 Admin CLI DTD//EN"
         "jar://com/iplanet/am/admin/cli/amAdmin.dtd"
     >

    <Requests>
        <SchemaRequests serviceName="iPlanetAMAuthService"
     SchemaType="Organization">
          <AddChoiceValues>
            <AttributeValuePair>
              <Attribute name="iplanet-am-auth-allowed-modules"/>
              <Value>JDBC</Value>
            </AttributeValuePair>
          </AddChoiceValues>
        </SchemaRequests>

        <SchemaRequests serviceName="iPlanetAMAuthService" SchemaType="Global">
          <AddDefaultValues>
           <AttributeValuePair>
              <Attribute name="iplanet-am-auth-authenticators"/>

     <Value>com.iplanet.am.samples.authentication.spi.jdbc.JDBC</Value>
            </AttributeValuePair>
          </AddDefaultValues>

        </SchemaRequests>
    </Requests>
     

  • Load sample.xml via amadmin 
    • cd <install-root>/SUNWam/bin
    • ./amadmin --runasdn uid=amAdmin,ou=People,<default_org>,<root_suffix> --password <password> --data sample.xml

Setting up the Connection Pools

If you'd like to use connection pooling, do the following: (Instructions are for Sun(tm) ONE Web Server (S1WS) only.  For use with other containers, please consult their documentation)

1) Connect to S1WS's admin server and login

2) Switch to the server on which IS is deployed and click on the Java Tab.

3) Select JDBC Connection Pool and create a new pool. Select your type. For the purposes of this Readme, Other was selected
 

Use the information appropriate to your JDBC driver. For MySQL this reference may help

Here's an example of what was configured for MySQL

General

Pool Name: samplePool 
Data Source Name: com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource


Parameters

serverName: 127.0.0.1
port: 3306
databaseName: test
user: root
password: password


Choose other settings as your environment dictates

Save the Pool


4) Configure the JDBC Resources, by clicking on its button on the left. Choose New
 

Use the following information:

JNDI Name: jdbc/samplePool
Pool Name: samplePool
Enabled: On
 

5) Apply the settings

6) Add the following as the last element of <install-root>/SUNWam/web-src/services/WEB-INF/sun-web.xml

 <resource-ref>
 <res-ref-name>jdbc/samplePool</res-ref-name>
<jndi-name>jdbc/samplePool</jndi-name>
 </resource-ref>
 

7) Add the following as the last element of <install-root>/SUNWam/web-src/services/WEB-INF/web.xml
<resource-ref>
 <description>Primary database</description>
 <res-ref-name>jdbc/samplePool</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
 <res-auth>Container</res-auth>
 </resource-ref>

8) Restart web container (e.g  /<WS-home-dir>/https-<WS-instance-name>/start, /<AS-home-dir>/domain/domain1/server1/bin/start for Web Server and App server respectively) 

Steps to run the JDBC Auth Module program

1) Login to the Identity Server as amAdmin

2) Verify that the JDBC service is available under the Service Management Tab.If not, go back and follow the loading steps according to the instructions listed above

3) Under the Identity Management tab, select the Org for which you'd like to configure JDBC AuthN. Select the Services View for that Org

4) Register the JDBC service

5) Create a new template for the JDBC service by clicking on the arrow next to the newly registed service

6) Modify the parameters as follows (according to your own settings)

  • Connection Type: Choose the appropriate connection type based on whether or not you configured a connection pool
  • Connection Pool JNDI Name: If you created a pool, put: java:comp/env/jdbc/samplePool
  • JDBC Driver: If you didn't configure a pool, place the appropriate class name here. For MySQL use: com.mysql.jdbc.Driver
  • JDBC URL: If you didn't configure a pool, place the appropriate jdbc URL here.  MySQL Example: jdbc:mysql://127.0.0.1:3306/test
  • User to connect to database:  If you didn't configure a pool, provide a valid database username.
  • Password to connect to database:  If you didn't configure a pool, provide a valid database password
  • Password to connect to database (confirm): Re-enter the password
  • Password Column in database:  This is the column name of password field in the database.
  • Prepared Statement:  Modify the prepared statement so only the password field is returned from your database
For a sample table of 'auth', with a 'userName' column and 'password' column, the following was done

Sample:
select PASSWORD_COLUMN from TABLE where USERNAME_COLUMN = ?

Sample after the statement is customized to use a table named 'auth':
select password from auth where userName = ?

Notice question marks were not modified....this is because it will be replaced via other inputs. The question mark is the is the UID provided by the user

  • Class to transform password syntax: This is a pluggable class which implements a transform on your password.The default is cleartext, although you can provide a plugin which might first hash the password the user provided before comparing it to the result from the database
The default is com.sun.identity.authentication.modules.jdbc.passwordsyntax.ClearTextTransform which will simply return the same clear text value. If you wish to implement a new transform, here is the interface (and it is provided in the /src/ directory)
/*
 * JDBCPasswordSyntaxTransform.java
 */

package com.iplanet.am.samples.authentication.spi.jdbc.passwordsyntax;

public interface JDBCPasswordSyntaxTransform{

String transform(String input) throws com.sun.identity.authentication.spi.AuthLoginException; 
}

 
  • Authentication Level:Set this to the appropraite level
7) Save the service and click on the core service

8) Select JDBC as an AuthN module for that service (Holding Control will allow you to select multiple) in the Organization Authentication Modules list. 
Note : Do not de-select LDAP auth module 

9) Save the core service and Logout.

10) You should be all set - login with http(s)://servername.domain:port/amserver/UI/Login?module=JDBC or org=OrgName, or use no params if JDBC auth is the default service