User Profiles

About User profiles

A User Profile represents an entity (such as a physical person, a device or an application) to be the “user”. A User Profile records personal characteristics about a user that are needed for access control purposes. TrustBuilder.io recommends that each user has a single User Profile . If the user needs different accounts to access different systems, these accounts will be associated to the single user profile in TrustBuilder.

A User Profile records those personal characteristics about a digital user that are needed for access control purposes.

TrustBuilder adopts the term “User Profile” as opposed to “User Account” to avoid confusion. An account typically refers to transactions and fixed access rights, it is typically managed outside TrustBuilder.io.

With TrustBuilder, a user can log in with only one user profile. During authentication the user can select a persona (or use default persona). During a valid session, the user can switch to another persona when relevant or required, without a new login (according to the policy).

The user profile is maintained in the Users database and accessible through the /users and /userinfo API endpoints. The API exposes user details as a JSON object containing ‘attributes’. User details can come from different sources, and the main (fairly static) part comes from a NoSQL database. This means that attributes can be added at any time.

A TrustBuilder user profile consists of different elements:

top-level attributes → basic information about the user (identifier, username, first name, last name, timestamp of the user's latest login). Most of the user attributes are root attributes (attributes stored at the first, or root, level of the user object), and some of these are editable.
providers → the Identity Providers (IdP) and Service Providers (SP) linked to the user profile (array with a block for every IdP and SP, possibly with an account at the provider)
personas→ the personas linked to the user profile (array with a block for every role that the user has registered or was added by an administrator or uploaded)

Custom attributes operate as secondary storage to maintain (cache) additional user info and derived attributes in customizable attributes, which may be linked to any of the above mentioned levels: top-level attributes level, providers level and personas level.

Third party attributes

User attributes provided by identity providers other than TrustBuilder (such as Google, Facebook, LinkedIn) are not directly editable. Moreover, TrustBuilder explicitly does not persistently store these so-called “third party attributes” in the User Profile due to the privacy risk: these attributes may change and even erased (e.g. a forget-me scenario at the identity provider) and thus should at the same moment be updated in TrustBuilder, while this is typically only done at the next login and thus too late.

Customer can specify that third party attributes are used to ease the registration process by prefilling corresponding fields in the registration form. Customer can also specify to temporary keep a copy of the third party attributes in the session that is set up using the identity provider. This ensures that data is at the minimum refreshed each time the user logs in.

Top-level attributes

A user profile is uniquely identified by the id attribute and TrustBuilder guarantees its uniqueness across the tenant. The user will not use this id, however, and they will identify themselves using the username, which will need to be unique across the tenant and TrustBuilder will raise an error if an attempt is made to create or update a user profile with a username that is already in use (even if it is in use by a blocked user profile). For the customer, the user profile may also be uniquely identified by the id_at_customer attribute (part of the persona object), but it shall be the customer that guarantees its uniqueness across their user population.

Name	Type	Description	Searchable?	Editable?	Importable?
Profile identification
`id`	uuid	Is system-generated and uniquely refers to the user profile. It is guaranteed to be unique within the realm of the customer. Importing allows user records to be synchronized across multiple systems without using mapping tables.	Y	N	Y
`username`	string	The name used by the user to identify their profile. This can look like an email address, a phone number, a full name separated with dots, a nickname, a customer-number, etc. It shall be unique within the customer’s realm. It can be copied from the user_id of the preferred_idp.	Y	Y	Y
`id_at_customer`	string	Id that uniquely identifies the person at the customer, such as CRM contact-id, personnel_number, etc.	Y	Y	Y
`personas`	array of `persona` object	Contains info about the different roles a user can play in the context of your service registered (see fields defined below).	Y	N	Y
Personal characteristics
`family_name`	string	The user's family name, normalised from the connected IdPs in a given priority order.	Y	Y	Y
`given_name`	string	The user's given name, normalised from the connected IdPs in a given priority order.	Y	Y	Y
Preferences
`ui_locales`	string	End-User's preferred language(s) for the user interface, represented as an array of BCP47 [RFC5646] language tag values, ordered by preference. Only the first language is considered. For example `de-DE`, `de-CH`, `en-US`, `en-GB.`	Y	Y	Y
`preferred_email`	string	The user's email address to be used for communicating with the user for notifications, requests, and other service-related matters	Y	Y	Y
`email_verified`	boolean	Indicates whether the user has confirmed their email address for service communications.	Y	N	Y
System-generated attributes
`last_login_at`	date time	System-generated timestamp (in UTC ISO 8601) indicating when the user last logged in. If a user is blocked and logs in, the blocked session updates last_login. If you are using this property from inside a Rule using the user< object, its value will be associated with the login that triggered the rule; this is because rules execute after login.	Y	N	N
`created_at`	date time	System-generated timestamp (in UTC ISO 8601) indicating when the user profile was first created.	Y	N	N
`updated_at`	date time	System-generated timestamp (in UTC ISO 8601) indicating when the user's profile was last updated/modified. Changes to last_login are considered updates, so most of the time, updated_at will match last_login.	Y	N	N

Example user profile

CODE

{
   "id": "B67425562B52417FAB73",
   "username": "jan.janssen",
   "created_at": "2022-05-17T11:29:05",
   "family_name": "Janssen",
   "given_name": "Jan",
   "ui_locales": "fr-FR",
   "preferred_email": "jan.janssen@gmail.com",
   "email_verified": TRUE,
   "personas": [
      {
        "id": "E1F425562B52417F87BA",
        "name": "consumer",
        "status": "ACTIVE"
      },
      {
        "id": "9DD425562B52417F981C",
        "name": "customer_employee",
        "scope": [ "chemco" ],
        "status": "PENDING"
      } 
    ]
}

For more examples of personas, please refer to Working with Personas.

How to manage User Profiles?

TrustBuilder enables a user profile to be created independently of any back office system.

The User Profiles can be created and edited:

using the TrustBuilder admin portal
using TrustBuilder Admin API (See Developer guide)
by a user using self-registration from the self-service portal

Create a User profile

To create a user profile for someone from TrustBuilder admin portal:

Go to User Management > Users
Click on + Add New User
Enter the Email, First Name, Last Name
Enter the Username.
The user will authenticate using the username. This has to be unique across the tenant. TrustBuilder will raise an error if an attempt is made to create or update a user profile with a username that is already in use (even if it is used by a blocked user profile). For example, this can look like an email address, a phone number, a full name separated with dots, a nickname, a customer-number.
Click on Save and Close.

The User Profile is successfully created. You can now edit the user profile to link it to Identity Providers and Personas, and add Consents.

A Universally Unique Identifier (UUID) is system-generated and uniquely refers to the user profile.

For each created User Profile, a principal (the entity that can be authenticated - usually a User) is automatically created in the TrustBuilder system Identity Provider. By default, the User Profile is linked to this principal.

Edit a User Profile

To edit a User Profile for someone from the admin portal:

Go to User Management > Users
Click on Edit for the user relevant User profile
In the General tab, you can edit the Email, the first and last names and the Username.
In the Provision tab, the available Identity Providers are listed (see Identity Providers to know more). For each Identity Provider (depending on the IdP type), you can perform the following actions:
- Link / Unlink the Identity Provider to the User Profile → Allow or disallow the user to authenticate using this Identity Provider
- (Only for System IdP) Set the Password for this Identity Provider → Set a password for this User Profile to authenticate using this Identity Provider. Password can be any combination of letters (upper and lower case), numbers, and symbols (ASCII-standard characters only).
  We recommend that you let users set their own password. Creating a user profile initiates an email confirmation process in which user will be invited to set a password.
- (Only for System IdP) Show provisioning details (requires provisioned status) → Display user login and password details
In the Consents tab, add Consents if needed (see Consents to know more).
In the Personas tab, add Personas if needed (see Personas to know more).
Click on Save and Close.

The User Profile is successfully updated.

Delete a User Profile

To delete a User Profile for someone from the admin portal:

Go to User Management > Users
Click on Delete for the relevant User profile.
In the pop-up, click on Delete to confirm the action.

The User Profile is successfully deleted. You may have to refresh the page to see it disappear from the list of user profiles.

Deleting a user ends all currently open sessions. This can be policy-driven as of TrustBuilder 11.2

Block/Unblock a User Profile

To block / unblock a User Profile for someone from the admin portal:

Go to User Management > Users
Click on Block / Unblock for the user relevant User profile.

The User Profile is successfully blocked / unblocked.

Blocking a user ends all currently open sessions. This can be policy-driven as of TrustBuilder 11.2