Multi-tenancy
Overview
Multi-tenancy allows you to share different content types from a single master source to multiple tenant destinations. This feature has two key types of players:
A single Master Instance
Multiple Tenant Instance(s)
A multi-tenancy relationship can only be established if you have one Master Instance and at least one Tenant Instance set up. As the name suggests, the master instance holds the source of data, while tenant instances are receivers of these data. This relationship is one-way: only the master instance can push data into the tenant instances, and tenant instances will be unable to edit or delete these shared items.
Reader Note
A tenant instance functions like a standard instance of D3 SOAR – however, certain capabilities are limited due to the multi-tenancy relationship:
Tenant instances cannot make edits to any shared content from the master instance
Tenant instances cannot create their own sites: the master instance creates sites for each specific tenant
Tenant instances cannot request updates from the master instance
Tenant Onboarding
In order to establish a connection between the master and tenant instance, you have to first onboard the tenant in the master instance.
Instance Registration
In Tenant Instance
Navigate to Configuration > Application Setting > Master Instance Registration
Click on Generate New Key
Click on Add
Copy this key and pass this key securely to the administrator of the Master instance
In Master Instance
Navigate to Configuration > Tenant Management
Click on + Add Tenant
Enter in the tenant instance URL and the tenant key you were provided with
Click on Register and Initiate
Result
The tenant instance is now connected to the master instance
Instance Initialization
Once a successful connection is established between a master and tenant instance, each of the instances will perform the following initialization procedures:
In Tenant Instance
Information about the master instance such as the URL, IP Address, and connection status can be found in Configuration > Master Instance Details
A new connection named Master will be created in built-in integrations
This connection is view only.
Information about Users, Groups, and Roles will be received from the master instance
The corresponding Region D3 agent will be automatically synchronized
In Master Instance
Information about the new tenant such as the URL, IP Address, and connection status can be found in Configuration > Tenant Management
A new connection with the name of the tenant instance will be created in D3 Integration
The master instance will clear all information about Users, Groups, and Roles in the tenant instance
maybe also clear all sites
maybe also share incident type
The master instance’s Users, Groups, and Roles information will be pushed to tenant
The corresponding Region D3 agent will be automatically synchronized
Master Instance
The master instance contains special features to help you manage, create, and share data sharing amongst your tenant instances:
View as Tenant Instance
The master instance has the ability to access any of its tenant instances.
To navigate to a tenant instance
Click on the Instance dropdown located in the top right of the application
Select your tenant instance
Result
You will be redirected to the tenant instance in a new window.
Reader Note
You can also view the information of the current instance you are viewing by clicking on the (i) button next to the dropdown.
Tenant Management
You can view all your connected tenants’ information in the Tenant Management module. This module is located in Configuration > Tenant Management. Here, you can:
Add a new Tenant
View Tenant Information
Tenant Details
Tenant Sites
Add a new Tenant
Prerequisite: You must have the target tenant’s instance URL and a valid tenant key.
Navigate to Configuration > Tenant Management
Click on + Add Tenant
Enter in the tenant instance URL and the tenant key you were provided with
Click on Register and Initiate
Result
Tenant instance is now connected to the master instance
View Tenant Information
The tenants are sorted by Region and displayed in a table view. You can view a tenant’s information, which includes:
ID
Name
URL
IP Address
Connection
Connection Status
Initialization Status
Shared Content Management
In the master instance, you are able to share content to all tenant instances. These shared content will be view only from the tenant’s perspective – tenants will be able to use the shared content, but they will not be able to edit or delete any shared content. The Shared Content module is located in Configuration > Tenant Management. There are nine types of content you can share – each content type will be explained in detail in the following sections:
Event Playbooks
Incident Playbooks
Integration
Utility Commands
Connections
Global List
Event Automation Rules
Users / Group / Roles
Incident Forms
Once a piece of content is shared, you can view the content’s share status in the Shared to Tenants column in the content list. This status is a summary of the statuses across all tenants. There are three possible states:
State | Description |
---|---|
Successful | The content is successfully shared to all tenants |
Sharing | The content is currently being shared with all tenants |
Incomplete | The content is not fully shared to all tenants. Depending on the content type, there are multiple reasons that a piece of content might fail to share. In general, there are a few reasons that may cause the sharing to fail: There is a new version of the content and it is outdated on some of the tenant sites |
Not Shared | The content has not been shared yet |
If you see the Incomplete status on a piece of shared content, you can view which tenant(s) caused this error in the sharing log. In general, if data/configuration has been changed in any content pieces, the status will change to Incomplete as the content is now out of date. However, in some cases, certain content types inherently carry site-specific data: Incident Playbooks, Connections, Global Lists, and Event Automation Rules. For these content types, you can view a detailed breakdown of which sites might have caused a failure in the sharing process in the sharing log details.
To view sharing log details
In this example, one of the incident playbooks “Email Protection - Phishing Playbook” failed to share with all tenants.
Navigate to Configuration > Tenant Management > Shared Content > Incident Playbooks
Click on the content that has an Incomplete share status
In the right-most panel, you can see which tenant caused this failed sharing, indicated by the X icon.
Hover over (?) next to the X icon. The tooltip will display the summary message explaining the cause of this error.
Since incident playbooks contain site data, you can view a detailed breakdown of which site(s) within this tenant caused the sharing error. To do so,
Click on the tenant with a failed status
Result
The pop-up window will display all the sites that failed to receive this item.
To share/reshare content
In this example, we will share a few selected incident playbooks to all tenants. The same steps apply to resharing content.
Navigate to Configuration > Tenant Management > Shared Content > Incident Playbooks
Select the content you would like to share/reshare
Click on Share
Result
The selected content will be shared to all tenants. Once it is done sharing, the status will be come Successful or Incomplete.
Reader Note
Tenants can identify content that was shared with the Shared tag.
Content Types
Each of the following content types is integral to a well-functioning D3 SOAR system. You can share these contents to help set up your tenant instances.
Event Playbooks | Event playbooks are pre-determined workflows that are applied to events at different stages of their life cycle. For an event playbook to be eligible to share, it must be submitted at least once. In other words, the event playbook must have at least one live version. The newest version of the playbook will be shared, along with specific content pieces that the playbook uses:
|
---|---|
Incident Playbooks | Incident playbooks are similar to event playbooks, but applied to incidents instead. One key difference is that incident playbooks require the playbook to be Published in addition to being live. Therefore, when an incident playbook is shared to tenants, it will also be automatically published to all of the tenants’ sites. If any of the sites are inactive, it will return an error and cause the playbook to be Incomplete. The newest version of the playbook will be shared, along with specific content pieces that the playbook uses:
|
Integrations | Integrations connects D3 SOAR to various third-party systems in order to exchange data. The following integration information will be shared:
Only custom integrations or configured built-in integrations can be shared. Please note that all connection data will not be shared as it is managed in the Connections section. |
Utility Commands | Utility Commands are out-of-the-box commands that you can use to manipulate your data. All custom utility commands will be shared – similar to the playbooks, only versions with at least one live version can be shared. When a new version of the command is submitted, any playbooks that use this utility command will also be automatically updated. |
Connections | Connections are saved credentials used to connect to different third-party systems. Only connections that have the Tenant toggle activated can be shared. Once this toggle is activated, you can define the specific Region, Tenant, and Tenant Site this connection can be used in. In cases where two connections’ tenant configurations overlap, the more specific case will apply. For example, connections with a specific Tenant Site selected have priority over connections that have all sites selected under Tenant Site. In addition, all connections inherent a custom property where different connections can have the same name. You may encounter situations where various sites utilize different sets of login credentials; instead of creating site-specific playbooks, this property allows you to select a connection by name when configuring a command task. The system will automatically check if the site contains a valid connection with the same name when the playbook executes. |
Global List | Global lists are lists that store reusable data across the system in JSON format. All data related to a global list will be shared, including its Active status. However, site permission data will not apply – the global list will be accessible by all sites within a tenant. |
Event Automation Rules | Event Automation Rules enable you to automate the escalation and dismissal of events by pre-defining a set of criteria for the system to match. Only automation rules with the Shared by default toggle enabled can be shared with tenants. All data related to an automation rule will be shared, including its Active status. However, site permission data will not apply – the automation rule will be accessible by all sites within a tenant. |
Incident Forms | Incident forms are user-defined sections within the incident workspace; each form belongs to a specific incident type. All incident types and their forms can be shared to tenants. All tenant sites will be able to access the shared incident forms. |
Users / Groups / Roles | The Users / Groups / Roles configuration in the master instance will be automatically shared to tenants when a tenant instance is initialized. You can reshare this information to all tenants if you made changes in the master instance. |
Playbook: Testing with Tenant Connections
In D3 SOAR, all playbooks have the ability to be tested with sample data. In the master instance, you have the additional ability to test a playbook’s workflow with the connection data of a tenant. This can help you verify if the playbook tasks will work in different tenant site instances.
To test with tenant connections in an event playbook
Click on the Test button
In the pop-up window, build your test data like a normal event playbook
Enable the Test the event playbook in a Tenant environment toggle
Select the Region, Tenant, and Site
Example: AMER, AMER Tenant, Security OperationsClick Run Test
Result
The event playbook will be tested with the specified site’s connection information.
To test in Incident Playbook
Click on the Test button
In the pop-up window, select an incident to use as sample data
Enable the Test the event playbook in a Tenant environment toggle
Select the specific Region, Tenant, and Site
Example: AMER, AMER Tenant, Security OperationsClick Run Test
Result
The incident playbook will be tested with the specified site’s connection information.
Multi-tenancy Utility Commands
User Onboarding/Offboarding | Tenant Onboarding | System Import/Explore |
---|---|---|
CreateUser | CreateTenantSite | CreateSite |
DeleteUser | CreateOrUpdateConnectionByClone | ImportPlaybookFromXML |
InactiveUser | SyncConnection | ImportIntegrationFromXML |
SyncAllUserGroupRole | SyncEventAutomationRule | ImportCommandFromXML |
PublishMasterPlaybookToAllSite | ImportEventAutomationRule | |
ShareMasterGlobalList | ImportConnection | |
ImportEventAutomationRule | ||
CreateGlobalList | ||
PublishMasterPlaybookToAllSite | ||
ShareMasterGlobalList |