Multi-tenancy Configuration

This feature is part of Moodle Workplace™, which is available through Moodle Certified Partners and Service Providers only.

Managing tenants

The main administrator or a user with the capability tool/tenant:manage can manage tenants through Site administration > Users > Organisation > Manage tenants or directly via the All tenants icon in the Workplace launcher.

For each active tenant, you view the following information: the Tenant name, the number of assigned Users, the Category, up to two Login URLs, and the Archive action.

A default tenant has been created during installation, and at least one user (the site admin account) has already been assigned to it. After upgrading from Moodle LMS to Moodle Workplace, all users will belong to the default tenant.

Each tenant can have a top-level course category attached to it. Note that a course category can only be attached to a single tenant.

To create a new tenant, click on the +New tenant button. A pop-up screen will appear, displaying a range of tenant details.

Tenant name (Required): Name of the tenant. This is the name of the tenant. While multiple tenants can share the same name, it is advisable to use distinct names for different tenants.
Site name and Site short name: These are essentially the full site name and the short name used in the site settings for the front page, found under Site administration > Front page settings. Once a tenant is active (either by selecting it via the tenant switcher or when a user belongs to a tenant), the tenant settings will override the site settings. The site shortname will be displayed in the header if the field 'Header logo' (in the tenant branding configuration) is left empty.
ID number: This is a unique identifier for your tenant. It is used when uploading users via the upload user tool or connecting to external systems through web services, as well as in the login URL. Two HTML data attributes, [data-tenantid="{tenant_id}"] and [data-tenantidnumber="{tenant_idnumber}"], help customize styles for specific tenants. However, the tenant ID number must be specified for these attributes to function.
Login URL: There are two options for accessing the login directly: one includes the ID number, and the other uses an internal numeric tenant ID (the default tenant always has ID=1 and cannot be changed). The internal tenant ID is not available during tenant creation, so the login URLs are displayed as tenantid={ID} and tenant={IDNUMBER}, respectively
Show this tenant in the login selector: By enabling this option, this tenant will be listed on the login page of every tenant as an alternative login page. For details, refer to the section describing the Login tenant selector.
Course category Courses belonging to a particular tenant must be located in a tenant category. There are three options for Course category selection:
- No category (default): No tenant category is selected.
- Create a new category: A top-level course category with the same name as the tenant name will be created.
- Choose an existing category: All top-level categories that are not already assigned to other tenants will be available for selection.

Moodle Workplace also supports courses that are shared across tenants.

Three roles are created automatically during the Workplace installation and are assigned automatically to the following users:

