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>/<Console-Deploy-URL>
-
Select "Service
Configuration" frame
-
In "Service Configuration"
frame 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
-
Log in to Access Manager
console as amAdminhttp://<host>.<domain>:<port>/<Console-Deploy-URI>.
-
Select the "Identity
Management" tab view and select your organization.
-
Select "Services" from
the "View" menu.
-
Click on "Core" in
the navigation frame under "Authentication".
-
Select "LoginModuleSample" to add it to the list
of highlighted modules in "Organization Authentication Modules".
Make sure "LDAP"
module is also selected, if not you will not be able to login to Access
Manager Console. (Use Control + mouse click to add additional modules).
-
Click on "Save" to
save the changes.
-
Log out
-
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.
|