Appendix F Authentication Framework Changes Between Sun ONE Portal Server 6.0 and Sun ONE Portal Server 6.2

This appendix provides information on the changes to the authentication framework between Sun™ ONE Portal Server 6.0 and Sun™ ONE Portal Server 6.2 service that you need to know for migration purposes. The information in this appendix is not meant to be a replacement for the Javadocs.


Note	All instances of the Sun™ ONE Identity Server 5.1 product refer to what was formerly known as the iPlanet™ Directory Server Access Management Edition 5.1 product.

Authentication Framework

The Sun ONE Portal Server product uses the Sun™ ONE Identity Server authentication framework. The authentication framework has changed considerably between the Sun ONE Identity Server 5.1 release (used by the Sun ONE Portal Server 6.0 product) and Sun ONE Identity Server 6.1 release (used by the Sun ONE Portal Server 6.2 product).

The Sun ONE Identity Server 6.1 authentication framework provides the Authentication Service Provider Interface (SPI) to write custom authentication modules. The Authentication SPI implements the Java™ Authentication and Authorization Service (JAAS) LoginModule API, and provides methods to access the Authentication Service and module configuration properties. The Authentication SPI is defined in the com.sun.identity.authentication.spi package. The Authentication SPI contains the abstract class, AMLoginModule,used for writing pluggable authentication modules. To write an authentication module, you extend the AMLoginModule class. Writers of custom authentication modules need to understand and be familiar with JAAS, especially the Callback mechanism.

Authentication Configuration and Property Files

Authentication modules require several files to enable them to be recognized by the core authentication service and define their service attributes, localization properties, and module properties.

amAuth.xml File

The amAuth.xml file defines the “parent” core authentication service. This file is located in the BaseDir/SUNWam/config/xml directory. Whenever a new authentication service is created, attributes in this file must be modified in order to recognize an authentication module. Refer to Modifying the amAuth.xml File for information on modifying this file.

XML Service File

Each authentication service must have its own service XML file. This file specifies the user and administrator configurable attributes and allows them to be managed using the Sun ONE Identity Server administration console. The name of the XML service file typically follows the format amAuthModuleName.xml (for example, amAuthSafeWord.xml or amAuthLDAP.xml) and is located in the BaseDir/SUNWam/config/xml directory. This is migrated automatically by the Sun ONE Identity Server 6.1 migration script.

Localization Properties File

The localization properties file defines the language-specific screen text for the attribute names for the module. The name of the localization properties file typically follows the format amAuthModuleName.properties (for example, amAuthSafeWord.properties or amAuthLDAP.properties) and is located in the BaseDir/SUNWam/locale directory under sub-directory appropriate to the locale (for example, en_US, or FR).

Authentication Module Configuration File

The authentication module configuration file specifies the authentication module credentials required by an identity (either user, service or application) in order to authenticate to the module. The name of the authentication module configuration file typically follows the format ModuleName.xml (for example, SafeWord.xml or LDAP.xml) and is located in the BaseDir/SUNWam/web-apps/services/config/auth/default directory.

The settings in this file define the user authentication screens properties. In Sun ONE Identity Server 5.1 implementation, this file was a .properties text file (for example, LDAP.properties) that contained certain keywords which were interpreted by the Sun ONE Identity Server 5.1 authentication service to render the screen. In Sun ONE Identity Server 6.1 implementation, this file is now a .xml file (for example, LDAP.xml) that describes the screen properties, data, and credential requirements to send to the authentication UI as JAAS Callbacks.This file needs to be manually translated to the new model, that is, into an XML file. The Auth_Module_Properties.dtd is the DTD file which defines all the different module screen states.

Table F-1shows the changes to the authentication module property types. This three-column table lists the property type in the first column. The second column shows the Sun ONE Identity Server 5.1 property name. The third column shows the Sun ONE Identity Server 6.1 property name.

Table F-1 Authentication Module Properties
Property Type	Sun ONE Identity Server 5.1 Property Name	Sun ONE Identity Server 6.1 Property Name
Screen Number	SCREEN	order=order_number
Page Timeout Value	TIMEOUT	timeout=value
Template Name	HTML	template=template_name
Text Value	TEXT	header=text
User Name	TOKEN	NameCallback
Password	PASSWORD	PasswordCallback
Attribute Name	ATTRIBUTE	Callback (depends on the type of attribute)
Image Name	IMAGE	None (image can be specified in the customized JSP)

For example, the following is a sample LDAP.properties file from Sun ONE Identity Server 5.1:

After conversion to the Sun ONE Identity Server 6.1 format, the file contents would be as follows:

<!DOCTYPE ModuleProperties PUBLIC "=//iPlanet//Authentication Module Properties XML Interface 1.0 DTD//EN"

"jar://com/sun/identity/authentication/Auth_Module_Properties.dtd">

<Callbacks length="2" order="1" timeout="120"

header="This server uses LDAP Authentication" >

</NameCallback>

<Prompt> Password: </Prompt>

</PasswordCallback>

</Callbacks>

Callbacks length="4" order="2" timeout="120" header="Change Password<BR/>#REPLACE#<BR/>" >

<Prompt>Old Password </Prompt>

</PasswordCallback>

<Prompt> New Password </Prompt>

</PasswordCallback>

<Prompt> Confirm Password </Prompt>

</PasswordCallback>

<Prompt> New Password </Prompt>

</PasswordCallback>

<Prompt> Confirm Password </Prompt>

</PasswordCallback>

<Value> Submit </Value>

</OptionValue>

<Value> Cancel </Value>

</OptionValue>

</OptionValues>

