With the Enterprise tenant of Cumulocity IoT, you can customize your platform in various aspects and according to your requirements.
Apart from various configuration settings, you can use your individual branding and your individual domain name.
Click Enterprise tenant in the Settings menu to access these settings.
On the Configuration tab, you can configure various properties for your tenant.
APPLICATION ACCESS:
Users must have access to the Administration application of the Enterprise tenant.
ROLES & PERMISSIONS:
On tenant creation, there are default roles available that can be used as a sample configuration for the above-mentioned permissions:
The following placeholders can be found in the Configuration tab:
| Placeholder | Description |
|---|---|
| {host} | The value of this placeholder is “https://” + “<<tenantId>>” + “<<base-domain>>”. For example, if “tenantId” is auto-generated, the host will be https://t12345678.cumulocity.com. |
| {tenant-domain} | This is the location in which a tenant can be accessed. It is equal to “https://” + “<<tenantDomainName>>”. For example, {tenant-domain} can be https://myTenant.cumulocity.com. In case of an Enterprise tenant, the {tenantDomain} placeholders can have different values. An example tenant domain is https://myTenant.myhost.com. |
| {token} | An automatically generated system token for password reset purposes. When a user requests a password reset, a new random token will be generated. This token will be associated only with the particular user and will allow for a single password reset action. The standard way of using this placeholder is along with the {tenant-domain} property as “{tenant-domain}?token={token}”. |
| {email} | Will be replaced with the email address of the recipient user as stored in the user settings. Some views in the UI recognize this parameter and prefill the respective field with this value, for example, during the process of password reset. |
| {username} | Will be replaced with the value of the username property specified in the user configuration, see User options and settings. |
| {binaryId} | Will be replaced with the respective binaryId for the binary artefact to be used in the download link. |
| {exportApi} | Will be replaced with the respective API in which the error occurred. |
| {size} | Will be replaced with the storage usage percentage value. |
Under Two-factor authentication, you can change the SMS template which is sent to the users.
In the Support link section, you can provide a URL which is then used as default link for the Request support option in the user menu. If you set this value to “false”, then the Request support option in the user menu will be hidden. If you leave the Support link field empty, the URL for the link will be taken from the tenant options. However, an application can override this setting by defining the “supportUrl” application option.
In the Password reset section you can change all settings related to password reset email templates.
At the top you can select if you want to allow sending emails to unknown email addresses.
In the Password reset email template fields, provide an email template to be used when the address is known and one to be used when the address is unknown. The link to reset the password might for example be: {tenant-domain}/apps/devicemanagement/index.html?token={token}&email={email}.
In the Email subject field, provide a subject for all password reset related emails.
In the following two fields provide an email template to be used on password change confirmation and a template for the invitation email.
In the Email server section, you can configure custom email server settings.
In the Protocol and encryption field, select a protocol/encryption type from the dropdown list. May be one of:
Provide the host, port, username, password, and sender address for the email server. The empty password configuration is supported for the Enterprise tenant.
In the Data export section, you can set the email subject and email template for data export and specify the User unauthorized error message.
In the Storage limit section, you can specify the email subject and email template for emails being send before data is removed on exceeding the storage limit (warning) and after data removal is performed (limit exceeded).
In the Suspending tenants section, you can provide settings for emails being send on tenant suspension.
At the top you can select if you want to send the email to the suspended tenant’s administrator and specify an additional email receiver. Below you set the subject and template for the tenant suspended email.
Click Save configuration at the bottom to save your settings.
With the Branding feature, you can fully customize the look of your tenant to your own preferences.
APPLICATION ACCESS:
The branding feature comes as default with the Enterprise tenant and is available in the Administration application.
The branding functionality is enabled by subscribing to the “feature-branding” application.
ROLES & PERMISSIONS:
On tenant creation, there are default roles available that can be used as a sample configuration for the above-mentioned permissions:
In the Branding tab, you can configure various parameters like logos, colors and font types used throughout the platform.
The parameters are configured at the left side of the tab while at the right you can immediately see your selections applied to a preview extract.
For a more detailed preview of your settings, click Open preview in the top menu bar to check the look and feel of your branding settings in the overall platform. You may interact and even switch applications in the preview. Every change that you make in the Branding tab will immediately be applied to the Preview page.
When you are done or want to store your settings, click Save at the bottom of the Configuration section to save your branding settings to your tenant.
Saving the settings will not yet apply them to the current tenant and respective subtenants. To do so, click Apply in the top menu bar.
Click Remove branding in the top menu bar to reset the branding of the current tenant and its subtenants to the default settings. The custom settings will still be saved but are no longer applied.
In the Configuration section, the following branding parameters can be configured.
Under General, you can edit the title which will be used in the browser tab.
Under Main logo, specify the following items:
Under Navigator logo you can provide the navigator logo and set the navigator logo height located on top of the navigator panel.
In the Font section you specify the font settings for your branded version.
You can select your base and headings font stack, and select an option for the navigator font stack (either same as base or same as headings font). You may also add a link to existing remote fonts to be used.
In the Colors section you specify the colors to be used in your branding version.
The following parameters can be specified by providing a hex, rgb or rgba value:
In the Top bar section you specify the parameters for the top bar.
The following parameters can be specified by providing a hex, rgb or rgba value:
In the Navigator section you specify the parameters for the navigator.
The following parameters can be specified by providing a hex, rgb or rgba value:
In the Misc section you specify the “Button Border-Radius” by providing a value in pixel (px).
In the Cookie banner section you specify the settings for the banner with the cookie usage information. If not disabled here, the banner is shown for all users of the current tenant and all subtenants until a user clicks Agree and proceed.
Disabling the cookie banner, also disables the product experience tracking by Gainsight for the current tenant and all subtenants.
The following parameters can be specified:
A key feature of the Enterprise tenant is the ability to operate the Cumulocity IoT platform using a custom domain name. This means that you can configure the platform to serve you and your customers using a host name of choice, for example *.iot.mycompany.com rather than the default URL of Cumulocity IoT. In addition you’ll be able to create subtenants using your domain. These will be using <subtenantName>.iot.mycompany.com as their host names.
APPLICATION ACCESS:
The domain management feature comes as default with the Enterprise tenant tenant and is available in the Administration application.
The domain management functionality is enabled by subscribing to the “sslmanagement” microservice.
ROLES & PERMISSIONS:
On tenant creation, there are default roles available that can be used as a sample configuration for the above-mentioned permissions:
PREREQUISITES
There are three prerequisites for using a custom domain:
SSL CERTIFICATE REQUIREMENTS
The following criteria must be met by any SSL certificate to be used with the Enterprise tenant feature:
Cumulocity IoT supports a single certificate that is signed by the root CA, as well as a full chain certificate which contains one or more intermediate certificates.
In order to use an SSL certificate with Cumulocity IoT, the certificate together with its private key must be uploaded to the platform in a single file, using the PKCS #12 file format.
Most certificate authorities deliver their certificates and corresponding private keys in the PEM file format, using two separate text files for the certificate chain and the private key. Make sure that the private key is not protected with a password/passphrase.
Such PEM files can easily be repackaged into #PKCS #12 using OpenSSL. In the following example, OpenSSL is used to combine a certificate chain (chain.cert) and the corresponding key (privkey.pem) into a PKCS #12 keystore file (out_keystore.p12) that can be used with Cumulocity IoT.
openssl pkcs12 -export -out out_keystore.p12 -inkey privkey.pem -in cert.pem -certfile chain.pem
The DNS entries for your custom domain must be configured in a way that all requests are routed to the Cumulocity IoT platform.
We strongly recommend you to use a wildcard CNAME entry for this purpose. The CNAME must contain your wildcard domain from the certificate in the NAME field. The VALUE field of the CNAME entry must point to the hostname of Cumulocity IoT. This target hostname can be easily determined by looking at your current tenant URL. If your tenant URL is http://mytenant.cumulocity.com, the target hostname is mytenant.cumulocity.com. Please also make sure to delete any conflicting A entries.
Example:
If you want to use *.iot.mycompany.com for your enterprise subtenants and if you’re using the Cumulocity IoT at mytenant.cumulocity.com, the following CNAME entry must be added to your DNS zone:
NAME TYPE VALUE
----------------------------------------------------
*.iot.mycompany.com. CNAME mytenant.cumulocity.com.
We highly discourage any use of alternative DNS configurations for the following reasons:
Once the DNS configuration is in place and if a certificate with the given requirements is available, it can be easily uploaded to the platform.
On the Domain name tab in the Enterprise tenant page, click Upload certificate. Select the certificate from your file system and click Upload.
Afterwards, you can activate the domain with a single click on its name. After the domain has been activated, you will be redirected to your Enterprise tenant using the new domain name. You will also receive an email with information about the activation. Note that your Management tenant domain name is static, for example, if your wildcard domain is “* .iot.mycompany.com” then your Management tenant domain will be “management.iot.mycompany.com”.
When your certificate expires, you must update your certificate with a new one with an extended validation period. When updating a certificate, you must make sure that the certificate meets the following requirements:
If you wish to return to your old domain at Cumulocity IoT, you can simply deactivate you certificate.
In case you cannot reach Cumulocity IoT using your custom domain, we recommend you to perform the following checks to verify your DNS setup.
Check if the DNS entry is correct
Execute the following command:
host management.<your domain name>
The following result should be returned:
management.<your domain name> is an alias for <instance domain name>
<instance domain name> has address <ip address>
Check if the API is responding
Execute the following command:
curl -v -u '<tenant ID>/<your user>:<your password>' --head http://management.<your domain name>/inventory/managedObjects
The following result should be returned:
...
HTTP/1.1 200 OK
...