Application Specific Data Persistence and Sharing
Trivore Identity Service (TIS) can be used to store small amounts of application specific data. There are a number of different types of data persistence methods for different kinds of data. This chapter covers the basics of those methods and helps making the decision on which method to use in which situation. This page also describes the logical locations of data for both user accounts and applications/services. The rationale combining these two seemingly different entities is simple: both may own similar objects, and both may share same objects. This sharing capability is of course controlled and safe when done right.
The graph above has four main entities, two user accounts and two applications/services (all darker blue). We use here both terms “application” and “service” interchangeably as they are the same thing in this context, yet many people only use the other term.
The fifth blue box represents the traditional user account group. These are shown here mostly due to them being able to carry access control and thus give access for their members.
There are three kind of private data types (all yellow), which are some of the main entities we concentrate on in this page. For user accounts the data types are user tags, and user custom fields. Each user account owns its own user tags, and custom fields. For accounts/services the private data type is application private tokens. Each application owns its own set of these tokens. For all these, we cover the access below.
In addition to the private data types, there are two public data types (both green). These data types are relatively close to each other by access control and usage. The main difference is in data structures to be stored. User tokens are simple, but data storage may store almost anything in it.
First we need to cover briefly few major terms.
Access control
A broad subject covering means to allow or deny access. Default access is always denying access.
Access control is defined often in lists, one for read-write and one for read-only. If an entity such as user or Management API Client is in a list, it will get appropriate access. Term access control list (ACL) and access control entry (ACE) are often used. ACE is one item in ACL. Access control is used purely for security purposes, not per permission management.
Another layer to access control is OAuth 2.0 and related user access tokens, which are entitled during signing in to the Trivore Identity Service OpenID Connect Provider. This mean to gain access is available for user accounts, and it may give access to additional data.
Similar to the above OAuth 2.0 is the management API, and management API clients. Integrating applications and services have very often a management API client defined for them. That is, management API client is used by applications and services. This client has security credentials, but more importantly it has permissions allocated to it. Those permissions give it access to data and other functionality.
Please note the access control is totally different internal control layer from user access token and management API client, which cover broader access capability from outside of service. For effective access state all three must be considered.
User related data persistence
The data persistence points in this section are related to user accounts in some way. The user tags are the most lightweight data structures, but they do not offer access control and can only store pieces of strings.
The user custom fields are key-value pairs and can hold more complex data than the user tags, but custom fields also do not have support for complex access management.
The user tokens are the most advanced user related data structure with access management support. User tokens are key-value pairs, but many types of data can be stored in them.
User tags
User tags are pieces of strings, which are attached to the user account. The user tags are indexed and users can be queried by tags. User tags can also be thought as lightweight groups, where a tag is the name of the group. TIS does not internally use user tags for anything and makes no interpretations on the meaning of the tags. It is up to the external application to
Namespace default tags can also be set for each namespace. The default tags are suggested in user tag editor field in the Web UI's user editor. Users can edit their own tags without any special permission. Also Management API Clients and users with ACCOUNT_MODIFY permission can change tags of any users belonging to an accessible namespace.
See https://trivore.atlassian.net/wiki/spaces/TISpubdoc/pages/24313857 page for more information on how to use tags efficiently.
User custom fields
Custom fields are a set of freely specified field names and values. The values can be strings, booleans, numbers or objects. They can be used in user search by using filter keys like 'customFields.{fieldName}'.
User Custom fields can be used to add and manage application specific user related data for each user.
User custom fields are visible to all Management API Clients with ACCOUNTS_VIEW permission and access to the user's namespace. Custom fields are also always visible to users themselves. Also, the custom fields can be modified by any management api client with ACCOUNTS_MODIFY permission and access to user's namespace.
User tokens
User tokens are access controlled key-value pairs attached to user accounts. User tokens have a list of entities, which are allowed to read the token and another list with entities, which are allowed to modify the token. The entities can be wither users, groups of users or Management API Clients. The value in user token can be any string, including JSON and base64 encoded binary streams. User tokens can be queried by user id and key.
The detailed user token documentation can be found on https://trivore.atlassian.net/wiki/spaces/TISpubdoc/pages/131858446 .
Generic data persistence
Data storages and application tokens can be used for more generic data persistence, which might not have anything to do with users. They can be used to store any application specific data.
The limitations of these storage methods are explained in the more detailed documents. Also the /apidoc page of each TIS instance tells how to access the endpoints for each data persistence methdod.
Data storages
The Data Storage is intended to be a light-weight database to store structured data in searchable form. It is not a full-blown relational database management system, but it serves most use cases for cloud and mobile-first applications. It has built-in access control, which can be used to grant read-only or read-write access to users, groups of users, or Management API Clients.
The detailed data storage documentation can be found on https://trivore.atlassian.net/wiki/spaces/TISpubdoc/pages/20515369 .
Application private tokens
As the name suggest, the application private tokens are application specific and visible and accessible only to the Management API Client, that created them. The application private tokens can be used to store relative data. Each entry has a relatedId, key and a value. The application private tokens do not have support for complex access management. The use of application private tokens does not require any specific permission and any Management API client can utilise them.
Application private tokens are documented in much greater detail in the page.
Matrix
The matrix below shows the difference and similarity of each data type.
Data type | Scope | REST API access | Accessible with | Max amount | Considerations |
|---|---|---|---|---|---|
User account custom fields | User account |
|
| Limited by combined user document size limit. | All fields are managed in bulk via REST. Take care when sharing between services. |
User tokens | User account | User tokens have their own REST API endpoint:
|
| Multiple may exist. For max size, see table below. | Good for smaller and low volume, controlled data sharing. |
Application private tokens | External service, each Management API client has their own set of private tokens. | Application private tokens have their own REST API endpoint:
|
| Multiple tokens may exist. For max size, see table below. | Having too many tokens may decrease application performance. Optimal single token size is usually around 1 kilobyte. Design application carefully. |
Data storage | Anything (Scope varies between data storages) | REST API endpoint:
|
| Unlimited amount of tokens may exist. For max size for one, see table below. | Very performant. Each data storage may have different access controls. |
User account (including identifying data and tags) | User account |
OpenID UserInfo endpoint:
|
| For max size for one user account, see table below. | Holds some of the auxiliary user account data. Also holds all user identity data. |
The table below shows important developer information on maximum data sizes. Total size includes keys, names, and some meta data, not only the main payload.
Data type(s) | Maximum size | Allowance |
|---|---|---|
User account (including tags, custom fields, identity data) | 16 MB per user account | Unlimited number of user accounts |
User tokens | 16 MB per token | Unlimited number of tokens |
Application private tokens | 16 MB per token | Unlimited number of tokens |
Data storage | 16 MB per storage with multiple key-data pairs | Unlimited number of data storages |