Reftab supports multi-tenancy which allows an organization to provision multiple unique instances of Reftab under one organizational structure.
In this guide we’ll cover:
- What multi-tenancy is
- How to know if you need multi-tenancy
- How to know which tenant users belong to
- How to know which access role a user should have within a tenant
- How to create a new tenant
- Automatically provisioning users with just-in-time provisioning
- Automatically sync users to tenants via SCIM
- Manually add users to a tenant
- Users that belong to multiple tenants
What is Multi-Tenancy in Reftab?
In a nutshell, multi-tenancy is when a software can serve multiple, independent user groups. For example, a university may want a Reftab account for the IT Department, while at the same time, wanting to use Reftab for the AV Department and for the Business School separately. Multi-tenancy would help here because these separate groups can manage their own assets and data without worrying about sharing access with other groups.
Single sign-on can be configured so that each user can sign in using their work / university credentials and route automatically to their Reftab tenant without hassle.
The users wont see any difference, but Reftab will do the work behind the scenes so that, for example, users in the Business School land in the Business School tenant, AV Department users land in the AV tenant and so on, without knowing any other tenant exists.
The image below shows an example of two tenants: London and New York, under one “Acme Corp.” company. The image illustrates data separation between tenants.
To setup multi-tenancy, you’ll need to reach out to help@reftab.com as this requires an upgrade.
How Do I Know if I Need Multi-Tenancy?
If you use single sign-on and have divisions within your school or company that want / need information to be separate from one another, then you should use multi-tenancy.
However, if not, you can use one Reftab account and setup access roles to limit what users can and cannot do. Or, each department can create a Reftab for their own group of users by signing up here: https://www.reftab.com/sign-up
Benefits of multi-tenancy
- Completely separate assets, categories and locations.
- Completely separate list of users.
- Manage user in multiple Reftab tenants using one SCIM connection.
- Completely separate account-wide settings. For example, each tenant can have its own timezone (important for running workflows and sending automated emails).
- Completely separate maintenance forms and schedules.
- Administrators can be given access to switch between tenants easily.
Limitations of multi-tenancy
- Cannot transfer data between tenants. Multi-tenancy is designed to separate assets, users, etc. As of today, there is no option for example, to transfer a group of assets from one tenant to another.
Limitations of single-tenancy
- Account settings are shared. For example, only one timezone can be set.
- Reports are all or nothing. For example, if you give someone access to reports, they can run reports on all locations across all categories of assets across all tenants. The only way to prevent this is to completely hide reports for the users you want to limit access.
- The loanee page will display all users no matter their department, organization or location they belong to.
- (You can still prevent users from checking out equipment at specified locations by using workflows)
- Maintenance jobs cannot be separated by access restrictions. All users who can log into Reftab can see maintenance forms.
How Does Reftab Know Which Tenant a User Belongs to?
Each tenant has attributes that define the type of users that should have access. Administrators need to define an attribute and value in Reftab and pass that attribute and value from their identity provider so that Reftab can read them and know information on who is logging in. Reftab looks at the SAML token being passed and, if mapped attributes are found, the user is allowed to access a tenant.
For example if you have a tenant for the “Photography” department, when users login, Reftab looks to see if the user is a member of the photography department based upon their SAML token. If so, they can access the Photography tenant.
If your organization does not have attributes like this, you can use a wild card. Click here to jump to the section on wild card routing
How Does Reftab Know The Access Role a User Belongs to?
Every user in Reftab needs to belong to an access role within Reftab. Examples of access roles are: “administrator”, “viewer”, “loanee”, “editor”, “disabled”, or any custom defined role.
By establishing attribute and value pairs, administrators can place users into an access role upon login. For example an attribute of, “department” and a value of, “IT” can save employee’s in the IT Department as Reftab administrators.
See the section below titled, “Automatically Provision Users Into Tenants” for more information.
This flow chart below gives an overview of the multi-tenancy mapping procedure:
How to Create a New Tenant
1) Log into Reftab in the Super Tenant as an administrator.
2) Click “settings“
3) Click “Tenants” > “Add Tenant“
Note: If you do not see “Tenants”, this means your account is not configured for multi-tenancy or, you’re not logging into the super tenant.
4) Next, provide the following information:
Tenant Name: A tenant name identifies the tenant within Reftab. If a user has access to more than one tenant, the tenant name will display to help identify which tenant to log into.
Attribute / Value: This is an attribute / value pair from your SAML 2.0 identity provider that you set to allow users access to a tenant. (This could be an attribute that describes the organization the user belong, their department or some other higher level attribute.)
- If you’re not using SSO, you can provide placeholder values such as “01” and “02”.
- If you are using SSO, and don’t have an attribute for your users at the organizational / department level, you can use a wild card. Click here for more info on using wild card
Main Account Email Address: This is the email address that you set as the main account admin for the tenant. When this person logs in, they will be a main account holder for the tenant and can make changes / add more users etc. You can leave this blank, Reftab will auto-generate a user.
In this screenshot below, a new tenant for “Business School” is being added. The attribute is “major” and value is “business”. This tells Reftab that after a user authenticates, check that ‘major’ is listed on their SAML token with a value of “business”, and if so, log them into the Business School tenant.
REMINDER: If using SSO, you must expose the attribute from your identity provider before users login. This is because each user logging in, must match a tenant’s attribute / value mapping, or they will get an error saying ‘the user authenticated but mapping failed’. If you are not using SSO, you can add users manually to a tenant.
Click “Save Tenant” when done.
Wild Card Routing
To know which users can access a tenant, you can pass a specific attribute and value. Or, you can use a wild card. A wildcard attribute should be something every user has on their SAML Assertion. For example, in the image below Reftab looks for ’email’ and if found, allows them access the APAC Region tenant. The wild card is indicated by “*”.
The advantage of using a wildcard is that it makes it easier to manage access to tenants. But if further limitations are needed, don’t use a wild card, use a specific attribute and value.
Automatically Provision Users Into Tenants with Just-In-Time Provisioning
After a user is allowed to access a tenant they must have an access role assigned to them. Just-in-time provisioning automates this process thus, eliminating the need to create user accounts in advance.
For example, when an “employeeRole” (attribute) from the “finance” (value) team attempts to login, Reftab will create them as a user under an access role appropriate for them. (It is perfectly acceptable to use the same attribute / value as saved at the tenant level.)
After saving the tenant, click “Add / Edit Users and Just-in-time Provisioning“.
Next, click “Just-In-Time User Provisioning“
You will need to define attribute and value pairs for each type of user and set the role they will belong to and set an access role such as, Administrator, editor, viewer, etc, or a custom role.
Click “Add Row” and provide an attribute, value and a role.
Put simply, there are three stages to tenancy login:
- The user authenticates with single sign on.
- Next, Reftab checks that the user is allowed access to a tenant.
- Finally, Reftab checks that the user is mapped to an access role within the tenant.
The screenshot below shows the just-in-time settings for a tenant called “Business School”. There are two rows in the screenshot establishing two mapping rules:
1.userType student -> viewer
2.userType staff -> Administrator
This means, On the SAML token, there should be an attribute for “userType”. If a value for userType is, “student” then the user will be provisioned with the the role of “Viewer“. Users with the userType of “staff” will be provisioned with the role of “Administrator“. If someone logs in and they’re not a student or staff userType, they will not be allowed in.
Click “Save Just-In-Time Provisioning” when done. Now whenever a user logs in, the system will be ready to determine who they are and provision them accordingly.
Add Users Manually to Tenant:
If you don’t want to sync users from your IT infrastructure via SCIM or use just-in-time provisioning, you can add users manually into tenants.
An administrator who has access to the super tenant can login and click “Settings” > “Tenants“
NOTE: If you do not see an option for “tenants”, you are not logged into your super tenant.
Find the tenant you want to add users to and click, “Edit Users and Sign-On“
NOTE: If you do not see an option for “tenants”, you are not logged into your super tenant.
Next, click “Add / Edit User Accounts“
Next, click “Add Sub Account“
From here, you can add the users email address (which is what they will use as their username) and save them to an access role.
Click, “Save Sub Account” when done.
Sync Users to Tenants via SCIM:
SCIM is ideal because it gives you the ability to create a user account in one system and then have matching accounts automatically created in additional systems the user needs access to.
Reftab allows you to sync your users from Active Directory, Okta and other applications that utilize a SAML 2.0 identity provider to configure a SCIM integration.
Follow these guides on how to setup a SCIM integration:
Azure AD: https://www.reftab.com/faq/scim-azure-active-directory
OKTA: https://www.reftab.com/faq/scim-okta
Notes on SCIM With multi-tenancy:
If you set up the SCIM integration at the super tenant level, it applies to all the tenants. Meaning, you can filter users into their respective tenants by mapping groups to tenants.
Otherwise, if you setup the SCIM integration within one, individual tenant, the SCIM connection will only be applicable to that one tenant.
It’s not suggested to setup SCIM in both the super and individual tenants. It should be done either only at the super level or within each individual tenant.
Users Can Belong to Multiple Tenants:
If a user is allowed access to multiple tenants, upon login they’ll be asked which tenant they would like to proceed to:
Once logged in, if a user wants to switch to another tenant, they can do so from the upper-right hand corner:
If a user only has access to one tenant, they wont be able to see other tenants. Only administrators can add other users. If someone wants to be added to another tenant, they will need to reach out to their Reftab admin.
For Help
Email [email protected] for any assistance or questions.
Thank you!