Manage users in yuuvis® Momentum and in Keycloak via the Tenant Management API.

Introduction

The Tenant Management API provided by the TENANT-MANAGEMENT service offers endpoints for user management via Keycloak. In order to scale the identity management, the KEYCLOAK-PROXY service can be used for the connection of multiple Keycloak instances. The endpoints of the Tenant Management API are called by the MANAGEMENT-CONSOLE, MANAGEMENT-CONSOLE-CLIENT and ARCHITECT services.

This article describes the handling and representation formats of data for individual user accounts as retrieved and expected by the Tenant Management Endpoints.

Further functionality is provided by our USERSERVICE.

User Management Endpoints

All endpoints for user management via the Tenant Management API are available via the Swagger UI https://<host>/tenant-management/swagger-ui.html. Some of them require an administrative role.

The POST and PUT endpoints allow for the deactivation of users. In object histories, the username of deactivated users is displayed further on. The username is still reserved as the user still exists in the corresponding tenant. In order to reuse the username of deactivated users for a new users, you may append -disabled to the original username. Thus, the deactivated user can still be identified in the object history and the username can be reused at the same time.

User Account Properties

The following properties for user accounts can be managed via the Tenant Management API.

Property	Type	in Creation Request Bodies	in Update Request Bodies	in Response Bodies	Description
id	string	Ignored.	Ignored.	Included.	The ID of the user for identification in the identity management system and in yuuvis® Momentum.
email	string	Required if invitation via email is desired.	Optional, unchanged if not specified.	Included if available.	The e-mail address of the user.
firstName	string	Optional.	Optional, unchanged if not specified.	Included if available.	The first name of the user.
lastName	string	Optional.	Optional, unchanged if not specified.	Included if available.	The last name of the user.
roles	list of string role names	Optional.	Optional, unchanged if not specified. Note: Changes can be applied also by assigning/removing groups.	Included if available. Includes roles assigned via groups if available.	A list of roles defined in the identity management system that are assigned to the user.
groups	list of string group names	Optional.	Optional, removed from data set if not specified.	Included if available.	A list of groups defined in the identity management system in which the assigned user is a member.
username	string	Required.	Optional, unchanged if not specified.	Included.	The username of the user.
enabled	boolean	Optional, default: true.	Optional, unchanged if not specified.	Included.	Specifies whether the user is allowed to log in (true) or not (false).
createdTimestamp		Ignored.	Ignored.	Included.

User Account Data Sets

For each user account represented in a request or response body, its properties are specified in JSON format. The order of the individual properties within one data set is arbitrary.

The following code block shows an example for a result list including the data sets of several user accounts. Such result list could be retrieved, e.g., by the endpoint GET /tenant-management/api/idm/users.

[
  {
    "id": "406b5a28-7a8b-4c36-a569-df7bff480375",
    "firstName": "Heinrich",
    "lastName": "Schuetzel",
    "roles": [
      "YUUVIS_SYSTEM_INTEGRATOR",
      "YUUVIS_DEFAULT",
      "YUUVIS_TENANT_ADMIN",
      "HR_MANAGER",
      "YUUVIS_CREATE_OBJECT",
      "YUUVIS_MANAGE_SETTINGS"
    ],
    "username": "newuser5",
    "enabled": true,
    "createdTimestamp": 1622122631393
  },
  {
    "id": "320c67d0-b88b-4e99-852a-b938f4b38cd7",
    "email": "kammer@segelreisen.de",
    "firstName": "Hannes",
    "lastName": "Kammer",
    "roles": [
      "YUUVIS_SYSTEM_INTEGRATOR",
      "YUUVIS_DEFAULT",
      "YUUVIS_TENANT_ADMIN",
      "YUUVIS_CREATE_OBJECT",
      "YUUVIS_MANAGE_SETTINGS",
      "YUUVIS_AI_PIPELINE",
      "COMPLIANCE_MANAGER",
      "YUUVIS_AI_PREDICT"
    ],
    "groups": [
      "onlyoffice"
    ],
    "username": "kammer",
    "enabled": true,
    "createdTimestamp": 1591957723730
  },
  {
    "id": "a6f5e1aa-ff42-4140-b9ec-5de4cc61f1a9",
    "email": "schwimmer@segelreisen.de",
    "firstName": "Klaus",
    "lastName": "Schwimmer",
    "roles": [
      "YUUVIS_SYSTEM_INTEGRATOR",
      "YUUVIS_DEFAULT",
      "INVOICE_MANAGER",
      "YUUVIS_TENANT_ADMIN",
      "HR_MANAGER",
      "YUUVIS_AIINVOICE",
      "EMAIL_WITHOUT_ACL",
      "QA_MEMBER_AREA2",
      "uma_authorization",
      "YUUVIS_CREATE_OBJECT",
      "TEAMS_MANAGER",
      "PHOTOARCHIVE_MANAGER",
      "YUUVIS_MANAGE_SETTINGS",
      "QA_MANAGER",
      "ACL_ALL_USERS",
      "YUUVIS_AI_PIPELINE",
      "QA_MEMBER_AREA1",
      "COMPLIANCE_MANAGER",
      "YUUVIS_AI_PREDICT",
      "offline_access"
    ],
    "username": "klaus",
    "enabled": true,
    "createdTimestamp": 1606820894094
  }
]

Graphical User Interfaces

yuuvis® architect

The User management view of yuuvis® architect provides a graphical interface for administrative users in order to manage users belonging to their tenant. Individual users can be edited or deleted and users can be added. New users will be invited via e-mail to set up their passwords.
>> User Management

yuuvis® management console

yuuvis® management console supports organizations in their tenant and user management, and hosts in package and organization management by means of a graphical user interface.
>> yuuvis® management console

User Settings Management

The USERSERVICE manages user-related data and provides CRUD (create, read, update, delete) operations on it. Its endpoints are provided in an own API.
>> User Settings Endpoints

Summary

For the user management of users via Tenant Management API, the data sets of individual user accounts are handled in JSON format with the above described properties and their corresponding values. For further functionality regarding account-specific content files and personal settings, we provide the USERSERVICE.