Multi-tenant capability

In its delivery state, the application is not multi-tenant capable.
Without multi-tenant capability enabled, the system works with a global tenant (hereinafter referred to as the standard tenant), under which all data is managed collectively.

Multi-tenant capability can be enabled via the configuration parameter
deployment.singleTenantMode.

If multi-tenant capability is enabled, data can be administered on a tenant-specific basis.
Each tenant can also define its own settings, permissions or document types for its users in order to adapt the behaviour and appearance of the application to its requirements.

Enabling multi-tenant capability

To activate multi-tenant capability, the setting deployment.singleTenantMode must be set to false. This also changes the roles that a user needs in order to log in to the application.

The installation guide states that a configured user must have one of the roles ssu-user or ssu-admin in order to be authorised to use the application. When the application is started for the first time, these roles and an additional role ssu-root are created for the default tenant. The role ssu-root is intended for system administration.

The change in role assignment on the server is necessary because a user’s tenant affiliation in multi-tenant operation is mapped via the roles. This means that a user in the default state of tenant mode requires the following roles:

<!-- file conf/tomcat-users.xml -->
<tomcat-users>
  <role rolename="ssu"/>
  <role rolename="ssu_ssu-user"/>
  <user username="john" password="password" roles="ssu, ssu_ssu-user"/>
</tomcat-users>

Explanation:
The role ssu stands for the tenant identification of the standard tenant and determines that this user is assigned to this tenant. In addition, all roles of the tenant must be preceded by their tenant identification. ([tenantIdent]_[roleIdent])

Create tenant

Only users who can be allocated to a known tenant are able to use the application. To do this, a tenant must first be created in the system using the REST API. The right ssu.server.tenants is required to create tenants. The role ssu-root has this right. A tenant requires a display name (displayName) and an identification (tenantIdent), which must be unique throughout the system.

Furthermore, roles must be created for the respective tenant, which are assigned to the users of the tenant. A role consists of a unique role identification (roleIdent) for the entire tenant and a list of associated rights. In order for a user with this role to log in to the application, they require the ssu.login right.

Tenant management

Tenants are managed exclusively via the REST API. The resource Tenants serves this purpose. This resource is used to:

• create tenants

• change tenants

• delete tenants

• create tenant roles

• change tenant roles

• delete roles from tenants

• set document types for tenants

• determine settings for all users of a tenant.

Users of tenants and their permissions

Regardless of whether the system is operated in multi-tenant mode or not, user management is always located in a separate system. (Tomcat, LDAP, OIDC)

Within the application, only the roles and their permissions are defined. External user management defines which users have which roles and, consequently, which rights they have and to which tenant they belong.

Each user has a user identification (userIdent) that must be unique throughout the system. The user data is automatically created by the system when logging in to the application (pool application or REST API). Until then, these users are unknown to the system and cannot be queried. If necessary for integration, dummy accounts can be created to prepare user access before the user logs in for the first time. These consist only of the userIdent and can be used to make administrative preparations on the account.

After the user has logged in for the first time, the system knows their permissions and tenant affiliation. A user can only be allocated to one tenant at a time. Switching to a different tenant at a later date requires the user to be reset. Afterwards, the user can be allocated to another tenant.

Specify user settings as tenant

The user settings are applied in the application hierarchically and overwrite each other one after the other, starting with the settings specified by the server. These can in turn be overwritten by the tenant settings. The latter can ultimately be overwritten by the user settings.