Skip to main content
Version: 8.2405.x.x RR

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:

ClassThe Java class to load. The class must implement the ch.nevis.esauth.auth.engine.AuthState interface.
LoggingRelated trace groups, available for analysis.
AuditingEntries generated by the state (apart from the generic ones, generated by the AuthEngine)
MarkerAuth markers issued by this state in case of a successfully completed authentication or authorization operation.


name (type [unit], default)

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


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.


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)



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



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


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