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 Name	Description
`DISPLAY_TENANT_NAME`	The Keycloak Realm Display Name of the tenant as specified in the creation call.
`TENANT_NAME`	The Keycloak Realm Name of the tenant as specified in the creation call.

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

GET /tenant-management/api/system/profile returns the currently active profile.
POST /tenant-management/api/system/profile applies a new profile to the cluster.

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.

Parameter		Required	Values	Description
`general.displayNameHTML`		No (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.customMicroservice`		No	URL	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.customMicroserviceOnDelete`		No	URL	Define the URL of the custom microservice that should be asynchronously called after deleting a tenant to remove additional custom settings.
`general.supportedLocales[]`		No	List 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.defaultLocale`		No	ISO 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)		No	List 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.host`		If using e-mail	URL	The SMTP server to be configured in the Keycloak realm (e.g., for sending invitation e-mails).
`email.port`		No	Integer	The port of the SMTP server. Default is `25`.
`email.fromDisplayName`		No	String	The display name of the e-mail sender for administrative emails.
`email.from`		If using e-mail	eMail address	The sender of the administrative e-mails.
`email.enableSSL`		No	Boolean	Determines if SSL is enabled (`true`) or disabled (f`alse`). Default is `false`.
`email.enableStartTLS`		No	Boolean	Determines if TLS is enabled (`true`) or disabled (f`alse`). Default is `false`.
`email.enableAuthentication`		No	Boolean	Determines if the SMTP server requires authentication.
`email.username`		If using e-mail with authentication	String	The user name for authentication against the SMTP server.
`email.password`		If using e-mail with with authentication	String	The password for authentication against the SMTP server.
`roles[]`		No	List of key value pairs with the following parameters.	Section that allows to add custom roles (in addition to the pre-defined role set) which will be available within each new tenant. The roles are specified by their name and a description.
	`role`	No	String	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)
	`description`	No	String	The 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 created	List 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.
	`username`	If additional user is to be created	String	The user name of the user to be created.
	`email`	If additional user is to be created, with e-mail invitation	String	The e-mail address of the user to be created.
	`firstName`	No	String	The first name of the user to be created.
	`lastName`	No	String	The last name of the user to be created.
	`roles[]`	No	List of Strings	The list of roles the user should be assigned to.
	`password`	If additional user is to be created, without e-mail invitation	String	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`		Boolean	Enable (`true`) or disable (`false`) the user to be created. In most cases `true` is recommended.
	`temporaryPassword`		Boolean	If 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`			Boolean	Determines 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

Browser not supported