com.sun.identity.authentication

Class AuthContext

java.lang.Object

com.sun.identity.authentication.AuthContext

All Implemented Interfaces:

Serializable

public class AuthContext
extends Object
implements Serializable

The AuthContext provides the implementation for authenticating users.

A typical caller instantiates this class and starts the login process. The caller then obtains an array of Callback objects, which contains the information required by the authentication plug-in module. The caller requests information from the user. On receiving the information from the user, the caller submits the same to this class. While more information is required, the above process continues until all the information required by the plug-ins/authentication modules, has been supplied. The caller then checks if the user has successfully been authenticated. If successfully authenticated, the caller can then get the Subject and SSOToken for the user; if not successfully authenticated, the caller obtains the AuthLoginException.

The implementation supports authenticating users either locally i.e., in process with all authentication modules configured or remotely to an authentication service/framework. (See documentation to configure in either of the modes).

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	AuthContext.IndexType The class IndexType defines the possible kinds of "objects" or "resources" for which an authentication can be performed.
static class	AuthContext.Status The class Status defines the possible authentication states during the login process.

Field Summary

Fields

Modifier and Type	Field and Description
protected static Debug	authDebug
protected static ResourceBundle	bundle
static String	localAuthServiceID Variables for local AuthService identifier
boolean	localFlag Variables for checking auth service is running local

Constructor Summary

Constructors

Constructor and Description
AuthContext(SSOToken ssoToken) Constructs an instance of AuthContext for a given organization name, or sub organization name contained in the single sign on token.
AuthContext(SSOToken ssoToken, boolean forceAuth) Constructs an instance of AuthContext for a given organization name, or sub organization name contained in the single sign on token.
AuthContext(String orgName) Constructs an instance of AuthContext for a given organization name or sub organization name.
AuthContext(String orgName, String nickName) Constructs an instance of AuthContext for a given organization name, or sub organization name and a nick name for the certificate to be used in SSL handshake if client authentication is turn on in the server side.
AuthContext(String orgName, String nickName, URL url) Constructs an instance of AuthContext for a given organization name, or sub organization name, a nick name for the certificate to be used in SSL handshake if client authentication is enabled on the server side and the OpenAM URL.
AuthContext(String orgName, URL url) Constructs an instance of AuthContext for a given organization name, or sub organization name and the OpenAM server URL.

Method Summary

