From CubeiaWiki

Introduction

The User Service is a service that wraps a user database and provides a web service suited for service oriented architectures (SOA). The service exposes common functionality such as create, read, update and delete (CRUD) users. It also provides an interface for common administrative tools such as block user.

The User Service exposes a REST style API supporting JSON or XML content types. There are client jars available for java clients which will simplify the integration process.

The User Service manages it's own database and it is not recommended to merge the tables with other tables in the same database since this would break the service isolation pattern.

The User Service and reference documentation can be found on the Cubeia Network download page.

Service API

The table below shows a high level overview of the service API. A detailed reference documentation of the API can be found here.

Request	Response	Description
Create User	Create User Response	Creates a new user in the system. The user will be persisted in the the data storage area.
Authenticate User	Authenticate User Response	Authenticate a user with username and password. This can be used as a login check for other services.
Update User	Update User Response	Update user with new information. ID and username cannot be changed.
Change User Status		Set user status as supplied status.
Get User by id	User List Response	Get information about a single user
Search Users	User List Response	Search for multiple users

Basic Communication Flow

This section contains examples of communication flows for different use cases.

Below is an example of a client that creates and new user through the public website front end and then logs in through the game client and Firebase game server.

Below is an example of an administrator using the User Service through an admin web frontend.

Specific Functionality

Passwords & Authentication

Passwords

Passwords are stored in an encrypted manner in the database. The default scheme is PBE with MD5 and DES combined. The encryption scheme can be changed compile time in the user-service artifact. Note that the password is encrypted and not hashed. This allows for decryption and retrieval of the original password.

Authentication

When a User is authenticated, the supplied password is matched against the encrypted password in the database.

Phone Lookup Strategy

The User Services provides a plugin API for looking up user information (address etc) from a phone number. This is particularly useful when users are interfacing with the system using SMS services since the phone number is then verified (but user provided data is not) and we can pre-populate the User’s information.

To provide a phone lookup strategy you implement the LookupStrategy interface:

public interface LookupStrategy {
    public UserInformation lookup(String number);
}

Then map your strategy implementation to a country in the phonelookupstrategy table in the database. The strategy can now be explicitly accessed by the user manager service.

User Attributes

The User object allows for key-value attributes. Both keys and values are stored and handled as Strings.

In the User object they will be represented as a Map of keys to AttributeValues. Keys are String based and AttributeValue contains the core String value.

Working with Attributes

Attributes can be provided or set for a User when creating or when updating the User. An example of a User update is shown below. Note that this update call will effectively clear any data and attributes not included in the JSON object.

{
  "userName" : "Dogbert",
  "attributes" : {
  "entry" : {
    "key" : "car",
    "value" : "Saab"
    },
  "entry" : {
    "key" : "color",
    "value" : "Silver"
    }
  }
}

Attributes can also be accessed as a separate resource in a plain text format. See user attributes resource definition below.

Response Codes

The HTTP response codes as used by the API are specified in the Network Overview document. Some more resource specific response codes are included in the resource documentation below. This is only to clarify what a certain response code corresponds to for that given resource; it should be assumed that any resource can return any response code.

Configuration

If the file user-service/user-service.properties is found, the application will try to read configuration from this file. Otherwise default values will be used.

The following configuration can be made:

# Enable/Disable password encryption on user passwords. 
# Enabled is default.
user.service.password.encryption.enabled=false

User Types

A User can be any one of the types defined in the UserType enumeration. A regular User has UserType set to USER, and if you do not explicitly specific the user type when creating a User then that user will be of type USER as well.

All search operations and authentication work on users with type User only unless specified otherwise. This means for example that you can only authenticate towards regular USER types and not towards an OPERATOR type.

Typical use cases for non-USER types are ownership for internal accounts and integration partners.

Network/user/overview