com.iplanet.portalserver.auth.server
Class Login

java.lang.Object
  |
  +--com.iplanet.portalserver.auth.server.Authenticator
        |
        +--com.iplanet.portalserver.auth.server.Login

public abstract class Login

extends com.iplanet.portalserver.auth.server.Authenticator

An abstract class used for writing pluggable athentication modules. Because it is an abstract class authentication writers must subclass and override the abstract methods init, validate, and getUserTokenId.

The HTML for the authentication states is dynamically generated based on the parameters set in the configuration file for the authentication module developed. There must be a configuration file with the name of the class (no package name) and the extension .properties. This file must reside in /etc/opt/SUNWips/auth when the server is is started.

The properties file is of the following form:

SCREEN
TIMEOUT 60
TEXT Sample Login Page
TOKEN Enter User Name:
PASSWORD Enter User Password:

SCREEN
TIMEOUT 30
TEXT Sample Login Page 2
TOKEN Enter Favorite Color
TOKEN Enter Secret Pin Number
PASSWORD Enter Challenge form

Each SCREEN entry corresponds to one authentication state or authentication HTML page. When an authentication session is invoked there will be one HTML page sent for each state. In the sample SCREENS above the first state will send an HTML page asking the user to enter a token and a password. When the user submits, the validate() method will be called. The module writer gets the tokens, validates them and returns. The second page is then sent, the validate() routine is again called. If the module writer throws a LoginException, a authentication failed page will be sent to the user. If no exception is thrown the user will be redirected to their default page. The TIMEOUT parameter is used to ensure that the user responds in a timely manner. If the time between sending the page in response is greater then the TIMEOUT, a timeout page will be sent.

There are also optional HTML and IMAGE parameters for each page. The HTML parameter allows the module writer to use a custom HTML page for the authentication screens. The IMAGE allows the writer to display a custom background image on each page.

The tag allows a module write to substitute dynamic text for the token and password accompanying text descriptions. This allows a module writer to dynamically generate challenges or passwords. The setReplaceText methods is used in the validate method to add this dynamic text.

When multiple pages are sent to the user, the tokens from a previous page my be retrieved by using the getTokenForState methods. Each page is referred to as a state. The underlying authentication module keeps the tokens from the previous states until the authentication is completed.

For your authentication module to be recognized by the platform you must add your module to the iwtAuth-authenticators and iwtAuth-authMenu attributes.

Each authentication session will create a new instance of your authentication Java class. The reference to the class will be released once the authentication session has either suceeded or or failed. It is important to note that any static data or reference to any static data in your authentication module must be thread safe.

For a complete sample please refer to /opt/SUNWips/sample/auth_modules

Constructor Summary

Login()
Login constructor.

Method Summary

java.util.Properties	getAllTokenNames() Returns all of the token names for the current authentication state
java.lang.String[]	getAllTokens() Returns all the user entered tokens in the current authentication state.
java.lang.String[]	getAllTokensForState(int stateNumber) Returns all the user entered tokens in the specified authentication state.
Profile	getApplicationProfile(java.lang.String name)
int	getAuthLevel()
int	getCurrentState() Returns the current state in the authentication process.
Profile	getDomainProfile(java.lang.String name)
javax.servlet.http.HttpServletRequest	getHttpServletRequest() Returns the request object for the HttpServletRequest object which initiated the call to this module.
javax.servlet.http.HttpServletResponse	getHttpServletResponse() Returns the HttpServletResponse object for the servlet request which initiated the call to this module.
java.lang.String	getLocale()
int	getNumberOfStates() Returns the number of authentication states for this authentication module.
int	getNumberOfTokens() Returns the total number of tokens and passwords in the current authentication state.
int	getNumberOfTokensForState(int stateNumber) Returns the total number of tokens and passwords for the given authentication state.
boolean	getPersistentCookieOn()
java.lang.String	getRequestDomain()
Session	getSession()
java.lang.String	getSessionId() Returns a unique key for this authentication session.
java.lang.String	getToken() Returns the user entered value for the first token in the current authentication state.
java.lang.String	getToken(int index) Returns the user entered value for the specified token in the current authentication state.
java.lang.String	getToken(java.lang.String name) Returns the user entered value for the specified token in the current authentication state.
Profile	getUserProfile(java.lang.String name)
java.lang.String	getUserSessionProperty(java.lang.String name) Gets the property from the user session.
abstract java.lang.String	getUserTokenId() This method must be overriden.
abstract void	init() This method must be overriden.
void	logout()
int	setAuthLevel(int auth_level) Attempt to set the AuthLevel for this session.
void	setDefaultURL(java.lang.String url) Sets the the default URL for the user.
void	setDomain(java.lang.String domain)
void	setNextScreen(int num)
int	setPersistentCookieOn() Attempt to set the Persistent Cookie for this session.
void	setReplaceText(int screenNumber, int token, java.lang.String text)
void	setReplaceText(int token, java.lang.String text) The tokens and passwords have text descriptions for each authentication page.
void	setReplaceText(int token, java.lang.String[] text) Same as setReplaceText(), but allows replacement of of multiple tokens.
void	setUserSessionProperty(java.lang.String name, java.lang.String value) Sets a property in the user session.
abstract void	validate() This method must be overriden.

Methods inherited from class com.iplanet.portalserver.auth.server.Authenticator

executeLogin, getName, loadModuleProperties, setWorkerClass

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Login

public Login()
      throws LoginException

Login constructor.

Throws:

LoginException - Exception should be thrown when the constructor has failed.

Method Detail

init

public abstract void init()
                   throws LoginException

