User Service

In this Lesson

You will learn about the options you have for managing users in the Soiree environment.


Imagine for a moment you need to individually identify each person who will be using your solution. You will need to define and manage user names and passwords – or do you? The users you need may already exist.

The two questions about users
Question 1: where do the users come from?

When the English poet John Donne wrote in Meditation XVII ‘no man is an island’ he was suggesting no one is self-sufficient; everyone relies on others. The same may be said of a solution.

Your solution may be able to obtain its population of users from some other source such as an enterprise identity management system or perhaps some other application. Or you may have a solution for which you do need to create and maintain a new or separate population of users. Either way Soiree can help.

Question 2: which tenant owns the user?

A multi-tenant solution is one which allows multiple independent customers to use the same solution instance. This requires the information for each tenant to be kept separate from the information of all other tenants. This separation includes users. User names are only unique within tenant.

All users in Soiree belong to a tenant – even if your product is not designed for multi-tenancy. Tenant id 0 (zero) is reserved as the generic or non-specific tenant. This value is assigned to all users for products which do not support the notion of multi-tenancy.

User Service

Soiree has the notion of a user service which allows you to integrate any user population into Soiree’s user provisioning and runtime environment.

A user service provides the following

  • The population of users for a Soiree solution
  • Authentication services for the users
  • It may also provide auto-authorization for the users

Soiree offers three types of user services

  1. Soiree
    This service stores the user ID and name in the SoireeUser system table. The user’s password is also stored in this table as a PBKDF2 salted password hash. With this service your solution does act a bit like an island because it owns and manages its own user population.
  2. Soiree with LDAP
    This service also stores the user in the SoireeUser system table but it does not use the password column in that table. Instead, this adapter will validate the user’s password against an LDAP directory using simple simple LDAP authentication. This is useful if your have an enterprise directory which people use for other applications and your solution wishes to utilize the same password but maintain their own set of users in the SoireeUser table.
  3. Custom
    You may provide your own user service if the two Soiree-provided services do not meet your needs. A user service is simply a Java class which implements

Configuring Soiree User Services

You may recall that a solution is a subcomponent of a product. You may have desktop, iOS, and Android solutions all being offered as part of a single product. They would all share the same security services. So, you specify the user service in the product definition as shown here

Here is a brief description of each option.

  1. Soiree
    This user service does not require any configuration other than to ensure the SoireeUser table has been created in the database instance that is referenced by the com.seronix.soiree.connection.System connection.
  2. Soiree with LDAP
    This user service requires the SoireeUser table along with the simple LDAP configuration parameters.

    • Security url
      This is the URL of your LDAP server
    • Security Principal
      This is the distinguished name authorized to access the LDAP directory in order to look up users and validate passwords.
    • Security Credentials
      This is the password for the Security Principal
    • Search Base
      This is the distinguished name which defines the location in the directory from which the LDAP search for users begins.
    • Search Filter
      This is used to find a speicific user in the subtree. Use the {userid} token to specify where the user name should be substituted into the filter. The user service will replace the token with the user name when authenticating a user.
  3. Custom
    You must specify the name of the user service class along with any parameters you wish to provide to it.

User Information

The user information that is passed between the user service and the Soiree framework is defined in the class. It contains the following values

  • Tenant
    The tenant to which the user belongs.
  • userId
    This is the id of the user (sometimes also referred to as the user name).
  • Surname
    In the Western English-language naming tradition this is the person’s ‘last’ name.
  • Given name
    This is the official ‘first’ name.
  • Common name
    This is the person’s preferred first name. For example: Andrew may prefer a common name of Andy.
  • Suffix
    In the Western English-language naming tradition the suffix follows a person’s full name and provides additional information about the person. Examples include Jr, Ph.D, or Esquire.
  • Title
    A prefix added to the name such as Mr, Ms, Senator, or Baron.
  • Revoked
    Indicates whether or not the user has been revoked. This applies only to those user services which support user revocation.
  • Password Set
    Indicates whether or not a password has been set for the user.
  • Password Reset Required
    Indicates whether or not the user must change their password the next time they sign on.

Creating a user service

A user service is simply a Java class which implements This interface contains methods with allow the user service to declare the features it supports as well as the methods which implement the supported features.

Let’s take a look at just a few of the methods in the interface to provide some insight into how a user service is designed. Refer to the interface’s Javadoc for more information.

  • public boolean isUserIdCaseSensitive();
    Declares whether to not the user id is case sensitive.
  • public String getUserIdProperCase(String userId);
    Provides the user id in the case used by the service. For example, case insensitive services may convert all user names to either upper or lower case.
  • public UserInfo getUserInformation(DBConnectionProvider connectionProvider, Integer tenantId, String userId);
    Provides information about a specific user.
  • public String getSearchFilterPrompt();
    Provides a short label describing the syntax which can be used to search for users. For example, does the search support the use of wildcards and if so which ones?
  • public UserInfoSearchResult getFilteredUserList(DBConnectionProvider connectionProvider, Integer tenantId,String searchFilter);
    Returns a list of users which match the user specified search filter.
  • public boolean isCreateUserSupported();
    Declares whether or not the service is capable of adding new users to the user population.
  • public void createUser(DBConnectionProvider connectionProvider,UserInfo userInfo);
    Adds the user information contained UserInfo to the population of users.
  • public AuthenticationResponse authenticate(DBConnectionProvider connectionProvider, Integer tenantId, String userId, String password);
    Validates the user id and password.
  • Refer to the interface definition for the complete list of methods.

Accessing the User Service

Any Java class may use the product’s user service directly. While this is generally not needed in most circumstances it would be convenient for creating your own user management services if the need arises.

This is not intended for obtaining information about the user that is currently signed on. It is better to obtain information about the active user from the SoireeUser object which an agent can obtain by calling getConversation().conv.getConnection().getUser()

Here is how you instantiate and use the user service for a product.



	//instantiate the product's user service
	UserService userService = new UserService("PRODUCT ID GOES HERE");

	//here are some of the avaiable methods







}catch(Exception e){

User Provisioning Integration

The user provisioning scenes in the server console solution (described in a later lesson) allow you to manage the user population. Those scenes rely on the product’s user service to obtain the list of users and maintain them.

Each user service describes the features its supports through its is-X-Supported() methods.

For example, the Soiree with LDAP user service does not provide the set password feature because it is relying on the LDAP directly to manage the passwords. So, the service contains the following method

public boolean isSetUserPasswordSupported() {
	return false;

These feature declarations provide hints to the user provisioning scene in the server console solution. The user provisioning scenes will only present those features which are allowed by the user service.

Authorization Integration

Soiree provides a security manager which, among other things, is used to validate a user id and password combination when a user signs on.

The security manager relies on the product’s user service to perform the authentication of the user id and password.

You have reached the end of this lesson.