Skip to main content
Version: 10.2.8

Configure multi-tenancy for WorkSpace

The guide describes how to configure WorkSpace to work in a multi-tenant environment.

info

If you ran the installer script from the Add Tenant guide, restart WorkSpace.

Configure DNS​

Each Tenant has a separate DNS address, for example, tenant1.workfusion.com and tenant2.workfusion.com for WorkSpace users to sign in.

To configure DNS hostnames, manually add tenant1.workfusion.com and tenant2.workfusion.com to /etc/hosts on the Master server.

For more information on DNS hostnames, see the instruction.

Configure workforce​

To configure a workforce, do as follows:

  1. In Control Tower, go to System Preferences, select Add License, enter Tenant DNS as Domain Name, and click Save.
  2. Go to Workers > Workforces and click Manage Crowds. Create a new crowd and specify the created license as an endpoint value.
  3. In Workforces, click Create. Add the crowd created on the previous step and click Save.
  4. In every Business Process, set a workforce for a Tenant. If the workforce is wrong, a Manual Task is displayed, but results are not submitted to WorkSpace.

Configure WorkSpace​

You can configure WorkSpace in two ways:

  • Use the single-tenant mode (available in the on-premise installation) for the default configuration where only one Tenant is configured. In the single-tenant mode, the default Data Source and realm are used for each request and scheduled job execution (not attached to a Tenant ID). You don't need to configure the WorkSpace host URL to resolve the Keycloak configuration.
  • Use the multi-tenant mode for an environment with multiple Tenants.

Two configuration types are introduced to preserve the configuration in the on-premise environment. The default Data Source and realm configuration are included in the application WAR file for WorkSpace to work out of the box.

info

In the on-premise environment, update the configuration only when you change the default Data Source or realm configuration in the external configuration file, for example, the Data Source connection pool size or realm secret properties.

Single-tenant mode​

If you use WorkSpace on the current on-premise environment with the default configuration, don't change anything.

Old configuration structure of application.yml
spring:
  datasource:
    username: ${ws.datasource.username}
    password: ${ws.datasource.password}
    driver-class-name: com.microsoft.sqlserver.jdbc.SQLServerDriver
    url: ${ws.datasource.url}
    hikari:
      minimum-idle: 5
      maximum-pool-size: 40 
      connection-timeout: 30000
      validation-timeout: 3000
      initialization-fail-timeout: 60000
keycloak:
  enabled: true
  verify-token-audience: true
  bearer-only: false
  realm: WorkfusionRealm
  resource: wf-workspace
  auth-server-url: ${ws.sso.oidc.auth.url}
  credentials:
    secret: ${ws.sso.oidc.client.secret}

The old configuration structure is transformed to:

tenants-config:
  default-tenant-name: WorkfusionRealm
  names: WorkfusionRealm
  keycloak:
    enabled: true
    verify-token-audience: true
    bearer-only: false
    realm: WorkfusionRealm
    resource: wf-workspace
    auth-server-url: ${ws.sso.oidc.auth.url}
  default:
      host: ""
      realm: WorkfusionRealm
      secret: ${ws.sso.oidc.client.secret}
      datasource:
        url: ${ws.datasource.url}
        driver-class-name: com.microsoft.sqlserver.jdbc.SQLServerDriver
        username: ${ws.datasource.username}
        password: ${ws.datasource.password}
        hikari:
          minimum-idle: 5
          maximum-pool-size: 40 
          connection-timeout: 30000
          validation-timeout: 3000
          initialization-fail-timeout: 60000

If you change any property using the external configuration file, apply the changes to new properties during the upgrade. For example, you change the maximum Data Source connection pool property:

spring.datasource.hikari.maximum-pool-size=60

Now, define a new value in the property:

tenants-config.default.datasource.hikari.maximum-pool-size=60

Multi-tenant mode​

When one instance of the application has more than one client with a separate realm and database, configure WorkSpace in the multi-tenant mode, with each Tenant having its own configuration.

tenants-config:
  default-tenant-name: tenant1
  names: tenant1,tenant2
  keycloak:
    enabled: true
    verify-token-audience: true
    bearer-only: false
    realm: WorkfusionRealm
    resource: wf-workspace
    auth-server-url: ${ws.sso.oidc.auth.url}
  tenant1:
      host: tenant1-workspace.workfusion.com
      realm: tenant1-WorkfusionRealm
      secret: secret1
      datasource:
        url: jdbc:sqlserver://localhost:1433;databaseName=tenant1-wfdb;schema=ws
        driver-class-name: com.microsoft.sqlserver.jdbc.SQLServerDriver
        username: tenant1
        password: tenant1-passwd
        hikari:
          minimum-idle: 5
          maximum-pool-size: 40 #TODO change as it was in branch WS2.0
          connection-timeout: 30000
          validation-timeout: 3000
          initialization-fail-timeout: 60000
  tenant2:
      host: tenant2-workspace.workfusion.com
      realm: tenant2-WorkfusionRealm
      secret: secret2
      datasource:
        url: jdbc:sqlserver://localhost:1433;databaseName=tenant2_wfdb;schema=ws
        driver-class-name: com.microsoft.sqlserver.jdbc.SQLServerDriver
        username: tenant2
        password: tenant2-passwd
        hikari:
          minimum-idle: 5
          maximum-pool-size: 40 
          connection-timeout: 30000
          validation-timeout: 3000
          initialization-fail-timeout: 60000

To add other Tenants, configure their realms and Data Sources and update the tenants-config.names property accordingly.

Store configuration​

