User Management via Endpoints

Manage users in Keycloak via the Tenant Management API.

Table of Contents

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 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.

API SectionRequired User Role in Default ConfigurationAvailable User Management EndpointsDescription

system-controller endpoints

operations on any tenant in the system

YUUVIS_SYSTEM_INTEGRATOR




Retrieves the number of all users of the specified tenant

GET /tenant-management/api/system/tenants/{tenant}/users

Retrieves a list of all users of the specified tenant. As 2021 Autumn, the list can be filtered by applying query parameters.

POST /tenant-management/api/system/tenants/{tenant}/users

Creates a new user with the given properties for the specified tenant.

GET /tenant-management/api/system/tenants/{tenant}/users/{id}

Retrieves the data of the user specified by tenant and id.

PUT /tenant-management/api/system/tenants/{tenant}/users/{id}

Update the data of the user specified by tenant and id.

DELETE /tenant-management/api/system/tenants/{tenant}/users/{id}

Deletes the user specified by id of the specified tenant.

admin-controller endpoints

operations on the own tenant

YUUVIS_TENANT_ADMINGET /tenant-management/api/admin/users/count

Retrieves the number of all users of the tenant.

GET /tenant-management/api/admin/users

Retrieves a list of all users within the tenant. As 2021 Autumn, the list can be filtered by applying query parameters.

POST /tenant-management/api/admin/users

Creates a new user in the tenant with the given properties.

GET /tenant-management/api/admin/users/{id}

Retrieves the data of the user specified by id.

PUT /tenant-management/api/admin/users/{id}

Updates the data of the user specified by id with the data passed in the request body in JSON format.

DELETE /tenant-management/api/admin/users/{id}

Deletes the user specified by id.

idm-controller endpoints

operations on the own tenant

The endpoints are available for every logged-in user.GET /tenant-management/api/idm/me

Retrieves the representation of the currently logged-in user.

GET /tenant-management/api/idm/roles/{role}/users

Retrieves a list of users that have the specified role assigned to them.

GET /tenant-management/api/idm/users

Retrieves a list of all users within the same tenant as the currently logged-in user.

GET /tenant-management/api/idm/users/{id}

Retrieves the representation of the user specified by id. Only users within the tenant of the logged-in user are available.

The POST and PUT endpoints allow for the deactivation of users. In object histories, the user names of deactivated users are still displayed. In the client framework components, these user names are still reserved by the Web-API Gateway as the users still exist in the corresponding tenant. In order to reuse the user name of a deactivated user for a new user, you may append -disabled to the original user name. Thus, the deactivated user can still be identified in the object history and the user name can be reused at the same time.

User Account Properties

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

PropertyTypein Creation Request Bodiesin Update Request Bodiesin Response BodiesDescription
idstringIgnored.Ignored.Included.The ID of the user for identification in the identity management system and in yuuvis® Momentum.
emailstringRequired if invitation via e-mail is desired.

Optional, unchanged if not specified.

Included if available.The e-mail address of the user.
firstNamestringOptional.Optional, unchanged if not specified.Included if available.The first name of the user.
lastNamestringOptional.Optional, unchanged if not specified.Included if available.The last name of the user.
roleslist of string role namesOptional.

Optional, unchanged if not specified.

Note: Changes can also be applied 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.
groupslist of string group namesOptional.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.
usernamestringRequired.Optional, unchanged if not specified.Included.The user name of the user.
enabledbooleanOptional, default: true.Optional, unchanged if not specified.Included.Specifies whether the user is allowed to log in (true) or not (false).
createdTimestampunix timestampIgnored.Ignored.Included.Date and time of user creation in the identity provider. 

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 can be retrieved, e.g., by the GET /tenant-management/api/idm/users endpoint.

[
  {
    "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 allowing them 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 a separate 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.

Read on

Tenant Creation Profile

Set up a tenant creation profile that defines the initial properties of tenants created via Tenant Management API. Keep reading

Tenant Management Endpoints

These endpoints can be used to retrieve information from the identity provider. Role and user management for a tenant and to create and delete tenants in Keycloak. Keep reading

USERSERVICE

A service allowing users to manage profile-specific content files (such as the user avatar) and settings (such as language preferences) after successful authentication. Keep reading