Tenant Creation Profile
- Technische Redaktion
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:
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 (false). Default is false. | ||
email.enableStartTLS | No | Boolean | Determines if TLS is enabled (true) or disabled (false). 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:
| ||
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 | |||
Profile Structure
The following code block shows an example profile.
{
"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.