Tenant Creation Profile

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

Table of Contents

Introduction

The tenant management API allows for the creation of new tenants in a customer's yuuvis® Momentum system. All information for the initial configuration of the new tenant are stored in the tenant creation profile, e.g. additional roles, initial users, schema and client settings. Each yuuvis® Momentum cluster has its own tenant creation profile. The tenant creation profile is stored, retrieved and updated in JSON format.

An admin user is created for each tenant that is used for the initial tenant administration. Per default, this user gets all global default roles except YUUVIS_SYSTEM_INTEGRATOR. The Credentials and E-mails will be specified during tenant creation. The users specified in the tenant creation profile are created in addition to this admin user.

The tenant creation profile does not belong the the configuration profiles of yuuvis® core. It is an independent file that follows its own concept and is managed only via the Tenant Management API.


Placeholders

It is possible to use placeholders within the tenant creation profile that will be replaced by values determined from the parameters of each tenant creation call. The syntax to incorporate them is ${varName}. The following placeholders are available:

Placeholder NameDescription
DISPLAY_TENANT_NAMEThe Keycloak Realm Display Name of the tenant as specified in the creation call.
TENANT_NAMEThe Keycloak Realm Name of the tenant as specified in the creation call.

The profile can be read and set via the following endpoints:

Parameters

The following table gives an overview of the parameters available within the profile and their usage. The parameters in the section general are displayed also in the Keycloak GUI, realm setting Themes.

ParameterRequiredValuesDescription
general.displayNameHTMLNo (but recommended)<div class=\"yuv-brand-logo\">${DISPLAY_TENANT_NAME}</div>
<div class=\"yuv-brand-logo ymc\">${DISPLAY_TENANT_NAME}</div>
Sets the left hand side of the login page's icon and title. If not specified, the Keycloak realm HTML Display name will be set by default to "<div class="yuv-brand-logo">${DISPLAY_TENANT_NAME}</div>".
general.customMicroserviceNoURL

The URL of a custom microservice endpoint that will be called in each process of a tenant creation via the Tenant Management API. Thus, custom tenant preparations are supported.

A POST request will be sent to the specified URL during each tenant creation process. The request contains a header and body:

  • Header: The JSON Web Token the creation endpoint was called with. Since this must be done by a user with access to the system-controller endpoints (default: users with YUUVIS_SYSTEM_INTEGRATOR role), you can use its rights to further prepare the tenant (e.g., create a user with tenant administration rights who can apply a tenant-specific schema)
  • Body: The tenant name as string.

The call is asynchronous, the tenant creation does not wait for a response from the microservice.


