Authentication Processing

This section describes the authentication process within nevisAuth.

Authentication flow

The figure below shows how the AuthEngine uses the configuration for state processing and specification of the required input.

The example on the right shows a configuration sample containing one domain and several authentication states. The domain dispatches on behalf of an authentication method: authenticate is called on AuthState2 (if the URL matches) or AuthState1, and stepup is processed in the AuthState3 plug-in.

info

Note that GUI specifications may be optional, depending on the plug-in implementation. The GUI may be generated dynamically in the code.

The figure below shows the request processing in more detail:

AuthEngine response states

There are four response states in which the AuthEngine ends up when a response is sent:

Response state	Description
AUTH_CONTINUE	The response state suggests that user data is still missing or that the wrong input was sent for the authentication process. The AuthEngine awaits another request and will then resume the AuthState that was previously stored in the session.
AUTH_DONE	If the response has the state AUTH_DONE, the authentication was successful and a SecToken was issued and sent back together with the response.
AUTH_ERROR	In this case, the AuthEngine is in a state in which additional information by the client will not recover the authentication process.
AUTH_REDIRECT	This special response state suggests that this nevisAuth instance is not capable of processing the request but knows another system that is.

The response states are extracted from the SOAP response sent by nevisAuth. They inform the nevisProxy IdentityCreationFilter what to do next.

Authentication conversations

The AuthEngine supports stateful and stateless dispatching. When doing multi-step authentication, the engine, per default, remembers the state of a session between a response and the following request. In effect, this creates a conversation where each consecutive request resumes the processing where the last response was generated. The conversation ends when a response with AUTH_DONE or AUTH_ERROR is generated, or when a session time-out occurs.

In some situations, exceptions to this behavior are required. AuthStates may be configured in four different ways to produce different state-flow behaviors within a conversation:

In the figure above, black arrows denote the processing of the incoming request, blue arrows denote the GUIs sent out in response to that request and red arrows show where the conversation continues when the next request is received.

• Generate AuthState response first (default)

  The AuthState is, per default, configured as being final. This means that the response of the AuthState is generated before processing any input. The AuthState's logic is executed when the client has provided the input to the previously generated response.

• Process the AuthState first

  If final is false, the AuthState is processed first, before generating any sort of response. Transitions from an AuthState configured as not being final to another AuthState occur without generating a response. This allows cascading multiple AuthStates to process a single request.

• Resume conversation at the preceding AuthState

  If resumeState is configured as false, the conversation will not resume at this AuthState after sending a response. Instead, it will resume at the preceding state. This behavior might be required in setups with several AuthStates acting as dispatchers.

• AuthState as dispatcher

  Some AuthStates are implemented as dispatcher AuthStates. In this case, requests are always dispatched for this AuthState, irrespective of where the conversation would have been resumed otherwise.

Resetting the conversation

Complex multi-step authentication scenarios may require a "cancel" option to be presented to the user. However, it can be difficult to design the state engine in such a way that the "cancel" option is always evaluated and that it resets the session to a valid state. For such use cases, the domain attribute resetAuthenticationCondition provides a clean and simple solution. If configured, this condition is evaluated for each incoming request. If it evaluates to a non-empty value that is not false, then the following values will be reset:

• nextState

  This resets the state flow of the current conversation. A new starting AuthState will be selected according to the dispatching configuration of the domain.

• result, error, outArgs, etc.

  All variable values pertaining to GUIs and errors and all outArgs are reset.

• userId, loginId, roles, authLevel:

  All authentication-relevant values will be reset to their state at the beginning of the conversation.

info

Note that only values known to be relevant to authentication or state flow will be reset. In particular, any session values set by AuthStates are not modified.