User Authentication

In this Lesson

In this lesson you will learn how to authenticate a user.

Concepts

User authentication is the process of verifying the identify of the person using the connection. Soiree utilizes a user ID and password to authenticate users.

Every client connection is associated with an instance of com.seronix.connect.SoireeUser which exists in one of two states

  1. Unauthenticated
    Unauthenticated users may only access public scenes. The SoireeUser’s authenticated property is false, it is associated with the generic tenant (0), has user token of 0, and contains no other properties.
  2. Authenticated
    Authenticated users may access public scenes and any scenes granted to them via the groups they are associated with. The SoireeUser’s authenticated property is true and the person’s name, tenant, user token, and security groups are properly valued.

Authenticating a User

The com.seronix.soiree.security.AuthenticationService contains methods which are used to authenticate users. The authentication service calls the product’s UserService to perform the actual validation of the user ID and password. If authentication succeeds then the connection’s SoireeUser will be transitioned to an authenticated state.

Here are the methods which will authenticate a user

  • public static AuthenticationResponse authenticate(Conversation conv, Integer tenant, String username, String password)
    This method is intended to be used by agents to authenticate a user.
  • public static AuthenticationResponse authenticate(Conversation conv, String username, String password)
    This is a convenience method which does not accept a tenant. It uses the generic tenant ID (0) to authenticate the user.
  • public static AuthenticationResponse authenticate(DBConnectionProvider connectionProvider, String productId, String solutionId, String connectionId, String clientIpAddress, Integer tenant, String username, String password)
    This method is intended to be used by non-agent services to authenticate a user.
  • public static AuthenticationResponse changePassword(Conversation conv, Integer tenant, String username, String oldPassword, String newPassword)
    This method will authenticate the user with the old password and, if successful, it will change the user’s password.
  • public static AuthenticationResponse changePassword(Conversation conv, String username, String oldPassword, String newPassword)
    This is a convenience method that does not accept a tenant. It processes the password change request using the generic tenant ID (0).

All of these methods return an instance of com.seronix.soiree.security.AuthenticationResponse. You can test the response with the following methods

  • isSuccess()
    Returns true if the authentication succeeded.
  • isInvalidTenant()
    Returns true if the tenant was invalid. Call getErrorMessage() to obtain a message suitable for presenting to the user.
  • isInvalidUsernameOrPassword()
    Returns true if either the user ID or password was invalid. Call getErrorMessage() to obtain a message suitable for presenting to the user.
  • isPasswordChangeRequired()
    Returns true if the client profile indicates the password needs to be changed. Call getErrorMessage() to obtain a message suitable for presenting to the user.
  • isGeneralError()
    Returns true if the process failed for any other reason. Call getErrorMessage() to the error message. Call getException() to obtain the Exception related to the error.

Sample Sign On Processing

Your agent is in control of the workflow – you get to choose what happens before or after they sign on. For example, instead of immediately starting the solution you may want to ask them information about themselves if they are signing on for the first time or perhaps you could give them an option to view introductory information about your product if they have not already that information.

Tip
How could you know if they are signing on for the first time or if they have not yet viewed the product information? You could store that type of information in User Preferences.

Here is the authentication process taken from the sample Signon agent. Notice it starts the solution if the authentication is successful.



Sample Sign Off Processing

You may transition a connection from authenticated to unauthenticated by calling this method.

Pump.signOff(Conversation conv)

This call asks the Pump to sign off the user all the agents have had a change to run. Sign off will occur whether or not any of the agents set an error condition.

This sign off request will assign an unauthenticated SoireeUser to the connection and then restart the solution which will transition the user back to the solution’s initial scene and related supporting scenes.


That’s all for this lesson.