de.aristaflow.adept2.base.security

Interface Authentication

All Known Subinterfaces:

GlobalSecurityManager, SecurityManager

public interface Authentication

This interface provides methods for authenticating agents based on appropriate credentials. Usually this is a name and a password but there may also be more sophisticated authentication methods.
The authentication procedure consists of two parts: An initial authentication verifying the provided credentials and returning a list of QualifiedAgents. The second authentication requires an appropriate organisational position, verifies the credentials again and returns client session factories that in turn allow to access to the AristaFlow-Client-API for normal users (via their client programs). The second authentication may be done without the first one, in case one knows the organisational position (for instance logging on programmatically.

The implementation of authentication consists of two components: the local security manager and the global security manager. Simple cases are just forwarded to the global security manager, complex authentication like Single Sign-On (SSO) requires the local security manager retrieving the appropriate user credentials. Due to the various alternatives for authentication (e.g. password-based, Kerberos, etc.) this interface is rather generic. Therefore each of its methods requires the name of an authentication method. The usual ones are defined and described in a separate interface.

Do not forget to log off if you do not need the session factory any longer! This invalidates your session factory and prevents messing with it.

Author:

Ulrich Kreher, Patrick Schmidt

Method Summary

Modifier and Type	Method and Description
java.util.List<QualifiedAgent>	authenticate(java.lang.String method, byte[] authenticationData, AFCallbackHandler callbackHandler) Authenticates the agent identified by the designated authentication data with the designated authentication method.
ClientSessionFactory	authenticate(java.lang.String agentName, long orgPositionID, java.lang.String password) Identifies and authenticates a normal user via the corresponding name, orgPosition and the password and returns an appropriate ClientSessionFactory as which encapsulates the security information for the designated agent.
ClientSessionFactory	authenticate(java.lang.String agentName, long orgPositionID, java.lang.String method, byte[] authenticationData, AFCallbackHandler callbackHandler) Identifies and authenticates the designated agent by the corresponding name and ID referring to the appropriate QualifedAgent with the designated authentication method providing the authentication method-specific data.
ClientSessionFactory	authenticate(java.lang.String agentName, long orgPositionID, java.lang.String method, byte[] authenticationData, AFCallbackHandler callbackHandler, java.lang.String userSessionID) Identifies and authenticates the designated agent by the corresponding name and ID referring to the appropriate QualifedAgent with the designated authentication method providing the authentication method-specific data.
ClientSessionFactory	authenticate(java.lang.String agentName, long orgPositionID, java.lang.String password, java.lang.String userSessionID) Identifies and authenticates a normal user via the corresponding name, orgPosition and the password and returns an appropriate ClientSessionFactory as which encapsulates the security information for the designated agent.
java.util.List<QualifiedAgent>	authenticate(java.lang.String agentName, java.lang.String password) Like the name implies, this method's job is to authenticate agents, i.e.
java.util.List<QualifiedAgent>	authenticate(java.lang.String agentName, java.lang.String method, byte[] authenticationData, AFCallbackHandler callbackHandler) Authenticates the designated agent by the corresponding name with the designated authentication method providing the authentication method-specific data.
ClientSessionFactory[]	authenticateCombined(java.lang.String method, byte[] authenticationData, AFCallbackHandler callbackHandler) Performs a combined authentication that is authenticate(String, byte[], AFCallbackHandler) and authenticate(String, long, String, byte[], AFCallbackHandler) or authenticate(String, long, String, byte[], AFCallbackHandler, String) in one step.
ClientSessionFactory[]	authenticateCombined(java.lang.String agentName, java.lang.String method, byte[] authenticationData, AFCallbackHandler callbackHandler) Performs a combined authentication that is authenticate(String, String, byte[], AFCallbackHandler) and authenticate(String, long, String, byte[], AFCallbackHandler) or authenticate(String, long, String, byte[], AFCallbackHandler, String) in one step.
void	logoff(SessionToken session) Logs the agent off that is identified by the designated SessionToken.

Method Detail

authenticate

java.util.List<QualifiedAgent> authenticate(java.lang.String agentName,
                                            java.lang.String password)
                                     throws AuthenticationException,
                                            DataSourceException

Like the name implies, this method's job is to authenticate agents, i.e. check whether the provided user credentials are correct. If so, a list of representing objects one per organisational position and one for the undefined organisational position will be returned.
The system agent is not allowed to authenticate via this method. System agents need to know their organisational position and provide it for authentication.
This is the same as authenticate(agentName, AuthMethod.UTF8_PASSWORD, password.getBytes("UTF-8"), null).
The system agent is not allowed to authenticate via this method. System agents need to know their organisational position and provide it for authentication.

Parameters:

agentName - The (unique) name of the agent to authenticate.

password - the Agent's password

Returns:

Objects representing the authenticated user in the occupied organisational positions. The list always contains an object for the undefined organisational position.

Throws:

AuthenticationException - If the provided credentials are incorrect or the system agent tries to authenticate, an AuthenticationException will be thrown.

DataSourceException - when an unrecoverable error occurs while accessing the data source

authenticate

java.util.List<QualifiedAgent> authenticate(java.lang.String agentName,
                                            java.lang.String method,
                                            byte[] authenticationData,
                                            AFCallbackHandler callbackHandler)
                                     throws AuthenticationException

Authenticates the designated agent by the corresponding name with the designated authentication method providing the authentication method-specific data. For information on this data refer to AuthMethod. The designated callback handler allows the used authentication method to request additional data while authenticating. For how to use this refer to CallbackHandler and JAAS. For the used method refer to the corresponding authentication method.

Parameters:

agentName - The unique name of the agent to authenticate. This must not be null nor the empty string.

method - The authentication method to use for authentication. This must not be null nor the empty string.

authenticationData - The data required by the designated authentication method. Depending on the authentication method this may be null or empty.

callbackHandler - A handler for callbacks allowing the used authentication method to request further data. This may be null in case no callbacks are required.

Returns:

Objects representing the authenticated user in the occupied organisational positions. The list will be filtered according to the application name. It may also be the empty list.

Throws:

AuthenticationException - If the designated agent cannot be authenticated by the designated data with the designated authentication method and the callback handler, an AuthenticationException will be thrown.

authenticate

java.util.List<QualifiedAgent> authenticate(java.lang.String method,
                                            byte[] authenticationData,
                                            AFCallbackHandler callbackHandler)
                                     throws AuthenticationException

Authenticates the agent identified by the designated authentication data with the designated authentication method. For more information on this data refer to AuthMethod. The designated callback handler allows the used authentication method to request additional data while authenticating. For how to use this refer to CallbackHandler and JAAS. For the used method refer to the corresponding authentication method.

Parameters:

method - The authentication method to use for authentication. This must not be null.

authenticationData - The data required by the designated authentication method. Depending on the authentication method this may be null or empty.

callbackHandler - A handler for callbacks allowing the used authentication method to request further data. This may be null in case no callbacks are required.

Returns:

Objects representing the authenticated user in the occupied organisational positions. The list will be filtered according to the application name. It may also be the empty list.

Throws:

AuthenticationException - If the designated agent cannot be authenticated by the designated data with the designated authentication method and the callback handler, an AuthenticationException will be thrown.

authenticate

ClientSessionFactory authenticate(java.lang.String agentName,
                                  long orgPositionID,
                                  java.lang.String password)
                           throws AuthenticationException,
                                  DataSourceException

Identifies and authenticates a normal user via the corresponding name, orgPosition and the password and returns an appropriate ClientSessionFactory as which encapsulates the security information for the designated agent. The returned client session factory allows the agent to create session tokens that are needed to call the AristaFlow-Client-API.
This is the same as authenticate(agentName, orgPositionID, AuthMethod.UTF8_PASSWORD, password.getBytes("UTF-8"), null).

Parameters:

agentName - The unique name of the agent to authenticate.

orgPositionID - The ID of the organisational position for which the user is to be logged on.

password - The password of the user corresponding to the designated name.

Returns:

The client session factory for the designated user and the corresponding organisational position encapsulating the security.

Throws:

AuthenticationException - If the password and/or the username are incorrect, an AuthenticationException will be thrown.

DataSourceException - If an an unrecoverable error occurs while accessing the data source containing the username and the password, a DataSourceException will be thrown.

authenticate

ClientSessionFactory authenticate(java.lang.String agentName,
                                  long orgPositionID,
                                  java.lang.String method,
                                  byte[] authenticationData,
                                  AFCallbackHandler callbackHandler)
                           throws AuthenticationException

Identifies and authenticates the designated agent by the corresponding name and ID referring to the appropriate QualifedAgent with the designated authentication method providing the authentication method-specific data. For information on this data refer to AuthMethod. The designated callback handler allows the used authentication method to request additional data while authenticating. For how to use this refer to CallbackHandler and JAAS.

Parameters:

agentName - The unique name of the agent to authenticate. This must not be null nor the empty string.

orgPositionID - The ID of the organisational position of the corresponding QualifedAgent.

method - The authentication method to use for authentication. This must not be null nor the empty string.

authenticationData - The data required by the designated authentication method. Depending on the authentication method this may be null or empty.

callbackHandler - A handler for callbacks allowing the used authentication method to request further data. This may be null in case no callbacks are required.

Returns:

The client session factory for the designated agent and the corresponding organisational position encapsulating the security.

Throws:

AuthenticationException - If the designated agent cannot be authenticated by the designated data with the designated authentication method and the callback handler or the agent is not allowed to log on at the provided application, an AuthenticationException will be thrown.

authenticate

ClientSessionFactory authenticate(java.lang.String agentName,
                                  long orgPositionID,
                                  java.lang.String password,
                                  java.lang.String userSessionID)
                           throws AuthenticationException,
                                  DataSourceException

Identifies and authenticates a normal user via the corresponding name, orgPosition and the password and returns an appropriate ClientSessionFactory as which encapsulates the security information for the designated agent. The returned client session factory allows the agent to create session tokens that are needed to call the AristaFlow-Client-API.
This is the same as authenticate(agentName, orgPositionID, AuthMethod.UTF8_PASSWORD, password.getBytes("UTF-8"), null, userSessionID).

Parameters:

agentName - The unique name of the agent to authenticate.

orgPositionID - The ID of the organisational position for which the user is to be logged on.

password - The password of the user corresponding to the designated name.

userSessionID - The ID of the user session which is provided by various (client) frameworks. For instance HTTP-frameworks use this HTTP-Session-ID to identify each user uniquely.

Returns:

The client session factory for the designated user, the corresponding organisational position and the corresponding user session ID encapsulating the security.

Throws:

AuthenticationException - If the password and/or the username are incorrect, an AuthenticationException will be thrown.

DataSourceException - If an an unrecoverable error occurs while accessing the data source containing the username and the password, a DataSourceException will be thrown.

authenticate

ClientSessionFactory authenticate(java.lang.String agentName,
                                  long orgPositionID,
                                  java.lang.String method,
                                  byte[] authenticationData,
                                  AFCallbackHandler callbackHandler,
                                  java.lang.String userSessionID)
                           throws AuthenticationException

Identifies and authenticates the designated agent by the corresponding name and ID referring to the appropriate QualifedAgent with the designated authentication method providing the authentication method-specific data. For information on this data refer to AuthMethod. The designated callback handler allows the used authentication method to request additional data while authenticating. For how to use this refer to CallbackHandler and JAAS. The session tokens created by the returned client session factory will have the designated user session ID.

Parameters:

agentName - The unique name of the agent to authenticate. This must not be null nor the empty string.

orgPositionID - The ID of the organisational position of the corresponding QualifedAgent.

method - The authentication method to use for authentication. This must not be null nor the empty string.

authenticationData - The data required by the designated authentication method. Depending on the authentication method this may be null or empty.

callbackHandler - A handler for callbacks allowing the used authentication method to request further data. This may be null in case no callbacks are required.

userSessionID - The ID of the user session which is provided by various (client) frameworks. For instance HTTP-frameworks use this HTTP-Session-ID to identify each user uniquely. This must not be null.

Returns:

The client session factory for the designated agent and the corresponding organisational position encapsulating the security.

Throws:

AuthenticationException - If the designated agent cannot be authenticated by the designated data with the designated authentication method and the callback handler or the agent is not allowed to log on at the provided application, an AuthenticationException will be thrown.

authenticateCombined

ClientSessionFactory[] authenticateCombined(java.lang.String agentName,
                                            java.lang.String method,
                                            byte[] authenticationData,
                                            AFCallbackHandler callbackHandler)
                                     throws AuthenticationException

Performs a combined authentication that is authenticate(String, String, byte[], AFCallbackHandler) and authenticate(String, long, String, byte[], AFCallbackHandler) or authenticate(String, long, String, byte[], AFCallbackHandler, String) in one step. Choosing the organisational position is done via a OrgPositionChoiceCallback. If there is only one organisational position, this will be chosen without using the callback.
Note that this method requires an appropriate callback handler unless you are absolutely sure, there is only one organisational position. To logon for several organisational positions at once, implement the callback handling to always select the appropriate (or all) offered choices.
User session IDs will also be retrieved via UserSessionIDCallback. However, since using user session IDs is optional, the callback handler need not handle these callbacks and may even throw an UnsupportedCallbackException for them.

The restrictions for valid combinations for the authentication method apply here additionally.

Parameters:

agentName - The unique name of the agent to authenticate. This must not be null nor the empty string.

method - The authentication method to use for authentication. This must not be null nor the empty string.

authenticationData - The data required by the designated authentication method. Depending on the authentication method this may be null or empty.

callbackHandler - A handler for callbacks allowing the used authentication method to request further data. This may be null in case no callbacks (especially for choosing the organisational position) are required.

Returns:

The client session factory/factories for the designated agent and the chosen organisational position/positions encapsulating the security.

Throws:

AuthenticationException - If the designated agent cannot be authenticated by the designated data with the designated authentication method and the callback handler or the agent is not allowed to log on at the provided application, an AuthenticationException will be thrown.

authenticateCombined

ClientSessionFactory[] authenticateCombined(java.lang.String method,
                                            byte[] authenticationData,
                                            AFCallbackHandler callbackHandler)
                                     throws AuthenticationException

Performs a combined authentication that is authenticate(String, byte[], AFCallbackHandler) and authenticate(String, long, String, byte[], AFCallbackHandler) or authenticate(String, long, String, byte[], AFCallbackHandler, String) in one step. Choosing the organisational position is done via a OrgPositionChoiceCallback. If there is only one organisational position, this will be chosen without using the callback.
Note that this method requires an appropriate callback handler unless you are absolutely sure, there is only one organisational position. To logon for several organisational positions at once, implement the callback handling to always select the appropriate (or all) offered choices.
User session IDs will also be retrieved via UserSessionIDCallback. However, since using user session IDs is optional, the callback handler need not handle these callbacks and may even throw an UnsupportedCallbackException for them.

The restrictions for valid combinations for the authentication method apply here additionally.

Parameters:

method - The authentication method to use for authentication. This must not be null.

authenticationData - The data required by the designated authentication method. Depending on the authentication method this may be null or empty.

callbackHandler - A handler for callbacks allowing the used authentication method to request further data. This may be null in case no callbacks (especially for choosing the organisational position) are required.

Returns:

The client session factory/factories for the designated agent and the chosen organisational position/positions encapsulating the security.

Throws:

AuthenticationException - If the designated agent cannot be authenticated by the designated data with the designated authentication method and the callback handler or the agent is not allowed to log on at the provided application, an AuthenticationException will be thrown.

logoff

void logoff(SessionToken session)
     throws AuthenticationException

Logs the agent off that is identified by the designated SessionToken. All further requests with similar session tokens to the API will be declined.

Parameters:

session - The session identifying the agent to log off. This must not be null.

Throws:

AuthenticationException - If logging off fails, for instance due to an invalid session token, an AuthenticationException will be thrown.