</ConfirmationCallback>

</Callbacks>

</ModuleProperties>

Rewriting the Authentication Modules

In Sun ONE Identity Server 6.1, authentication modules extend the AMLoginModule SPI which extends the JAAS LoginModule Interface and provides other convenient methods.

Table F-2 lists the methods in Sun ONE Identity Server 5.1 AuthenticationModule SPI and the equivalent method in Sun ONE Identity Server 6.1 AMLoginModule SPI. This three-column table lists the method in the first column. The second column shows the Sun ONE Identity Server 5.1 method. The third column shows the Sun ONE Identity Server 6.1 method. Refer to Sun ONE Identity Server Javadocs for exact details on these methods.


Note	Since the authentication framework has changed dramatically between Sun ONE Identity Server 5.1 and Sun ONE Identity Server 6.0 some Sun ONE Identity Server 5.1 methods do not have an equivalent in the Sun ONE Identity Server 6.0 JAAS-based framework.

Table F-2 Authentication Module Properties
Method	Sun ONE Identity Server 5.1 Authentication Module SPI	Sun ONE Identity Server 6.1 AMLoginModule SPI
init method Must be implemented by the LoginModule.	void init()	void init(javax.security.auth.Subject.subject, java.util.Map sharedState, java.util.Map options)
LoginModule process method Must be implemented by the LoginModule.	void validate()	int process(javax.security.auth.callback.Callback[] callbacks, int state)
get user id or principal Must be implemented by the LoginModule.	String getUserTokenID	javax.security.Principal getPrincipal()
get all token names for the current authentication state	Properties getAllTokenNames
get all user entered tokens in the current authentication state	String getAllTokensForState()
get all user entered tokens in the specified state	String getAllTokensForState()
get auth level	int getAuthLevel()	int getAuthLevel()
get current state	int getCurrentState()	int getCurrentStatel()
get the HttpServletRequest object	HttpServletRequest get HttpServletRequest()	HttpServletRequest get HttpServletRequest()
get the HttpServletResponse object	HttpServletResponse get HttpServletResponse()	HttpServletResponse get HttpServletResponse()
get the locale	String getLocale()	String getLocale()
get the number of screens	int getNumberOfScreens()
get the number of authentication states for the module	int getNumberOfStates()	int getNumberOfStates()
get the number of tokens in the current authentication state	int getNumberOfTokens()
get the number of tokens for the specified authentication state	int getNumberOfTokensForState(int stateNumber)
get the organization attributes for the organization specified	java.util.Map getOrgProfile(String orgDN)	java.util.Map getOrgProfile(String orgDN) throws javax.security.auth.login.LoginException
get the service template attribute defined for the organization	java.util.Map getOrgServiceTemplate(String orgDN, String serviceName)	java.util.Map getOrgServiceTemplate(String orgDN, String serviceName) throws javax.security.auth.login.LoginException
check if persistent cookie is on or off	boolean getPersistentCookieOn()	boolean getPersistentCookieOn()
return orgDN for this session	String getRequestOrg()	String getRequestOrg()
get service configuration attributes	java.util.Map getServiceConfig(String name)	java.util.Map getServiceConfig(String name) throws javax.security.auth.login.LoginException
get the session ID which is the unique key for this authentication session	String getSessionId()	getSessionId()
get authentication SSO session	SSOToken getSSOSessionId()	SSOToken getSSOSessionId()
get the user entered value for the specified token in the current authentication state	String getToken()
get the user entered value for the specified authentication state	String getToken(int index)	java.security.auth.callback.Callback getCallback(int index) throws javax.security.auth.login.LoginException
get the user entered value for the specified token in the current authentication state	String getToken(String name)
get the user profile for the user specified	AMUser getUserProfile(String userDN)	AMUser getUserProfile(String userDN) throws javax.security.auth.login.LoginException
get the property specified from the user session	Sting getUserSessionProperty(String name)	Sting getUserSessionProperty(String name) throws javax.security.auth.login.LoginException
log out	logout()	AMLoginModule implements the JAAS logout() method
set the authentication level for the session	void setAuthLevel(String authLevel)	boolean setAuthLevel(int auth_level)
set the default URL for the user to redirect to on authentication	void setDefaultURL(String url)	void setLoginSuccessURL(String url) throws javax.security.auth.login.LoginException void setLoginFailureURL(String url) throws javax.security.auth.login.LoginException
set the number of next login screen that will be sent to the user during authentication	void setNextScreen(int num)
set the user’s organization	void setOrg(String orgDN)
turn the persistent cookie on for this auth session	int setPersistentCookieOn()	boolean setPersistentCookieOn()
replace header test on the screen specified	setReplaceText(int screenNumber, int token, String text) setReplaceText(int token, String text)	void replaceCallback(int state, int index, callback) throws javax.security.auth.login.LoginException void replaceHeader(int state, String header) throws javax.security.auth.login.LoginException
set a property in the user session	void setUserSessionProperty(String name, String value)	void setUserSessionProperty(String name, String value) throws javax.security.auth.login.LoginException
get attribute name for the specified callback in the state specified		String getAttribute(int state, int index)
check if a callback is required to have an input		boolean isRequired(int state, int index)
set the failure UserID. This ID is used to log failed authentication is the logs		void setFailureID(String userID)
set attribute values which will be used when authentication service is configured dynamically by user		void setUserAttributes(java.util.Map attribute ValuePairs)
reset callback to original callback for specified state and callback index.		void resetCallback(int state, int index)

Previous Contents Index Next
Sun Java System Portal Server 6 2004Q2 Migration Guide