general.customMicroserviceOnDeleteNoURLDefine the URL of the custom microservice that should be asynchronously called after deleting a tenant to remove additional custom settings.
general.supportedLocales[]NoList of ISO language terms e.g. ["en","de","es"]Defines which languages a user can select in the login dialogue of Keycloak. The default locales are en for English and de for German. Find more available locales in the Keycloak documentation.
general.defaultLocaleNoISO language term, e.g., "en"Determines the language of the invitation e-mails that will be sent to each user created during the tenant creation.
client.redirectUris[] (as of 2022 Winter)NoList of URIs, e.g. [https://example.com/*"]URIs that are set as Valid Redirect URIs in Keycloak for Client creation. The default URI baseURL+"/*" is internally added to the configured list. As of 2022 Winter, only the default is used for tenant creation.
email.hostIf using e-mailURLThe SMTP server to be configured in the Keycloak realm (e.g., for sending invitation e-mails).
email.portNoIntegerThe port of the SMTP server. Default is 25.
email.fromDisplayNameNoStringThe display name of the e-mail sender for administrative emails.
email.fromIf using e-maileMail addressThe sender of the administrative e-mails.
email.enableSSLNoBooleanDetermines if SSL is enabled (true) or disabled (false). Default is false.
email.enableStartTLSNoBooleanDetermines if TLS is enabled (true) or disabled (false). Default is false.
email.enableAuthenticationNoBooleanDetermines if the SMTP server requires authentication.
email.usernameIf using e-mail with authenticationStringThe user name for authentication against the SMTP server.
email.passwordIf using e-mail with with authenticationStringThe password for authentication against the SMTP server.
roles[]NoList of key value pairs with the following parameters.Section that allows to add custom roles (in addition to the pre-defined role setwhich will be available within each new tenant. The roles are specified by their name and a description.

roleNoString

The name of a role to be added to the tenant. The following roles are created per tenant by default:

  • YUUVIS_DEFAULT  (full access to every object via default role set)
  • YUUVIS_MANAGE_SETTINGS  (save result list column and filter configurations as standard)
  • YUUVIS_TENANT_ADMIN  (update schema, rolse set, manage users, ... for the tenant)
  • YUUVIS_SYSTEM_INTEGRATOR  (update global schemata and role sets for the system, create tenants) 
  • YUUVIS_MULTI_TENANT (easily switch between accounts in different tenants)

descriptionNoStringThe description of a role to be added to the tenant.
groups[]No

As of 2021 Autumn, not yet supported by yuuvis® architect and yuuvis® management console.

Specify groups that will be created in the tenant with the listed roles assigned to them.








user.users[]If additional users shall be createdList of key value pairs with the following parameters.If a tenant is created via Tenant Management API, a first user admin is always included. Here you can define additional initial users that will be set up in each tenant created. For each of them, the following configuration parameters are available.

usernameIf additional user is to be createdStringThe user name of the user to be created.
emailIf additional user is to be created, with e-mail invitationStringThe e-mail address of the user to be created.
firstNameNoStringThe first name of the user to be created.
lastNameNoStringThe last name of the user to be created.
roles[]NoList of StringsThe list of roles the user should be assigned to.
passwordIf additional user is to be created, without e-mail invitationString

The user password of the user to be created. It will be stored encrypted.

Not necessary when inviting users via e-mail. 

Note: The password policy must be met, see corresponding description of this tenant management API endpoint: 

POST /tenant-management/api/system/tenants

enabled
BooleanEnable (true) or disable (false) the user to be created. In most cases true is recommended.
temporaryPassword
BooleanIf you want to set up technical users that should not be forced to change their passwords while logging in for the first time, set false. The default is true.
user.withInvitation
BooleanDetermines if new users should be invited via e-mail. If true, you do not need to set a password during user creation. 

The default value is false.


Profile Structure

The following code block shows an example profile.

example
{
	"general":{
		"displayNameHTML": "<div class=\"yuv-brand-logo\">${DISPLAY_TENANT_NAME}</div>",
		"customMicroservice": "https://myCustomMicroserviceURL",
		"supportedLocales": ["en","de","es"],
		"defaultLocale": "es"
	},

    "client": {
        "redirectUris": [ "https://example.com/*" ]
    },

	"email": {
		"host": "myemailservice.com",
		"port": 25,
		"fromDisplayName": "mySenderShowName",
		"from": "my.sender@address.tld",
		"enableSSL": true,
		"enableStartTLS": true,
		"enableAuthentication": true,
		"username": "emailserviceuser",
		"password": "PaswordWith8Characters1Uppercase1SpecialNoUserName"
	},

	"roles": [ 
		{
		"role": "Role 1",
		"description": "Description of Role 1"
		}, ...
	],

	"user": {
		"users": [
			{ 
				"username": "yauser", 
				"email": "yauser@example.tld",
				"firstName": "yaFirstName",
				"lastName": "yaLastName",
				"roles": ["YUUVIS_DEFAULT"],
				"password": "PaswordWith8Characters1Uppercase1SpecialNoUserName",
                "temporaryPassword": false,
				"enabled": true
			},
			...
		],
		"withInvitation": true
	}
}


Summary

The tenant creation profile is a JSON configuration file managed via the Tenant Management API. It is read during creation of a tenant of a customer via the Tenant Management API to set it up with all the information that should be configured. A custom microservice can be specified that will be called in each process of a tenant creation and allows for custom tenant preparations. Additional roles and initial users can be defined to be provided in each tenant created.

Read on

Keycloak Settings for yuuvis® management console

Configure Keycloak for the use of yuuvis® management console and the management console API. Keep reading

yuuvis® Momentum Settings for yuuvis® management console

Configure the cluster to enable the tenant management API to create and modify tenants. 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