An Abstract Class Used for Writing Pluggable Authentication Modules

This API is classified Unstable. For an explanation of this classification, see the manpage attributes(5) in Solaris 2.6. The likelihood that this API will change is very high. Make a backup copy of any file that you are going to edit.

This is an abstract class that can be used to write pluggable authentication modules. Because it is an abstract class authentication, writers must subclass and override the abstract methods init, validate, and getUserTokenId.

How Authentication Works

The HTML for the authentication states is generated dynamically 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/SUNWstnr on the i-Planet server when it is started.

The properties file is of the following form shown in Missing Cross Reference Target

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, one HTML page is sent for each state. In the previous sample SCREENS, the first state sends an HTML page asking the users to enter a token and a password. When the users submit the token and the password, the validate() method is called. Module writers get the tokens, validate them, and return them. The second page is then sent and the validate() routine is again called.

If the module writers throw a LoginException, an authentication failed page is sent to the user. If no exception is thrown, which implies successful completion, the users are redirected to their default page. The TIMEOUT parameter is used to ensure that the users respond in a timely manner. If the time between sending the page in response is greater than the TIMEOUT, a time-out page is sent.

Optional Pages

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

The SetReplace method allows module writers to substitute dynamic text for the token and password accompanying text descriptions.

When multiple pages are sent to the user, the tokens from a previous page may 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.

Using Your Authentication Module

For the i-Planet server to recognize your authentication module, you must add the full class name with package to the /etc/opt/SUNWstnr/platform.conf file after the authenticators = parameter. The reverseproxy.policy file on the i-Planet gateway must also be modified to allow requests to your authentication module. You will find this file on the i-Planet gateway in the directory /opt/SUNWsnrp/policy/. You must restart the reverse proxy server on the i-Planet gateway and the web server on the i-Planet server after you have modified these files.

Each authentication session creates a new instance of your authentication Java class. The reference to the class is released once the authentication session has either succeeded or failed.

Any static data or reference to any static data in your authentication module must be thread safe.

For example, .properties and Java module files, see "Sample Files"" section in this appendix or the /opt/SUNWstnr/sample/auth/com/sun/login/sample on the i-Planet server. /opt is the directory for the default installation. If you have customized your installation, you may have installed this file in another directory.

Constructors

Login

public Login () throws LoginException

If the Login constructor fails, LoginException should be thrown.

Methods

init

public abstract void init() throws LoginException

This method must be overridden. 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 Authenicator

validate

public abstract void validate() throws LoginException

This method must be overridden. It is called once for each authentication page that 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. LoginException should be thrown at some point during the validate() method if authentication has failed. The message in the exception is logged and users are sent an Authentication Failed page. If no exception is thrown, which implies successful completion, and all authentication pages have been sent, the user is authenticated. The abstract method getUserTokenId() is called to get the authenticated name of the user.

Overrides: validate in class Authenticator

getUserTokenId

public abstract String getUserTokenId()

This method must overridden. It is called once after the all authentication pages have been sent to the user.

Overrides: getUserTokenId in class Authenticator

getSessionId

public String getSessionId()

This method returns a unique key for this authentication session.

getCurrentState

public int getCurrentState()

This method returns the current state in the authentication process.

getNumberOfTokens

public int getNumberOfTokens()

This method returns the total number of tokens and passwords in the current authentication state.

getNumberOfTokensForState

public int getNumberOfTokensForState(int stateNumber)

This method 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 String getToken(int index)

This method returns the user-entered value for the specified token in the current authentication state.

getToken

public String[] getToken()

This method returns the user-entered value for the first token in the current authentication state.

getAllTokens

public String[] getAllTokens()

This method returns all the user-entered tokens in the current authentication state.

getAllTokensForState

public String[] getAllTokensForState(int stateNumber)

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

getNumberOfStates

public int getNumberOfStates()

This method returns the number of authentication states for this authentication module.

setReplaceText()

public void setReplaceText(int token,

				String text)

The tokens and passwords have text descriptions for each authentication page. If your module needs to add to these descriptions, this can be done by inserting the keyword into the description. This method can then be used to substitute the specified text with generated dynamic text.

This method should be called for the next state, before returning from the validate method().

setReplaceText

public void setReplaceText(int token,

							String text[])

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

logout

public void logout()

Not implemented. This method is a placeholder. It will be called when a user logs out.