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
|