User Tokens and User Preferences

In this Lesson

You will learn how about the unique identifier Soiree assigns to users.

Concepts

Soiree allows user IDs to be changed. The user ID is a unique identifier (within its tenant) but it is not THE unique identifier used internally by Soiree. The unique identifier for a user in Soiree is called a user token, or simply token. The token is a 64-bit two’s complement integer (Java Long) that uniquely identifies a user across all tenants. If you have a token it can be used to find the user ID, tenant, and related information.

The token serves three purposes

  1. It provides a stable identifier for associating information to a user
    • Security groups are associated to a user token
    • The sign on log contains the user token
    • Your product may use it to associate your information to a user
  2. It is a more efficient linking mechanism than using the tenant and user ID.
  3. It allows the user ID to be modified without causing any harm to information which may be linked to a user

The token should be used for linking information to a user (there is one exception which we will discuss later regarding user preferences).

Using the Token

Agents may access the token for the currently signed on user.

getConversation().getConnection().getUser().getUserToken()

The com.seronix.soiree.security.UserService provides the following methods for returning information about a token

  • public UserInfo getUserInformation(DBConnectionProvider connectionProvider, Long userToken)
    Returns information about the user.
  • public static String getUserId(DBConnectionProvider connectionProvider, Long userToken)
    Returns the user ID.
  • public static String getUserId(Conversation conv, Long userToken)
    Returns the user ID.
  • public static UserIdentifiers getUserIdentifiers(DBConnectionProvider connectionProvider, Long userToken)
    Returns the tenant id, user ID, and the user service which owns the user.
  • public static UserIdentifiers getUserIdentifiers(Conversation conv, Long userToken)
    Returns the tenant id, user ID, and the user service which owns the ID.

The com.seronix.soiree.security.UserService provides the following methods for obtaining the token

  • public Long getUserToken(DBConnectionProvider connectionProvider, Integer tenantId , String userId)
    Returns the token for the specified tenant and user id.
  • public Long getOrCreateUserToken(DBConnectionProvider connectionProvider, Integer tenantId, String userId, String surname, String givenName)
    Returns the token for the specified tenant and user id. It will create the token if it does not already exist. Note: this method is intended for provisioning services.

User Preferences

The SoireeUserPreference system table stores name/value pairs associated with a user. It is designed to store any extended information about a user.

This table is the exception to the rule because the token is not used to associate the preferences to a user instead it uses the tenant and user ID.

Why this exception?

The sign on process and classes which implement UserServiceInterface do not have a user token and yet they may want to store preferences related to the tenant and user id they are working with.

Here are the APIs for storing and retrieving user preferences

  • UserPreference.putPreference(DBConnectionProvider connectionProvider, Integer tenant, String userId, String key, String value)
  • UserPreference.getPreference(DBConnectionProvider connectionProvider, Integer tenant, String userId, String key)

Renaming the user ID

When a user ID is changed two things happen

  1. Soiree asks the user service to change the ID (assuming the service supports that feature)
  2. Soiree changes the user ID in the SoireeUserPreference system table

That concludes this lesson.