TENANT-MANAGER

Tenant Manager helps you to manage tenants and their credentials.

Kaa platform tenants are implemented on top of Keycloak realms meaning that each tenant has a separate Keycloak realm. For that reason Tenant Manager works not only with tenants and their credentials but also with Keycloak-related stuff - realms, scopes, resources, roles, identity providers, etc.

Usually, it is needed to specify a lot of parameters during realm creation in Keycloak - realm name, login page theme, default locale and others. All of them are listed here. The same is true for clients, scopes, roles, resources, identity providers, etc. that are other Keycloak entities. Each of the listed entity has its own set of fields that can vary between Keycloak versions.

In order to be flexible and not depend on specific Keycloak version, Tenant Manager introduces “template” concept. Template is a free format object that describes one of a Keycloak entity (e.g. realm), is stored on Tenant Manager and has unique version. The version is used in REST API during tenant creation.

Depending on the use case different tenants can be created from different templates.

The relation between tenants and templates is summarized in the following diagram.

Tenant Manager tenant to template relation diagram

Asynchronous tenant creation

Since each tenant has a separate Keycloak realm, during tenant creation Tenant Manager needs to create a corresponding realm in Keycloak. The process may take up to 1 minute depending on the available resources for a Keycloak server. For that reason, task queues and statuses were introduced. Receiving new tenant creation REST API request Tenant Manager creates new tenant record with the CREATING status in the underlying database and adds realm creation task to an asynchronous queue.
Once the task is completed and a corresponding Keycloak realm is created, tenant status is changed to AVAILABLE.
All statuses are listed here.

Tenant Manager uses Redis as a task queue.

Resource protection

Each tenant owns set of protected resources - e.g. endpoints, applications, etc. In order to authenticate and authorize user access to protected resources Keycloak introduces “client” concept. There are two such clients that are used in the Kaa platform - front-end and back-end with different access types.

  • Front-end client has public access type and is used for user authentication.
  • Back-end client has confidential access type and is used by Kaa services to manage protected resources.

Clients have their templates that can be managed with Tenant Manager’s REST API.

Interfaces

Tenant Manager supports a number of interfaces to perform its functional role. The key supported interfaces are summarized in the following diagram.

Tenant Manager interfaces diagram

For inter-service communication, Kaa services use REST APIs.

Kaa Service platform

Tenant Manager provides Tenant management API to allow managing tenants in Tenant Manager.

Identity Provider

An identity provider (IDP) is a service that can authenticate a user. Keycloak is an IDP.

Management interface

Tenant Manager exposes an HTTP-based management interface with the following endpoints:

  • GET /health returns 200 OK if the service is up and running properly, and 500 Internal Server Error otherwise. In case of errors, the response payload contains their human-readable descriptions. This endpoint can be used by Kubernetes for liveness and readiness probing.