You can define the WorkSpace configuration in the following ways:

  • application.yml: configuration file included in the application or as the external configuration file
  • ZooKeeper: configuration properties in the /config/workspace directory
  • Secrets Vault: secrets with usernames and passwords

All these places are treated as one property source. Thus, the Tenant configuration can be spread across all these places, for example:

tenants-config:
  default-tenant-name: tenant1
  keycloak:
    enabled: true
    verify-token-audience: true
    bearer-only: false
    realm: tenant1-WorkfusionRealm
    resource: wf-workspace
    auth-server-url: ${ws.sso.oidc.auth.url}

With the help of ZooKeeper, WorkSpace can add, remove, and update Tenants without restarting the application. If you change some Tenant property in ZooKeeper, a related notification is sent to the application. Then, WorkSpace checks if the property refers to a Tenant configuration and triggers Data Sources and realm configuration refresh from the property sources (ZooKeeper, Secrets Vault, configuration files).

info

Only changes in ZooKeeper are detected. Changes in Secrets Vault do not trigger reconfiguration.

The best approach to configure a Tenant is:

  1. Configure or change Tenant properties in Secrets Vault.
  2. Configure or change Tenant properties in ZooKeeper.
  3. After you configure a new Tenant, update the tenants-config.names property.

Configure application properties​

Before setting the application properties, make sure the following prerequisites are met:

  • Realm configuration is added to the Keycloak for each Tenant.
  • Databases or schemas are created in the database server for each Tenant.

Configuration properties​

Configuration properties unique for Tenants have the {tenantName} token, a Tenant identifier in the WorkSpace configuration:

tenants-config.default-tenant-name       
tenants-config.names                  
tenants-config.keycloak.verify-token-audience             
tenants-config.keycloak.bearer-only            
tenants-config.keycloak.resource      
tenants-config.keycloak.auth-server-url                                  
tenants-config.{tenantName}.host                                          
tenants-config.{tenantName}.realm                                         
tenants-config.{tenantName}.secret                                        
tenants-config.{tenantName}.datasource.url                                
tenants-config.{tenantName}.datasource.driver-class-name                  
tenants-config.{tenantName}.datasource.username                           
tenants-config.{tenantName}.datasource.password                           
tenants-config.{tenantName}.datasource.hikari.minimum-idle                
tenants-config.{tenantName}.datasource.hikari.initialization-fail-timeout 
tenants-config.{tenantName}.datasource.hikari.maximum-pool-size           
tenants-config.{tenantName}.datasource.hikari.validation-timeout

Common properties​

Common properties are as follows:

tenants-config.default-tenant-name       
tenants-config.names

Mind the following requirements when configuring common properties:

  • tenant-config.default-tenant-name: keep the default Tenant name in the single-tenant mode.
  • tenants-config.names: keep the list of configured Tenant names separated by a comma, for example, tenant1,tenant2,tenant3

Some part of the Keycloak configuration is common for all Tenants:

tenants-config.keycloak.verify-token-audience             
tenants-config.keycloak.bearer-only            
tenants-config.keycloak.resource      
tenants-config.keycloak.auth-server-url

The properties are included in the application property file with the following default values:

  • tenants-config.keycloak.verify-token-audience=true
  • tenants-config.keycloak.bearer-only=false
  • tenants-config.keycloak.resource=wf-workspace
  • tenants-config.keycloak.auth-server-url=${ws.sso.oidc.auth.url}

In most cases, you don't have to change the properties in the external configuration file.

Tenant realm configuration​

To configure a realm for a Tenant, set up the following values:

tenants-config.{tenantName}.host                                          
tenants-config.{tenantName}.realm                                         
tenants-config.{tenantName}.secret

Where:

  • tenants-config.{tenantName}.host: URL (domain name) used to access WorkSpace for the Tenant and authenticate users

    For example, if a Tenant accesses WorkSpace under the URL: https://tenant1-workspace.workfusion.com, the property should have the tenant1-workspace.workfusion.com value.

    note

    The property must be empty in the single-tenant mode.

  • tenants-config.{tenantName}.realm: realm name configured for a Tenant

  • tenants-config.{tenantName}.secret: Keycloak resource secret used by WorkSpace for authentication purposes

Configure Tenant Data Source​

To configure a Data Source for a Tenant, specify the following settings:

tenants-config.{tenantName}.datasource.url                                
tenants-config.{tenantName}.datasource.driver-class-name                  
tenants-config.{tenantName}.datasource.username                           
tenants-config.{tenantName}.datasource.password                           
tenants-config.{tenantName}.datasource.hikari.minimum-idle                
tenants-config.{tenantName}.datasource.hikari.initialization-fail-timeout 
tenants-config.{tenantName}.datasource.hikari.maximum-pool-size           
tenants-config.{tenantName}.datasource.hikari.validation-timeout

Where:

  • tenants-config.{tenantName}.datasource.url: JDBC URL for the Tenant database or schema
  • tenants-config.{tenantName}.datasource.driver-class-name: driver class name
  • tenants-config.{tenantName}.datasource.username: Tenant database username
  • tenants-config.{tenantName}.datasource.password: Tenant database password
  • tenants-config.{tenantName}.datasource.hikari.minimum-idle: minimum number of idle connections in the connection pool
  • tenants-config.{tenantName}.datasource.hikari.initialization-fail-timeout: Data Source initialization timeout
  • tenants-config.{tenantName}.datasource.hikari.maximum-pool-size: maximum Data Source connection pool size
  • tenants-config.{tenantName}.datasource.hikari.validation-timeout: Data Source validation timeout