Main Page
Login Module Sample
This file explains how to write, compile,
deploy and run the Login Module
Sample program.
PRODUCT_DIR setting on different
Platforms:
- Solaris Sparc/x86 : PRODUCT_DIR =
<install_root>/SUNWam
- Linux :
PRODUCT_DIR = <install_root>/sun/identity
- W2K :
PRODUCT_DIR = <install_root>
How to Write Sample Login Module using
AMLoginModule SPI (Service Provider Interface):
-
Create Module Properties File
Create Module properties XML file with the
same name of the class (no package name) and have the extension .xml.
Based on this configuration file, Authentication UI will dynamically
generate page.
Note : create XML file with above naming
convention even if no states required
Page states can be defined in module
properties file as shown below, each Callbacks Element corresponds to
one login page state When an authentication process is invoked, there
will be Callback[] generated from user's Login Module for each state.
All login state starts with 1, then module control the login process,
and decides what's the next state to go.
Sample Module Properties file file :
To know how to define , construct and initiate
callback , refer Auth_Module_Properties.dtd which can be found in
<PRODUCT_DIR>/dtd directory.
<ModuleProperties moduleName="LoginModuleSample" version="1.0" > <Callbacks length="2" order="1" timeout="60" header="This is a sample login page" > <NameCallback> <Prompt> User Name </Prompt> </NameCallback> <NameCallback> <Prompt> Last Name </Prompt> </NameCallback> </Callbacks> <Callbacks length="1" order="2" timeout="60" header="You made it to page 2" > <PasswordCallback echoPassword="false" > <Prompt> Just enter any password </Prompt> </PasswordCallback> </Callbacks> </ModuleProperties>
In the sample module configuration shown
above, page state one has two Callbacks, first callback is for user ID
and second is for Last Name. When the user fills in the Callbacks,
those Callback[] will be sent to the module, where the module writer
gets the submitted Callbacks, validates them and returns . module
writer will set the next page state to 2. Page state two has one
Callback to request user to enter password. The process() routine is
again called after user submits the Callback[]. If the module writer
throws an LoginException, an 'authentication failed' page will be sent
to the user. If no exception is thrown, the user will be redirected to
their default page.
-
Write SamplePrincipal.java
After creating module configuration xml file next step
is to write a Sample Principal class which implements
java.security.Principal and the constructor takes username of the user
as an argument. If authentication is successful, module will return
this principal to Authentication framework which will populate a
Subject with a SamplePrincipal representing the user.
-
Write Sample LoginModule
Login Module writers must subclass
AMLoginModule class and implement init(), process(), getPrincipal()
methods. AMLoginModule is an abstract class which implements JAAS
LoginModule, it provides methods to access Sun Java System Access
Manager services and the module XML configuration. Refer javadocs
for
complete list of methods.
public void init(Subject subject,Map sharedState, Map options);
This is an abstract method, Module writer
should
implemet to initialize this LoginModule with the relevant information.
If this LoginModule does not understand any of the data stored in
sharedState or options parameters, they can be ignored. This method is
called by a AMLoginModule after this SampleLoginModule has been
instantiated,
and prior to any calls to its other public methods. The method
implementation should store away the provided arguments for future use.
The init
method may additionally peruse the provided sharedState to determine
what additional authentication state it was provided by other
LoginModules,
and may also traverse through the provided options to determine what
configuration options were specified to affect the LoginModule's
behavior.
It may save option values in variables for future use.
public int process(javax.security.auth.callback.Callback[] callbacks, int state) throws LoginException;
The process method is called to
authenticate a Subject. This method implementation should perform the
actual authentication. For example, it may cause prompting for a user
name and password, and then attempt to verify the password against a
password database. If your LoginModule requires some form of user
interaction (retrieving a user name and password, for example), it
should not do so directly. That is because there are various ways of
communicating with a user, and it is desirable for LoginModules to
remain independent of the different types of user interaction. Rather,
the LoginModule's process method should invoke the handle method of the
the CallbackHandler passed to this method to perform the user
interaction and set appropriate results, such as the user name and
password and the AMLoginModule internally passes the UI an array of
appropriate Callbacks, for example a NameCallback for the user name and
a PasswordCallback for the password, and the
UI performs the requested user interaction and sets appropriate values
in the Callbacks.
Consider
following steps while writing preocess() method.
-
Perform the
authentication.
-
If
Authentication succeeded, save the principal who has successfully
authenticated.
-
Return -1 if
authentication succeeds, or throw a LoginException such as
AuthLoginException if authentication fails or return relevant state
specified in module configuration XML file
-
If multiple
states are available to the user, the Callback array from a previous
state may be retrieved by using the getCallbak(int state) methods. The
underlying login module keeps the Callback[] from the previous states
until
the login process is completed.
-
If a module writer need to substitute
dynamic text in next state, the writer could use the getCallback()
method to get the Callback[] for the next state, modify the output text
or prompt, then call replaceCallback() to update the Callback array.
This allows a module writer to dynamically generate challenges,
passwords or user IDs. Note: Each authentication session will create a
new instance of your Login Module Java class. The reference to the
class will be released once the authentication session has either
suceeded or failed. It is important to note that any static data or
reference to any static data in your Login module must be
thread-safe.
public Principal getPrincipal();
This method should be called once at the
end of a successful authentication session. A login session is deemed
successful when all pages in the Module properties XML file have been
sent and the module has not thrown an exception. The method retrieves
the authenticated token string that the authenticated user will be
known by in the Access Manager environment.
How to Compile and Run the Sample:
Steps to compile the Login Module Sample program
Follow the steps given below to compile the
sample found
under <PRODUCT_DIR>/samples/authentication/spi/providers.Skip
this
step if you are writing your own Custom Authentication
module based on AMLoginModule SPI or Pure JAAS module.
-
Set the following
environment variables. These variables will be used to run the gmake
command. You can also set these variables in the Makefile. This
Makefile is in is in
,<PRODUCT_DIR>/samples/authentication/spi/providers.
-
JAVA_HOME
Set this variable to your installation of JDK. The
JDK should be version 1.3.1_06 or higher.
-
CLASSPATH
Set this variable to refer to am_services.jar which
can be found in the <PRODUCT_DIR>/lib directory. (Note: Include
jaas.jar in your classpath if you are using JDK version less than
JDK1.4)
-
BASE_DIR
Set this variable to the directory where the Access
Manager is installed.
-
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
<PRODUCT_DIR>/samples/authentication/spi/providers directory and
run gmake.
Steps
to "deploy" the Login Module Sample program
-
Copy
LoginModuleSample.jar from JAR_DIR to
<PRODUCT_DIR>/web-src/services/WEB-INF/lib.
-
Copy
LoginModuleSample.xml from
<<PRODUCT_DIR>/samples/authentication/spi/providers to
<PRODUCT_DIR>/web-src/services/config/auth/default.
-
Redeploy amserver.war file.
Steps to load Login
Module Sample into Access Manager
-
Using Access
Manager Admin Console.
-
Login to
Access Manager Console as amadmin, using the URL: http://<host>.<domain>:<port>/<Service-Deploy-URI>/UI/Login
-
Click on
"Configuration" tab.
-
Select "Core"
within "Authentication"
-
Add class
file name
com.iplanet.am.samples.authentication.spi.providers.LoginModuleSample
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 LoginModuleSample auth
module entry into allowed modules, anauthenticators 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="Global">
<AddDefaultValues>
<AttributeValuePair>
<Attribute name="iplanet-am-auth-authenticators"/>
<Value>com.iplanet.am.samples.authentication.spi.providers.LoginModuleSample</Value>
</AttributeValuePair>
</AddDefaultValues>
</SchemaRequests>
</Requests>
- Load sample.xml via amadmin
<AMADMIN> --runasdn
uid=amAdmin,ou=People,<root_suffix> --password <password>
--data sample.xml
where,
Solaris Sparc/x86 : AMADMIN
= <PRODUCT_DIR>/bin/amadmin
W2K
: AMADMIN =
<PRODUCT_DIR>\bin\amadmin
Steps to run the Login
Module Sample program
-
Enter URL
http://<host>.<domain>:<port>/<Service-Deploy-URI>/UI/Login?module=LoginModuleSample.
(If you choose to use an organization other than the default, please
specify that in the URL using the 'org' parameter.)
On Windows2000
Steps
to compile the Login Module Sample program on Windows2000
-
Set the following
environment variables. These variables will be used to run the make
command. You can also set these variables in the Makefile. This
Makefile is in
the same directory
(<install-root>\samples\authentication\spi\providers) as the
Login Module Sample program files.
-
JAVA_HOME
Set this variable to your installation of JDK. The
JDK should be version 1.3.1_06 or higher.
-
BASE
Set this variable to <install-root>
-
CLASSPATH
Set this variable to refer to am_services.jar which
can be found in the <install-root>\lib directory. (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>\samples\authentication\spi\providers directory and
run make.
Steps
to deploy the Login Module Sample program
-
Copy
LoginModuleSample.xml from
<install-root>\samples\authentication\spi\providers to
<install-root>\web-src\services\config\auth\default.
-
Restart web
container
-
WebServer -
\<WS-home-dir>\https-<WS-instance-name>\restart
- Applicaton Server -
\<AppServer-home-dir>\domains\<domain
name>\<server_instance>\bin\restartserv
Steps to load Login Module Sample into Access
Manager
Refer to Steps to load Login
Module Sample into Access Manager section in this document.
Steps
to "run" the Login Module Sample program
Refer to Steps to "run" the Login
Module Sample program section of this document.
|