Sun Java System Portal Server 6 2004Q2 Migration Guide |
Appendix F
Authentication Framework Changes Between Sun ONE Portal Server 6.0 and Sun ONE Portal Server 6.2
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.
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.
This appendix contains the following sections:
Authentication FrameworkThe 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 FilesAuthentication 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.
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">
<ModuleProperties moduleName="LDAP" version="1.0" >
<Callbacks length="2" order="1" timeout="120"
header="This server uses LDAP Authentication" >
<NameCallback>
<Prompt> User Name: </Prompt>
</NameCallback>
<PasswordCallback echoPassword="false" >
<Prompt> Password: </Prompt>
</PasswordCallback>
</Callbacks>
Callbacks length="4" order="2" timeout="120" header="Change Password<BR/>#REPLACE#<BR/>" >
<PasswordCallback echoPassword="false" >
<Prompt>Old Password </Prompt>
</PasswordCallback>
<PasswordCallback echoPassword="false" >
<Prompt> New Password </Prompt>
</PasswordCallback>
<PasswordCallback echoPassword="false" >
<Prompt> Confirm Password </Prompt>
</PasswordCallback>
<Prompt> New Password </Prompt>
</PasswordCallback>
<PasswordCallback echoPassword="false" >
<Prompt> Confirm Password </Prompt>
</PasswordCallback>
<ConfirmationCallback>
<OptionValues>
<OptionValue>
<Value> Submit </Value>
</OptionValue>
<OptionValue>
<Value> Cancel </Value>
</OptionValue>
</OptionValues>
</ConfirmationCallback>
</Callbacks>
</ModuleProperties>
Rewriting the Authentication ModulesIn 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)