com.sun.identity.authentication
Class AuthContext

java.lang.Object
  com.sun.identity.authentication.AuthContext

public class AuthContext
extends Object

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

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.

Constructor Summary

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 turn on in the server side and the OpenSSO URL.

AuthContext(String orgName, URL url)
Constructs an instance of AuthContext for a given organization name, or sub organization name and the OpenSSO URL.

Method Summary

void	abort() Terminates an ongoing login call that has not yet completed.
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.
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.
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.
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.
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	logout() Logs out the user and also invalidates the single sign on token associated with this AuthContext.
static void	setCertDBPassword(String password) Sets the password for the certificate database.
void	submitRequirements(Callback[] info) Submits the populated Callback objects to the authentication plug-in modules.

Constructor Detail

AuthContext

public AuthContext(String orgName)

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)

Constructs an instance of AuthContext for a given organization name, or sub organization name and the OpenSSO 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 OpenSSO protocol, host name, port to talk to. 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 OpenSSO to talk to

Throws:

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

AuthContext

public 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. 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)

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 turn on in the server side and the OpenSSO 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 OpenSSO protocol, host name, port to talk to. 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 OpenSSO to talk to

Throws:

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

AuthContext

public AuthContext(SSOToken ssoToken)

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)

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()

Starts the login process for the given AuthContext object.

Throws:

AuthLoginException - if an error occurred during login.

login

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

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 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 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. 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 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.

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.

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

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.

logout

public void logout()

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

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()

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:

Exception - 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.

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()

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.