Authentication Plug-Ins and AuthStates

This chapter provides an overview of the built-in authentication plug-ins and AuthStates. Each plug-in usually includes several AuthStates. The AuthStates are the building blocks of the authentication process and can be combined in all kinds of variations and sequences. During the authentication process, the user's login data passes different AuthStates.

Each AuthState has one particular responsibility, e.g., to authenticate a user against a certain authentication back end, to manipulate a request, to store information, etc. The AuthState also forwards the data to the next step in the authentication process. Basically, each AuthState receives input, processes it and produces output (which is the input for the next AuthState). This goes on and on, until the last AuthState within the authentication process is reached.

The description of each AuthState always happens in a standardized form:

Topic	Description
Class	The Java class to load. The class must implement the ch.nevis.esauth.auth.engine.AuthState interface.
Logging	Related trace groups, available for analysis.
Auditing	Entries generated by the state (apart from the generic ones, generated by the AuthEngine)
Marker	Auth markers issued by this state in case of a successfully completed authentication or authorization operation.

Properties

name (type [unit], default)

Properties are used to configure the plug-in and are read at startup.

Methods

The AuthEngine provides a contract for the following events:

• authenticate

  Standard initial authentication of a user.

  Result: An authentication session is created on success.

• stepup

  Session is established, but the authentication level is too weak or some authentication data is missing.

  Result: User receives a required security role (along with additional authentication data). The session remains.

• unlock

  Rechecks credentials on an existing session (screen-saver)

  Result: User may continue using the session.

• logout

  Existing session is invalidated due to a user logout.

  Result: Authentication session does not exist anymore.

If process is the method, all the above events trigger the same functionality. In addition, the AuthState may provide the following processing steps:

• validateInput

  This pre-processing step is called before delivering the event to one of the above methods. The default implementation validates user input according to the configured GUI descriptor. All declared GUI elements requiring input need to be present.

• generate

  This post-processing step is called after the AuthEngine has processed the event. It checks the AuthResponse for an already established GUI descriptor. If only a name is set, the corresponding GUI descriptor is set from the configuration. If nothing is set, the first GUI descriptor from the configuration is used (default behavior).

• finish

  This post-processing step is usually used to generate additional security tokens based on an established session context.

• handleError

  An implementing AuthState can use this method to define what has to be done if an error occurred in the post-processing methods.

Input

name (source, optional | mandatory)

Description: Expected user or caller input. Possible sources are:

• user

  Data is expected to be provided by the user

• user-agent

  Data is expected from the user's client infrastructure (e.g., browser). From a security point of view, this is equal to input from the user.

• caller

  Data is expected to be provided by the caller (e.g., nevisProxy)

Transitions

name

Result names are used to configure transitions to the next AuthState.

Output

name

Output arguments, generated by the AuthState. These values may be used in consecutive AuthStates using variable expressions (see Configuration expressions).

Errors

Errors are set by the AuthState (or the AuthEngine) and consist of an error number and a message. They are posted in the GUI descriptor to the login renderer. The following errors are set by the AuthEngine:

• lasterror=1: The generic AuthState validateInput function checks if all fields in the configured GUI descriptor were entered by the user.
• lasterror=9: Session handover failure. A handover handle was presented, but the session could not be transferred.
• lasterror=99: Some internal problem arose. The setup might be broken.

Notes

name

Notes are used to add processing data to the current request. They can be used by other AuthStates or in the configuration (see Configuration expressions).

Example

Example configurations.