Main Page
Login Module Sample
This file explains how to write, compile,
deploy
and run the Login Module Sample program.
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 at <install-root>/SUNWam/dtd
<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 and implement init(),
process(), getPrincipal() methods. To the AMLoginModule class. AMLoginModule
is an abstract class which implements JAAS LoginModule, it provides methods
to access Sun Java System Identity Server 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 succeeded 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 Identity Server environment.
How to Compile and Run the Sample:
On Solaris
Steps to compile the Login Module Sample program on Solaris
Follow the steps given below to compile the sample found under
<install-root>/SUNWam/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 the same directory (<install-root>/SUNWam/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.
-
CLASSPATH
Set this variable to refer to am_services.jar which can be found
in the <install-root>/SUNWam/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 Identity Server 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 <install-root>/SUNWam/samples/authentication/spi/providers
directory and run gmake.
Steps to "deploy" the Login Module Sample program
-
Copy LoginModuleSample.jar from JAR_DIR to <install-root>/SUNWam/web-src/services/WEB-INF/lib.
-
Update classpath with LoginModuleSample.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 LoginModuleSample.xml from <install-root>/SUNWam/samples/authentication/spi/providers
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
-
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 Login Module Sample 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
-
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="Organization">
<AddChoiceValues>
<AttributeValuePair>
<Attribute
name="iplanet-am-auth-allowed-modules"/>
<Value>LoginModuleSample</Value>
</AttributeValuePair>
</AddChoiceValues>
</SchemaRequests>
<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
-
cd <install-root>/SUNWam/bin.
-
/amadmin --runasdn uid=amAdmin,ou=People,<default_org>,<root_suffix>
--password <password> --data sample.xml
Steps to run the Login Module Sample program
-
Log in to Identity Server 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".
-
Add "LoginModuleSample" 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 Identity Server 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.jar from JAR_DIR to <install-root>\web-src\services\WEB-INF\lib
-
update classpath with LoginModuleSample.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\.
and update server.xml with new classpath.
-
Copy LoginModuleSample.xml from <install-root>\samples\authentication\spi\providers
to <install-root>\web-src\services\config\auth\default.
-
Restart web container (e.g /<WS-home-dir>/https-<WS-instance-name>/start)
Steps to load Login Module Sample 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
-
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="Organization">
<AddChoiceValues>
<AttributeValuePair>
<Attribute
name="iplanet-am-auth-allowed-modules"/>
<Value>LoginModuleSample</Value>
</AttributeValuePair>
</AddChoiceValues>
</SchemaRequests>
<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
-
cd <install-root>/SUNWam/bin.
-
/amadmin --runasdn uid=amAdmin,ou=People,<default_org>,<root_suffix>
--password <password> --data sample.xml
Steps to "run" the Login Module Sample program
-
Log in to Identity Server console as amAdmin, enter URL http://<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".
-
Add "LoginModuleSample" 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 Identity Server 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.)
|