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

1. Navigate to Configuration > Application Setting > Master Instance Registration

2. Click on Generate New Key

3. Click on Add

4. Copy this key and pass this key securely to the administrator of the Master instance

In Master Instance

1. Navigate to Configuration > Tenant Management

2. Click on + Add Tenant

3. Enter in the tenant instance URL and the tenant key you were provided with

4. 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

1. Information about the master instance such as the URL, IP Address, and connection status can be found in Configuration > Master Instance Details

2. A new connection named Master will be created in built-in integrations

3. This connection is view only.

4. Information about Users, Groups, and Roles will be received from the master instance

5. The corresponding Region D3 agent will be automatically synchronized

In Master Instance

1. Information about the new tenant such as the URL, IP Address, and connection status can be found in Configuration > Tenant Management

2. A new connection with the name of the tenant instance will be created in D3 Integration

3. The master instance will clear all information about Users, Groups, and Roles in the tenant instance

   1. maybe also clear all sites

   2. maybe also share incident type

4. The master instance’s Users, Groups, and Roles information will be pushed to tenant

5. 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:

1. View as Tenant Instance

2. Tenant Management

3. Shared Content Management

4. Playbook: Testing with Tenant Connections

5. Multi-tenancy Utility Commands

View as Tenant Instance

The master instance has the ability to access any of its tenant instances.

To navigate to a tenant instance

1. Click on the Instance dropdown located in the top right of the application

2. 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:

1. Add a new Tenant

2. View Tenant Information

   1. Tenant Details

   2. 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

1. Click on + Add Tenant

2. Enter in the tenant instance URL and the tenant key you were provided with

3. 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:

1. ID

2. Name

3. URL

4. IP Address

5. Connection

6. Connection Status

7. 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:

1. Event Playbooks

2. Incident Playbooks

3. Integration

4. Utility Commands

5. Connections

6. Global List

7. Event Automation Rules

8. Users / Group / Roles

9. 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 The master instance was not able to connect to a tenant site when the sharing was initiated Certain sites were not active when the content was shared (content types with site data only) Specific errors relating to each content type. You can view the error message by hovering over the (?) icon in the sharing log.
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.

1. Navigate to Configuration > Tenant Management > Shared Content > Incident Playbooks

2. Click on the content that has an Incomplete share status

3. In the right-most panel, you can see which tenant caused this failed sharing, indicated by the X icon.

4. Hover over (?) next to the X icon. The tooltip will display the summary message explaining the cause of this error.

5. 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,

6. 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.

1. Navigate to Configuration > Tenant Management > Shared Content > Incident Playbooks

2. Select the content you would like to share/reshare

3. 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: Custom Utility Commands Custom Integrations Custom Commands Integration field mapping
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: Custom Utility Commands Custom Integrations Custom Commands Integration field mapping
Integrations	Integrations connects D3 SOAR to various third-party systems in order to exchange data. The following integration information will be shared: Connection Parameters Built-in Commands: Event Field Mapping Incident Field Mapping Custom Commands 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

1. Click on the Test button

2. In the pop-up window, build your test data like a normal event playbook

3. Enable the Test the event playbook in a Tenant environment toggle

4. Select the Region, Tenant, and Site
   Example: AMER, AMER Tenant, Security Operations

5. Click Run Test

Result

The event playbook will be tested with the specified site’s connection information.

To test in Incident Playbook

1. Click on the Test button

2. In the pop-up window, select an incident to use as sample data

3. Enable the Test the event playbook in a Tenant environment toggle

4. Select the specific Region, Tenant, and Site
   Example: AMER, AMER Tenant, Security Operations

5. Click Run Test

Result

The incident playbook will be tested with the specified site’s connection information.

Multi-tenancy Utility Commands