Skip to content

Tenants Management

The software has a multi-tenant architecture where each tenant includes a unique configuration, unique integrations, and unique content. Each tenant:

  • is connected to their own unique back-end database.
  • has its own unique URL which has the following pattern: https://host:port/tenant-name/space-name

This Tenants page displays a list of all tenants in this deployment and is used to obtain a tenant's key ring.

Creating New Tenants

To create a new tenant:

  1. Log in to the default base tenant with an Administrator account. New tenants can only be created from the base root.
  2. Navigate to Management > Tenants and click the Add button.
  3. Click on the parameter name for details about each or follow the guidance provided here:
    1. Tenant Update Type: This parameter defines the procedure to use when connecting a new or an existing tenant to an existing database. The following scenarios are supported:
      • Create Standalone: In this scenario the tenant is connected to a new standalone database that is not initialized with the system data. All signing and encryption keys supporting at-rest or in-motion security will be created new.
      • Update Existing: In this scenario the tenant will connect to an existing database previously initialized with the system data in the past. In this case, a user should provide a Key Ring generated by a tenant connected to this database in the past to transfer signing and encryption keys to the newly created or updated tenant.
      • Create with Shared Database: In this scenario the tenant will connect to an existing database as a second node in a High Availability cluster. In this case, a user should provide a Key Ring generated by a tenant on the other node connected to this database to transfer signing and encryption keys to the newly created or updated tenant.
    2. Name: Tenant name is the part of the URL that clients, browsers and scripts use to access the tenant. In the case of the embedded database, it will be the name of the database too. Note that tenant name can only contain alphanumeric characters.
    3. Issuer: Issuer identifies a tenant for external parties such as SSO identity providers, browsers, scripts or applications integrating with the tenant using REST API calls. Tokens and exchange documents that the tenant signs are generated with this unique identifier. Issuer is usually a tenant URL.

      When ${dynamic} value is specified in the issuer field, the tenant generates an issuer value based on the URL a client accesses the tenant during the request to use the issuer. The downside of using dynamic issuer generation is that all tokens and exchange documents generated with different issuer will be invalid when the tenant will be accessed from a different URL.
    4. Language: Language of the tenant generated logs and events as well as the default language of the WEB application GUI. Note that each user might change the language of the GUI.
    5. Database: The back end database to store tenant data. The Embedded database is managed by the application itself. External database options include MySql, MS SQL, Oracle and PostgreSQL. Each external database will option will require you to supply an accessible DB URL, DB User and DB Password for connectivity.
  4. Click the Test button to test connectivity or the Save button to complete this operation.

Managing Tenants

To manage an existing tenant:

  1. Log in to the default base tenant with an Administrator account. Tenants can only be managed from the base root.
  2. Navigate to Management > Tenants, locate the tenant that you wish to update from the list and using its Actions menu:
    1. Edit: use this option to edit this tenant to modify the tenant configuration, including Name, Issuer, Language and Database.
    2. Navigate: use this option to navigate your browser to this tenant.
    3. Delete: use this option to delete this tenant. This operation cannot be undone.
  3. Click the Save button to complete the update operation.

Tenant Edit Menu

Accessing Tenant Key Rings

Tenant Key Rings are used to securely transport a tenant's signing and encryption keys to one database to another. If you are expanding a deployment to additional nodes or moving a tenant to a new or different database, the key ring will be required to complete this operation. To access a tenant's key ring:

  1. Log in to the base root tenant with an Administrator account.
  2. Navigate to Management > Tenants and expand the tenant entry you want to access the key ring from using its expansion arrow (Show Details) under the Actions column header.
  3. From the Key Ring field, click the Access Secret button to access the key ring. Once accessed, you can:
    1. Copy: this option will copy the key ring value to your clipboard without making it visible on your screen.
    2. Show Secret: this option will display the key ring value in this field. You may manually copy this value once visible.
    3. Lock Secret: this option will return the Key Ring to its original locked state. Collapsing this entry or navigating away from this page will result in an automatic lock action.

Accessing a Tenant Key Ring

Note

Keep all tenant key rings secure and be sure to store them in a safe location if copying them outside of the software.