This method must be overriden. It is called each time an authentication session is started. If the initialization of the module fails the LoginException should be thrown.

Overrides:

init in class com.iplanet.portalserver.auth.server.Authenticator

Throws:

LoginException - Exception should be thrown when the authentication module initialization has failed.

validate

public abstract void validate()
                       throws LoginException

This method must be overriden. Called once for each authentication page which is specified in the authentication modules properties file. The various getToken methods may be used to get the values for the user entered tokens and passwords. The LoginException should be thrown at some point during the validate() method if authentication has failed. The message in the exception will be logged and the user will be sent an Authentication Failed page. If no exception is thrown and all authentication pages have been sent, the user is authenticated. The abstract method getUserTokenId() will be called to get the authenticated name of the user.

Overrides:

validate in class com.iplanet.portalserver.auth.server.Authenticator

Throws:

LoginException - Exception should be thrown when the user has failed authentication.

getUserTokenId

public abstract java.lang.String getUserTokenId()

This method must be overriden. Called once after the all authentication pages have been sent to the user.

Overrides:

getUserTokenId in class com.iplanet.portalserver.auth.server.Authenticator

getHttpServletRequest

public javax.servlet.http.HttpServletRequest getHttpServletRequest()

Returns the request object for the HttpServletRequest object which initiated the call to this module.

getHttpServletResponse

public javax.servlet.http.HttpServletResponse getHttpServletResponse()

Returns the HttpServletResponse object for the servlet request which initiated the call to this module. The servlet response object will be the response to the HttpServletRequest received by the the authentication module.

getSessionId

public java.lang.String getSessionId()

Returns a unique key for this authentication session. This key will be unique throughout an entire Webtop installtion.

getCurrentState

public int getCurrentState()

Returns the current state in the authentication process.

getNumberOfTokens

public int getNumberOfTokens()

Returns the total number of tokens and passwords in the current authentication state.

getNumberOfTokensForState

public int getNumberOfTokensForState(int stateNumber)

Returns the total number of tokens and passwords for the given authentication state. This method may be used to get token values from previous authentication states.

getToken

public java.lang.String getToken(java.lang.String name)

Returns the user entered value for the specified token in the current authentication state.

getToken

public java.lang.String getToken(int index)

Returns the user entered value for the specified token in the current authentication state.

getToken

public java.lang.String getToken()

Returns the user entered value for the first token in the current authentication state.

getAllTokenNames

public java.util.Properties getAllTokenNames()

Returns all of the token names for the current authentication state

getAllTokens

public java.lang.String[] getAllTokens()

Returns all the user entered tokens in the current authentication state.

getAllTokensForState

public java.lang.String[] getAllTokensForState(int stateNumber)

Returns all the user entered tokens in the specified authentication state.

getNumberOfStates

public int getNumberOfStates()

Returns the number of authentication states for this authentication module.

setReplaceText

public void setReplaceText(int token,
                           java.lang.String text)

The tokens and passwords have text descriptions for each authentication page. If your module needs to generate dynamic text to add to these descriptions this may be accomplished by inserting the keyword into the description. This method may then be used to substitute with the specified text. This method should be called for the next state, prior to returning from the validate method().

setReplaceText

public void setReplaceText(int screenNumber,
                           int token,
                           java.lang.String text)

setReplaceText

public void setReplaceText(int token,
                           java.lang.String[] text)

Same as setReplaceText(), but allows replacement of of multiple tokens.

setNextScreen

public void setNextScreen(int num)

getDomainProfile

public Profile getDomainProfile(java.lang.String name)
                         throws LoginException

getLocale

public java.lang.String getLocale()
                           throws LoginException

getApplicationProfile

public Profile getApplicationProfile(java.lang.String name)
                              throws LoginException

getUserProfile

public Profile getUserProfile(java.lang.String name)
                       throws LoginException

getSession

public Session getSession()
                   throws LoginException

getRequestDomain

public java.lang.String getRequestDomain()

logout

public void logout()

setDomain

public void setDomain(java.lang.String domain)
               throws LoginException

setAuthLevel

public int setAuthLevel(int auth_level)
                 throws LoginException

Attempt to set the AuthLevel for this session. Can be called from any state in the auth module, but the value passed must be in the list of valid values (iwtAuth-authLevelList) and be less than the maximum allowed (iwtAuth-maxAuthLevel). If setAuthLevel returns, then the AuthLevel was set successfully; otherwise it throws a LoginException.

getAuthLevel

public int getAuthLevel()

setPersistentCookieOn

public int setPersistentCookieOn()

Attempt to set the Persistent Cookie for this session. Can be called from any state in the auth module. It will return whether AuthD will add the persistent cookie (name is specified in the /etc/opt/SUNWips/platform.conf:ips.pcookie.name property) when authentication is successful (0), or if the persistent cookie mode attribute is not set for the domain (1).

getPersistentCookieOn

public boolean getPersistentCookieOn()

setUserSessionProperty

public void setUserSessionProperty(java.lang.String name,
                                   java.lang.String value)
                            throws LoginException

Sets a property in the user session.

Parameters:

name - The property name.

value - The property value.

getUserSessionProperty

public java.lang.String getUserSessionProperty(java.lang.String name)
                                        throws LoginException

Gets the property from the user session.

Parameters:

name - The property name.

Returns:

The property value.

setDefaultURL

public void setDefaultURL(java.lang.String url)
                   throws LoginException

Sets the the default URL for the user. This method doesn't change the default URL in the user's profile. When the user authenticates successfully, This URL will be used by the auth for the redirect.