Modifier and Type	Method and Description
void	abort() Terminates an ongoing login call that has not yet completed.
protected void	checkAndSetLoginStatus()
protected static void	checkForException(Document document)
AuthContextLocal	getAuthContextLocal()
protected String	getAuthenticationHandle(Document document)
String	getAuthIdentifier() Returns the current Auth Identifier of the authentication process as String Session ID.
protected static Callback[]	getCallbacks(Document document, boolean noFilter)
String	getClientHostName() Returns the client's hostname or IP address as set by setClientHostName
Map	getCookieTable() Returns a Map object that that contains cookies set by AM server
String	getErrorCode() Returns error code.
String	getErrorMessage() Returns the error message.
String	getErrorTemplate() Returns the error template.
String	getFailureURL() Returns the Failure Login URL for the authenticating user.
Locale	getLocale() Returns locale preference set in AuthConext
String	getLockoutMsg() Returns the account lockout message.
AuthLoginException	getLoginException() Returns login exception, if any, during the authentication process.
Set	getModuleInstanceNames() Returns authentication module/s instances (or plugins) configured for a organization, or sub-organization name that was set during the AuthContext constructor.
String	getOrganizationName() Returns the the organization name that was set during the AuthContext constructor.
javax.servlet.http.HttpServletRequest	getRemoteRequest() Fetches the remote request from the context
javax.servlet.http.HttpServletResponse	getRemoteResponse() Fetches the remote response from the context
Callback[]	getRequirements() Returns an array of Callback objects that must be populated by the user and returned back.
Callback[]	getRequirements(boolean noFilter) Returns an array of Callback objects that must be populated by the user and returned back.
SSOToken	getSSOToken() Returns the Single-Sign-On (SSO) Token for the authenticated user.
AuthContext.Status	getStatus() Returns the current status of the authentication process as AuthContext.Status.
Subject	getSubject() Returns the set of Principals or Subject the user has been authenticated as.
protected static Subject	getSubject(Document document)
String	getSuccessURL() Returns the Successful Login URL for the authenticated user.
protected static String	getXMLforSubject(Subject subject)
boolean	hasMoreRequirements() Returns true if the login process requires more information from the user to complete the authentication.
boolean	hasMoreRequirements(boolean noFilter) Returns true if the login process requires more information from the user to complete the authentication.
boolean	isLockedOut() Returns true if account is lock out.
void	login() Starts the login process for the given AuthContext object.
void	login(AuthContext.IndexType type, String indexName) Starts the login process for the given AuthContext object identified by the index type and index name.
SSOToken	login(AuthContext.IndexType type, String indexName, Callback[] userInfo) Starts the login process for the given AuthContext object identified by the index type and index name and also completes the login process by submitting the given User credentials in the form of Callbacks.
void	login(AuthContext.IndexType type, String indexName, String locale) Starts the login process for the given AuthContext object identified by the index type and index name.
void	login(AuthContext.IndexType indexType, String indexName, String[] params) Starts the login process for the given AuthContext object identified by the index type and index name with default parameters.
void	login(AuthContext.IndexType indexType, String indexName, String[] params, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
void	login(AuthContext.IndexType indexType, String indexName, String[] params, Map envMap) Starts the login process for the given AuthContext object identified by the index type and index name with certain parameters and environment map.
void	login(AuthContext.IndexType indexType, String indexName, String[] params, Map envMap, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
void	login(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Starts the login process for the given AuthContext object.
void	logout() Logs out the user and also invalidates the single sign on token associated with this AuthContext.
void	logoutUsingTokenID() Logs out the user and also invalidates the single sign on token associated with this AuthContext.
protected Document	processRequest(String xmlRequest)
void	reset() Resets this instance of AuthContext object, so that a new login process can be initiated.
protected void	sendQueryInformation(String reqInfo)
static void	setCertDBPassword(String password) Sets the password for the certificate database.
void	setClientHostName(String hostname) Sets the client's hostname or IP address.This could be used by the policy component to restrict access to resources.
void	setLocale(Locale loc) Sets locale based on user locale preferemce.
void	submitRequirements(Callback[] info) Submits the populated Callback objects to the authentication plug-in modules.
void	submitRequirements(Callback[] info, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)

Methods inherited from class java.lang.Object

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

Field Detail

authDebug

protected static Debug authDebug

bundle

protected static ResourceBundle bundle

localFlag

public boolean localFlag

Variables for checking auth service is running local

localAuthServiceID

public static String localAuthServiceID

Variables for local AuthService identifier

Constructor Detail

AuthContext

public AuthContext(String orgName)
            throws AuthLoginException

Constructs an instance of AuthContext for a given organization name or sub organization name. This organization or sub-organization name must be either "/" separated ( where it starts with "/" ) , DN , Domain name or DNS Alias Name.

Caller would then use login to start the authentication process and use getRequirements() and submitRequirements() to pass the credentials needed for authentication by the plugin authentication modules. The method getStatus() returns the authentication status.

Parameters:

orgName - Name of the user's organization.

Throws:

AuthLoginException - if AuthContext creation fails. This exception is kept for backward compatibility only.

AuthContext

public AuthContext(String orgName,
                   URL url)
            throws AuthLoginException

Constructs an instance of AuthContext for a given organization name, or sub organization name and the OpenAM server URL. This organization or sub-organization name must be either "/" separated ( where it starts with "/" ) , DN , Domain name or DNS Alias Name. And the url should specify the OpenAM server's protocol, host name, and port number, for example : http://daye.red.iplanet.com:58080 Caller would then use login to start the authentication process and use getRequirements() and submitRequirements() to pass the credentials needed for authentication by the plugin authentication modules. The method getStatus() returns the authentication status.

Parameters:

orgName - name of the user's organization

url - URL of the OpenAm instance to talk to

Throws:

AuthLoginException - if AuthContext creation fails. This exception is kept for backward compatibility only.

AuthContext

public AuthContext(String orgName,
                   String nickName)
            throws AuthLoginException

Constructs an instance of AuthContext for a given organization name, or sub organization name and a nick name for the certificate to be used in SSL handshake if client authentication is turn on in the server side. This organization or sub-organization name must be either "/" separated ( where it starts with "/" ) , DN , Domain name or DNS Alias Name. This constructor would be mainly used for the Certificate based authentication. If the certificate database contains multiple matching certificates for SSL, this constructor must be called in order for the desired certificate to be used for the Certificate based authentication. Caller would then use login to start the authentication process and use getRequirements() and submitRequirements() to pass the credentials needed for authentication by the plugin authentication modules. The method getStatus() returns the authentication status.

Parameters:

orgName - name of the user's organization

nickName - nick name for the certificate to be used

Throws:

AuthLoginException - if AuthContext creation fails. This exception is kept for backward compatibility only.

AuthContext

public AuthContext(String orgName,
                   String nickName,
                   URL url)
            throws AuthLoginException

Constructs an instance of AuthContext for a given organization name, or sub organization name, a nick name for the certificate to be used in SSL handshake if client authentication is enabled on the server side and the OpenAM URL. This organization or sub-organization name must be either "/" separated ( where it starts with "/" ) , DN , Domain name or a DNS Alias Name. And the url should specify the OpenAM server's protocol, host name, and port number, for example : http://daye.red.iplanet.com:58080 This constructor would be mainly used for the Certificate based authentication. If the certificate database contains multiple matching certificates for SSL, this constructor must be called in order for the desired certificate to be used for the Certificate based authentication. Caller would then use login to start the authentication process and use getRequirements() and submitRequirements() to pass the credentials needed for authentication by the plugin authentication modules. The method getStatus() returns the authentication status.

Parameters:

orgName - name of the user's organization

nickName - nick name for the certificate to be used

url - URL of the OpenAM server to talk to

Throws:

AuthLoginException - if AuthContext creation fails. This exception is kept for backward compatibility only.

AuthContext

public AuthContext(SSOToken ssoToken)
            throws AuthLoginException

Constructs an instance of AuthContext for a given organization name, or sub organization name contained in the single sign on token. This constructor should be called for re-authentication of an authenticated user. single sign on token is the authenticated resource's Single-Sign-On Token. If the session properties based on the login method used matches those in the user's new authenticated session then session upgrade will be done. A new session containing properties from both old single sign on token and new session shall be returned and old session will be destroyed if authentication passes. Caller would then use login to start the authentication process and use getRequirements() and submitRequirements() to pass the credentials needed for authentication by the plugin authentication modules. The method getStatus() returns the authentication status.

Parameters:

ssoToken - single sign on token representing the resource's previous authenticated session.

Throws:

AuthLoginException - if AuthContext creation fails. This exception is kept for backward compatibility only.

AuthContext

public AuthContext(SSOToken ssoToken,
                   boolean forceAuth)
            throws AuthLoginException

Constructs an instance of AuthContext for a given organization name, or sub organization name contained in the single sign on token. This constructor should be called for re-authentication of an authenticated user. single sign on token is the authenticated resource's Single-Sign-On Token. If the session properties based on the login method used matches those in the user's new authenticated session then session upgrade will be done. If forceAuth flag is true then the existing session is used and no new session is created otherwise this constructor behaves same as the constructor with no forceAuth flag. Caller would then use login to start the authentication process and use getRequirements() and submitRequirements() to pass the credentials needed for authentication by the plugin authentication modules. The method getStatus() returns the authentication status.

Parameters:

ssoToken - single sign on token representing the resource's previous authenticated session.

forceAuth - indicates that authentication preocess has to be restarted and given single sign on token will be used and new session will not be created.

Throws:

AuthLoginException - if AuthContext creation fails. This exception is kept for backward compatibility only.

Method Detail

login

public void login()
           throws AuthLoginException

Starts the login process for the given AuthContext object.

Throws:

AuthLoginException - if an error occurred during login.

login

public void login(javax.servlet.http.HttpServletRequest request,
                  javax.servlet.http.HttpServletResponse response)
           throws AuthLoginException

Starts the login process for the given AuthContext object.

Parameters:

request - The HttpServletRequest that was sent to start the authentication process.

response - The corresponding HttpServletResponse for the HttpServletRequest.

Throws:

AuthLoginException - If an error occurred during login.

login

public void login(AuthContext.IndexType type,
                  String indexName)
           throws AuthLoginException

Starts the login process for the given AuthContext object identified by the index type and index name. The IndexType defines the possible kinds of "objects" or "resources" for which an authentication can be performed. Currently supported index types are users, roles, services (or application), levels, resources and mechanism/authentication modules.

Parameters:

type - Authentication index type.

indexName - Authentication index name.

Throws:

AuthLoginException - if an error occurred during login.

login

public void login(AuthContext.IndexType type,
                  String indexName,
                  String locale)
           throws AuthLoginException

Starts the login process for the given AuthContext object identified by the index type and index name. The IndexType defines the possible kinds of "objects" or "resources" for which an authentication can be performed. Currently supported index types are users, roles, services (or application), levels, resources and mechanism. It allows the caller to pass in the desired locale for this request.

Parameters:

type - authentication index type

indexName - authentication index name

locale - locale setting

Throws:

AuthLoginException - if an error occurred during login

login

public SSOToken login(AuthContext.IndexType type,
                      String indexName,
                      Callback[] userInfo)
               throws AuthLoginException

Starts the login process for the given AuthContext object identified by the index type and index name and also completes the login process by submitting the given User credentials in the form of Callbacks. The IndexType defines the possible kinds of "objects" or "resources" for which an authentication can be performed. Currently supported index types are users, roles, services (or application), levels, resources and mechanism.

NOTE : This is a simplified wrapper method to eliminate multi-step calls to 'login' and submit credentials. This method is useful and will work only for those authentication modules which require only one set of callbacks or one page. This method can not be used to authenticate to authentication modules which require user interaction or multiple pages.

Parameters:

type - Authentication index type.

indexName - Authentication index name.

userInfo - User information/credentials in the form of array of Callback objects. The Callback objects array must be in the same order as defined in the authentication module properties file, otherwise authentication module code will not work.

Returns:

single-sign-on token for the valid user after successful authentication.

Throws:

AuthLoginException - if an error occurred during login.

login

public void login(AuthContext.IndexType indexType,
                  String indexName,
                  String[] params)
           throws AuthLoginException

Starts the login process for the given AuthContext object identified by the index type and index name with default parameters. The IndexType defines the possible kinds of "objects" or "resources" for which an authentication can be performed. Currently supported index types are users, roles, services (or application), levels, resources and mechanism/authentication modules.

Parameters:

indexType - authentication index type.

indexName - authentication index name.

params - contains the default values for the callbacks. The order of this array matches the callbacks order for this login process. value for the PasswordCallback is also in String format, it will be converted to char[] when it is set to the callback. Internal processing for this string array uses | as separator. Hence | should not be used in these default values. Currently only NameCallback and PasswordCallback are supported.

Throws:

AuthLoginException - if an error occurred during login.

login

public void login(AuthContext.IndexType indexType,
                  String indexName,
                  String[] params,
                  javax.servlet.http.HttpServletRequest request,
                  javax.servlet.http.HttpServletResponse response)
           throws AuthLoginException

Throws:

AuthLoginException

login

public void login(AuthContext.IndexType indexType,
                  String indexName,
                  String[] params,
                  Map envMap)
           throws AuthLoginException

Starts the login process for the given AuthContext object identified by the index type and index name with certain parameters and environment map. The IndexType defines the possible kinds of "objects" or "resources" for which an authentication can be performed. Currently supported index types are users, roles, services (or application), levels, modules and resources.

Parameters:

indexType - authentication index type.

indexName - authentication index name.

params - contains the default values for the callbacks. The order of this array matches the callbacks order for this login process. value for the PasswordCallback is also in String format, it will be converted to char[] when it is set to the callback. Internal processing for this string array uses | as separator. Hence | should not be used in these default values. Currently only NameCallback and PasswordCallback are supported.

envMap - contains the environment key/value pairs. Key is a String object indicating the property name, value is a Set of String values for the property. Currenty this parameter only applicable when the indexTye is AuthContext.IndexType.RESOURCE.

Throws:

AuthLoginException - if an error occurred during login.

login

public void login(AuthContext.IndexType indexType,
                  String indexName,
                  String[] params,
                  Map envMap,
                  javax.servlet.http.HttpServletRequest request,
                  javax.servlet.http.HttpServletResponse response)
           throws AuthLoginException

Throws:

AuthLoginException

getSubject

public Subject getSubject()

Returns the set of Principals or Subject the user has been authenticated as. This should be invoked only after successful authentication.

Returns:

Subject for the authenticated User. If the authentication fails or the authentication is in process, this will return null.

getCookieTable

public Map getCookieTable()

Returns a Map object that that contains cookies set by AM server

Returns:

a Map of cookie name and Cookie object.

hasMoreRequirements

public boolean hasMoreRequirements()

Returns true if the login process requires more information from the user to complete the authentication.

NOTE: This method has to be called as a condition of a while loop in order to complete the authentication process and get the correct Status after submitting the requirements.

Returns:

true if more credentials are required from the user.

hasMoreRequirements

public boolean hasMoreRequirements(boolean noFilter)

Returns true if the login process requires more information from the user to complete the authentication. NOTE: This method has to be called as a condition of a while loop in order to complete the authentication process and get the correct Status after submitting the requirements.

Parameters:

noFilter - flag indicates whether to filter PagePropertiesCallback or not. Value true will not filter PagePropertiesCallback.

Returns:

true if more credentials are required from the user.

getRequirements

public Callback[] getRequirements()

Returns an array of Callback objects that must be populated by the user and returned back. These objects are requested by the authentication plug-ins, and these are usually displayed to the user. The user then provides the requested information for it to be authenticated.

Returns:

an array of Callback objects requesting credentials from user

getRequirements

public Callback[] getRequirements(boolean noFilter)

Returns an array of Callback objects that must be populated by the user and returned back. These objects are requested by the authentication plug-ins, and these are usually displayed to the user. The user then provides the requested information for it to be authenticated.

Parameters:

noFilter - boolean flag indicating whether to filter PagePropertiesCallback or not. Value true will not filter PagePropertiesCallback.

Returns:

an array of Callback objects requesting credentials from user

getRemoteRequest

public javax.servlet.http.HttpServletRequest getRemoteRequest()

Fetches the remote request from the context

Returns:

The Http Servlet Request

getRemoteResponse

public javax.servlet.http.HttpServletResponse getRemoteResponse()

Fetches the remote response from the context

Returns:

The Http Servlet Response

submitRequirements

public void submitRequirements(Callback[] info)

Submits the populated Callback objects to the authentication plug-in modules. Called after getRequirements method and obtaining user's response to these requests.

Parameters:

info - Array of Callback objects.

submitRequirements

public void submitRequirements(Callback[] info,
                               javax.servlet.http.HttpServletRequest request,
                               javax.servlet.http.HttpServletResponse response)

logout

public void logout()
            throws AuthLoginException

Logs out the user and also invalidates the single sign on token associated with this AuthContext.

Throws:

AuthLoginException - if an error occurred during logout.

logoutUsingTokenID

public void logoutUsingTokenID()
                        throws AuthLoginException

Logs out the user and also invalidates the single sign on token associated with this AuthContext. This method causes the logout to happen on the server and the correct SPI hooks to be called.

Throws:

AuthLoginException - if an error occurred during logout.

getLoginException

public AuthLoginException getLoginException()

Returns login exception, if any, during the authentication process. Typically set when the login fails.

Returns:

login exception.

getSSOToken

public SSOToken getSSOToken()
                     throws L10NMessageImpl

Returns the Single-Sign-On (SSO) Token for the authenticated user. If the user has not successfully authenticated Exception will be thrown.

Single sign token can be used as the authenticated token.

Returns:

Single-Sign-On token for the valid user after successful authentication.

Throws:

L10NMessageImpl - if the user is not authenticated or an error is encountered in retrieving the user's single sign on token.

getStatus

public AuthContext.Status getStatus()

Returns the current status of the authentication process as AuthContext.Status.

Returns:

Status of the authentication process.

getAuthIdentifier

public String getAuthIdentifier()

Returns the current Auth Identifier of the authentication process as String Session ID.

Returns:

Auth Identifier of the authentication process.

getSuccessURL

public String getSuccessURL()
                     throws Exception

Returns the Successful Login URL for the authenticated user.

Returns:

the Successful Login URL for the authenticated user.

Throws:

Exception - if it fails to get url for auth success

getFailureURL

public String getFailureURL()
                     throws Exception

Returns the Failure Login URL for the authenticating user.

Returns:

the Failure Login URL for the authenticating user

Throws:

Exception - if it fails to get url for auth failure

reset

public void reset()

Resets this instance of AuthContext object, so that a new login process can be initiated. A new authentication process can started using any one of the login methods.

getOrganizationName

public String getOrganizationName()

Returns the the organization name that was set during the AuthContext constructor.

Returns:

Organization name in the AuthContext.

getModuleInstanceNames

public Set getModuleInstanceNames()

Returns authentication module/s instances (or plugins) configured for a organization, or sub-organization name that was set during the AuthContext constructor.

Returns:

Set of Module instance names.

abort

public void abort()
           throws AuthLoginException

Terminates an ongoing login call that has not yet completed.

Throws:

AuthLoginException - if an error occurred during abort.

setCertDBPassword

public static void setCertDBPassword(String password)

Sets the password for the certificate database. It is required to call only once to initialize certificate database if the password is not set in the password file (specified as the value for com.iplanet.am.admin.cli.certdb.passfile in AMConfig.properties). If both are set, this method will overwrite the value in certificate password file.

Parameters:

password - Password for the certificate database.

getErrorTemplate

public String getErrorTemplate()

Returns the error template.

Returns:

error template.

getErrorMessage

public String getErrorMessage()

Returns the error message.

Returns:

error message.

getErrorCode

public String getErrorCode()

Returns error code.

Returns:

error code with white space trimmed

setClientHostName

public void setClientHostName(String hostname)

Sets the client's hostname or IP address.This could be used by the policy component to restrict access to resources. This method is ineffective if the "Remote Auth Security" option under the global configuration of Core Authentication Service is not enabled. This method must be called before calling login method. If it is called after calling login then it is ineffective.

Parameters:

hostname - hostname or ip address

getClientHostName

public String getClientHostName()

Returns the client's hostname or IP address as set by setClientHostName

Returns:

hostname/IP address

setLocale

public void setLocale(Locale loc)

Sets locale based on user locale preferemce.

Parameters:

loc - locale preference of user

getLocale

public Locale getLocale()

Returns locale preference set in AuthConext

Returns:

- user prefered locale.

checkAndSetLoginStatus

protected void checkAndSetLoginStatus()

sendQueryInformation

protected void sendQueryInformation(String reqInfo)

processRequest

protected Document processRequest(String xmlRequest)
                           throws AuthLoginException

Throws:

AuthLoginException

checkForException

protected static void checkForException(Document document)
                                 throws AuthLoginException

Throws:

AuthLoginException

getAuthenticationHandle

protected String getAuthenticationHandle(Document document)
                                  throws AuthLoginException

Throws:

AuthLoginException

getCallbacks

protected static Callback[] getCallbacks(Document document,
                                         boolean noFilter)

getSubject

protected static Subject getSubject(Document document)

getXMLforSubject

protected static String getXMLforSubject(Subject subject)

getLockoutMsg

public String getLockoutMsg()

Returns the account lockout message. This can be either a dynamic message indicating the number of tries left or the the account deactivated message.

Returns:

account lockout message.

isLockedOut

public boolean isLockedOut()

Returns true if account is lock out.

Returns:

true if account is lock out.

getAuthContextLocal

public AuthContextLocal getAuthContextLocal()