Tenant administrator: Assigned to the tenant administrator (in the system context).
Tenant administrator in the course category: Assigned to the tenant administrator (in the context of the tenant's course category). This role is also known as tenant manager.
Tenant user: Assigned to all tenant users (in the context of the tenant's course category). By default, this role only has the capability 'moodle/category:viewcourselist'

You cannot delete these three roles or change their assignments. However, as a site administrator, you can modify these roles if necessary. For example, the "Tenant administrator" role by default includes the capability tool/tenant:managetheme, which allows the tenant administrator to change the appearance of their tenant (logo and colours). The main administrator may decide to restrict theme customisation to a central level and prohibit this capability in the "Tenant administrator" role. The same applies to the tool/tenant:manageusers capability.

After adding a tenant, you will be redirected to the Users tab, where you should add a tenant administrator.

Tenant Users

When dealing with tenant users, two fundamental rules apply:

A user is always assigned to a tenant; that is, an account cannot be tenantless.
A user cannot be assigned to more than one tenant; an account always belongs to a single tenant and a single tenant only. This rule might be relaxed in the future.

The following diagram illustrates how users are assigned to tenants:

Each user belongs to precisely one tenant. Each tenant can have zero, one, or many tenant administrators. By default, a tenant admin has permission to manage tenant users, manage tenant roles, configure authentication settings, and adjust tenant branding.

When a new user account is created—whether through self-registration, manual entry, batch upload, or via web services—it is always attached to the default tenant unless specified otherwise.

You can manage all tenant users and add new users to the tenant in the Users tab. The required capability is tool/tenant:manageusers.

To add a new tenant user manually, select the +New User button. The screen will display the same information as the standard user form, plus an additional Tenant administration section at the bottom, where you can assign the user tenant administration rights to the user.

If a course category has been assigned to the tenant, the tenant administrator is automatically assigned the tenant manager role in that category. This means they have permission to create courses, assign roles, etc. Access to course management is available through Workplace launcher > Courses.

Using the drop-down menu at the bottom, an administrators can perform a number of actions. By default, that is without granting or denying permissions, the following actions are available to tenant administrators and site administrators, respectively:


Action	Tenant Admin	Site Admin
Confirm accounts	X	X
Send a message		X
Delete users	X	X
Force password change		X
Add to cohort		X
Suspend users	X	X
Activate user accounts (unsuspend users)	X	X
Resend confirmation emails	X	X
Resend user authentication factors		X
Allocate to program		X
Allocate or certification		X
Add to tenant administrators (role)		X
Remove from tenant administrators (role)		X
Move between tenants*		X

* To move users between tenants the tool/tenant:allocate capability required. None of the user data, such as courses or certification completion, will be affected by this.

As a tenant administrator, you can batch upload users via the Upload users tool. A tenant is matched by its tenant ID number.

If the user has the tool/tenant:allocate capability, they can specify a tenant when uploading users (both for creating new users and updating existing ones). If the user does not have this capability, they can only be create and update users in their own tenant.

Since a user cannot be tenantless, it is not possible to remove tenant allocation. However, you can move a user from one tenant to another tenant by replacing the old tenant with the new value in the CSV file.

Multi-tenant support for user profile fields

Moodle's user profile fields have been extended to allow the definition of different user profile fields per each tenant. When creating or editing a user profile category in Site administration > Users > User profile fields, the following three self-explanatory options are available:

This category is available to all tenants (including future ones)
This category is available to the following tenants...
This category is available to all tenants except the following...

When profile fields belong to tenant-specific categories, they will only appear in the profile for users in those tenants; this includes sign-up and edit forms.

A tenant admin has permission to edit locked profile fields for users in their tenant.

User profile fields can be defined as identity fields (found under Site administration > Users > User permissions), which means that various user reports across Moodle Workplace will display the fields relevant to the current tenant.

Tenant Details

In the Details tab, the meta-information about the tenant can be modified. The screen is identical to the one used when you created a new tenant.

Tenant Roles

The Roles tab is where the available roles and their assignment to users in the current tenant are displayed and managed.

By default, the Tenant administrator role includes the capability tool/tenant:manageusers. Unless this capability has been removed from the role by the main administrator, the tenant administrator can create and edit users within their tenant.

The tenant administrator can also assign other roles to their users, such as Program manager or Organisation structure manager in the system context.

If the tenant has its own course category, the tenant administrator also has the role of Tenant administrator in course category in this course category and can assign roles in the context of this course category, such as "Course creator". For easier management, a single page lists all the roles that the tenant administrator can assign in both the System and Category contexts, accessible via Workplace launcher > Users > Roles.

Each tenant user is automatically assigned the role Tenant user in the context of their tenant category. Even a site administrator cannot edit this role or assign it to any users manually to avoid confusion.

Tenant Authentication

Moodle Workplace supports multi-tenancy for authentication, allowing you to configure different authentication options for each tenant. In the Authentication tab, all authentication plugins enabled in Site administration > Plugins > Authentication > Manage authentication are displayed.

Authentication methods that fully support multi-tenancy can be configured individually using the cogwheel icon. Authentication plugins that do not (yet) support multi-tenancy (indicated by the lock symbol) cannot be configured at the tenant level. Additionally, you can deactivate individual authentication plugins via the Hide icon.

To override selected authentication settings, such as authentication instructions and allowed domains, click the Common settings link. Here, you can modify general authentication settings for each tenant.

Site administrators can enforce certain settings for all tenants using the Force for all tenants option in the Common settings section under Site administration > Plugins > Authentication > Manage authentication.

Tenant administrators can override common settings or settings for multi-tenant authentication plugins through the Authentication tab. This feature requires the tool/tenant:authconfig capability, which is enabled by default for the Tenant admin role.

For more information on configuring authentication plugins in a multi-tenancy setup, please refer to the Multi-tenancy authentication section.

Tenant Branding

The Branding tab allows you to customise the look and feel of the tenant (the required capability is tool/tenant:managetheme). The available categories are Images, Colours, and Advanced:

Images

The Images category on the Branding tab allows you to manage the pictures displayed on your site:

Header logo: The company logo shown in the navigation bar.
Login logo: The organization logo displayed above the username and password fields on the login screen. This is often the same as the header logo.
Tenant selector logo: This logo appears on the login tenant selector if enabled. If not specified, the Login logo will be used.
Login background image: The picture displayed on the login screen.
Favicon: The icon associated with this site, typically shown in the browser's address bar.

Colours

The Colours category on the Branding tab allows you to specify the primary colour of your site:

Primary colour: This is the colour used for all links and serves as the accent colour of the site.
Match gray tones hue with primary colour: When enabled, shades of grey are automatically generated based on the tenant primary colour. This feature reinforces the brand identity while maintaining a consistent user experience.

Advanced

The Advanced category on the Branding tab includes settings that can only be edited by users with the tool/tenant:managethemeadvanced capability. By default, only site administrators have this capability, but it can be added to the tenant admin role if needed.

The following settings are available in the Advanced category

Footer text: Text displayed at the bottom of all pages, for example, a copyright disclaimer.
No-reply address: The site-wide no-reply address (noreplyaddress) is specified in Administration > Server > Email > Outgoing mail configuration. Here, you can provide tenant-specific email address.
Support name: The name of the person or other entity providing support via the support form or support page.
Link to 'Contact site support': The URL of a support page. If left empty it will link to a contact form.
Support availability: Determines who has access to contact site support from the footer.

The support-related fields are configured at the site level by default. By selecting Override, you can provide new values that apply only to users in this tenant.

Settings placed in the Show more... area may impact the site's accessibility and user experience. The default values fully comply with accessibility standards.

Navigation bar colour: The background colour of the top navigation bar
Primary button colour: The colour of the main action buttons
Custom SCSS: Any valid custom SCSS code

By clicking the Reset tenant appearance button, you can select which elements will be restored to their default values.

Note: Resetting tenant appearance cannot be undone!

Tenant Dashboard

By default all tenants' dashboards are linked to the content defined in the'Default site dashboard page'. Any modifications made to the site default dashboard will be reflected for new users in any tenant. Users with the tool/tenant:managedashboard capability (Site and tenant admins by default) can define a tenant-specific dashboard with the same editing capabilities as the core Dashboard. Tenant administrators can manage their tenant's dashboard and reset the configuration for tenant users.

Once the button "Create personalised dashboard..." is clicked, the tenant dashboard will no longer be linked to the content defined in 'Default site dashboard page'. Instead, it will become an independent dashboard page that can be configured individually via the Edit Dashboard button.

The Dashboard status will change from Linked to Un-linked. When the Remove personalised dashboard, use site default dashboard... button is clicked, the tenant dashboard will be re-linked to the content defined in 'Default site dashboard page'.

The dashboard for new tenant users will be created from the default dashboard. Existing users will not be affected by changes to the linked or un-linked dashboard. However, their dashboards can be manually reset by clicking the Reset dashboard for all users... button.

Archiving and Deleting Tenants

Moodle Workplace supports the and deleting of tenants. The complete tenant archiving and deletion process is shown in the following workflow:

To archive a tenant, select the Archive action next to the tenant in the Active tenants tab.

If the tenant has no users, it will be archived and can accessed from the Archived tenants tab, where the following actions are available:

Restore: The tenant will be restored, retaining all its settings, roles, and theme variables.
Delete: The tenant will be permanently removed. This action cannot be undone!

If the tenant has users, they will be suspended, and the tenant will be archived. You can access the archived tenant from the Archived tenants tab, where the following actions are available:

Restore: The tenant will be restored, and all its users will be activated (unsuspended). The tenant retains all its settings, roles, and theme variables.
Activate users into tenant ...: All users of the archived tenant will be allocated to the selected tenant. Users will keep their previous roles in the new tenant, including tenant administrators. This reallocation does not apply to users who have already been (manually) allocated to another tenant.
Delete: The tenant will be permanently removed, and all its users deleted. This action cannot be undone!

Note: The default tenant cannot be archived.

User Tour Tenant selector

The tenant user tour selector allows you to customise onboarding tours by tenant.

You can create different user tours for different tentants by selecting one or many tenants when creating a new user tour.

Documentation