Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add documentation for dynamic configuration of tenancy in Dashboards #3694

Merged
merged 18 commits into from
Apr 21, 2023
Merged
Show file tree
Hide file tree
Changes from 12 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 109 additions & 0 deletions _security/multi-tenancy/dynamic-config.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
---
layout: default
title: Dynamic configuration in OpenSearch Dashboards
parent: OpenSearch Dashboards multi-tenancy
nav_order: 147
---


# Dynamic configuration in OpenSearch Dashboards

Dynamic configuration of multi-tenancy in OpenSearch Dashboards provides options to make common settings for tenancy without having to make changes to the configuration YAML files on each node and then restart the cluster. You can take advantage of this functionality by using the Dashboards interface or the REST API. The following list includes description of the options currently covered by dynamic configuration:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we avoid making this into a feature by calling out the functionality? For example, "You can dynamically configure your multi-tenancy settings in OpenSearch Dashboards without making changes to the configuration YAML files on each note and then restarting the cluster."

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see your point. But I don't want to lead out a new section with "You can...". How about ...
"Multi-tenancy includes dynamic configuration options in OpenSearch Dashboards so you can make common settings for tenancy without having to make changes to the configuration YAML files on each node and then restart the cluster."
I've revised the sentence like so.


- **Disable or enable multi-tenancy** - Administrators can disable and enable multi-tenancy dynamically. Disabling multi-tenancy does not pose a risk for loss of data. If and when an administrator chooses to re-enable tenancy, all previously saved objects are preserved and made available. The default is `true`.
cwillum marked this conversation as resolved.
Show resolved Hide resolved

This setting does not have an impact on the global tenant, which always remains enabled.
{: .note }

- **Disable or enable private tenant** - This option allows administrators to disable and enable private tenants. As with the enable multi-tenancy setting, when private tenants are re-enabled all previously saved objects are preserved and made available.
cwillum marked this conversation as resolved.
Show resolved Hide resolved
- **Default tenant** - This option allows an administrator to choose either a global, private, or custom tenant as the default when users sign on. In the case where a user doesn't have access to the default tenant (for example, if a custom tenant unavailable to the user was specified as the default), the default transitions to the preferred tenant, which is specified by the `opensearch_security.multitenancy.tenants.preferred` setting in the `opensearch-dashboards.yml` file. See [Multi-tenancy configuration]({{site.url}}{{site.baseurl}}/security/multi-tenancy/multi-tenancy-config/) for details about this setting.
cwillum marked this conversation as resolved.
Show resolved Hide resolved

Depending on the specific changes made to multi-tenancy using dynamic configuration, some users may be logged out of their Dashboards session once the changes are saved. For example, if an admin user disables multi-tenancy, users with either a private or custom tenant as their selected tenant will be logged out and will need to log back in. Similarly, if an admin user disables private tenants, users with the private tenant selected will be logged out and will need to log back in.
cwillum marked this conversation as resolved.
Show resolved Hide resolved

The global tenant, however, is a special case. Since this tenant is never disabled, users with global tenant selected as their active tenant will experience no interruption to their session. Furthermore, changing the default tenant has no impact on a user's session.
cwillum marked this conversation as resolved.
Show resolved Hide resolved


## Configuring multi-tenancy in OpenSearch Dashboards

To make settings for multi-tenancy in Dashboards, follow these steps.
cwillum marked this conversation as resolved.
Show resolved Hide resolved

1. Begin by selecting **Security** in the Dashboards home page menu. Then select **Tenancy** from the Security menu on the left side of the screen. The **Multi-tenancy** page is displayed.
1. By default, the **Manage** tab is displayed. Select the **Configure** tab to display the dynamic settings for multi-tenancy.
* In the **Multi-tenancy** field, select the **Enable tenancy** check box to enable multi-tenancy. Clear the check box to disable the feature. The default is `true`.
* In the **Tenants** field, you can enable or disable private tenants for users. By default the check box is selected and the feature is enabled.
* In the **Default tenant** field, use the dropdown menu to select a default tenant. The menu includes Global, Private, and any other custom tenants that are available to users.
1. After making your preferred changes, select **Save changes** in the lower right corner of the window. A popup window appears listing the configuration items you've changed and asks you to review your changes.
cwillum marked this conversation as resolved.
Show resolved Hide resolved
1. Select the checkboxes beside the items you want to confirm and then select **Apply changes**. The changes are implemented dynamically.
cwillum marked this conversation as resolved.
Show resolved Hide resolved


## Configuring multi-tenancy with the REST API

In addition to the Dashboards interface, dynamic configurations can be made using the REST API.
cwillum marked this conversation as resolved.
Show resolved Hide resolved

### Get tenancy configuration

Retrieves settings for the dynamic configuration.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Retrieves settings for the dynamic configuration.
Retrieves settings for the dynamic configuration:

cwillum marked this conversation as resolved.
Show resolved Hide resolved

```json
GET /_plugins/_security/api/tenancy/config
```
{% include copy-curl.html %}

#### Example response

```json
{
"mulitenancy_enabled": true,
"private_tenant_enabled": true,
"default_tenant": "global tenant"
}
```

### Update tenant configuration

Updates settings for dynamic configuration.
cwillum marked this conversation as resolved.
Show resolved Hide resolved
cwillum marked this conversation as resolved.
Show resolved Hide resolved

```json
PUT /_plugins/_security/api/tenancy/config
{
"default_tenant": "custom tenant 1",
"private_tenant_enabled": false,
"mulitenancy_enabled": true
}
```
{% include copy-curl.html %}

### Example response

```json
{
"mulitenancy_enabled": true,
"private_tenant_enabled": false,
"default_tenant": "custom tenant 1"
}
```

### Dashboardsinfo API

You can also use the Dashboardsinfo API to retrieve the status of multi-tenancy settings for the user logged in to Dashboards.
cwillum marked this conversation as resolved.
Show resolved Hide resolved

```json
GET /_plugins/_security/dashboardsinfo
```
{% include copy-curl.html %}

### Example response

```json
{
"user_name" : "admin",
"not_fail_on_forbidden_enabled" : false,
"opensearch_dashboards_mt_enabled" : true,
"opensearch_dashboards_index" : ".kibana",
"opensearch_dashboards_server_user" : "kibanaserver",
"multitenancy_enabled" : true,
"private_tenant_enabled" : true,
"default_tenant" : "Private"
}
```

2 changes: 1 addition & 1 deletion _security/multi-tenancy/mt-agg-view.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ In this first experimental phase of development, there are some limitations that

* The feature can only be used in a new cluster. At this time, the feature is not suported by clusters already in use.
* Also, the feature should be used only in a test environment, not in production.
* Finally, once the feature has been enabled and used in a test cluster, the feature cannot be disabled for the cluster. Disabling the feature once it has been used to work with tenants and saved objects can result in the loss of saved objects and have an impact on tenant-to-tenant functionality.
* Finally, once the feature has been enabled and used in a test cluster, the feature cannot be disabled for the cluster. Disabling the feature once it has been used to work with tenants and saved objects can result in the loss of saved objects and can have an impact on tenant-to-tenant functionality. This can occur when disabling the feature in any one of three ways: disabling the aggregate view feature with the [feature flag]({{site.url}}{{site.baseurl}}/security/multi-tenancy/mt-agg-view/#enabling-aggregate-view-for-saved-objects/); disabling multi-tenancy with the traditional [multi-tenancy configuration]({{site.url}}{{site.baseurl}}/security/multi-tenancy/multi-tenancy-config/) setting; or disabling multi-tenancy with [dynamic configuration]({{site.url}}{{site.baseurl}}/security/multi-tenancy/dynamic-config/) settings.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is correct! Thanks for summarizing this up! @cwillum


These limitations will be addressed in upcoming releases.

Expand Down
34 changes: 19 additions & 15 deletions _security/multi-tenancy/multi-tenancy-config.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,19 +15,23 @@ config:
dynamic:
kibana:
multitenancy_enabled: true
private_tenant_enabled: true
default_tenant: global tenant
server_username: kibanaserver
index: '.kibana'
do_not_fail_on_forbidden: false
```

Setting | Description
:--- | :---
`multitenancy_enabled` | Enable or disable multi-tenancy. Default is true.
`server_username` | Must match the name of the OpenSearch Dashboards server user from `opensearch_dashboards.yml`. Default is `kibanaserver`.
`index` | Must match the name of the OpenSearch Dashboards index from `opensearch_dashboards.yml`. Default is `.kibana`.
`do_not_fail_on_forbidden` | If true, the security plugin removes any content that a user is not allowed to see from search results. If false, the plugin returns a security exception. Default is false.
| Setting | Description |
| :--- | :--- |
| `multitenancy_enabled` | Enable or disable multi-tenancy. Default is true. |
cwillum marked this conversation as resolved.
Show resolved Hide resolved
cwillum marked this conversation as resolved.
Show resolved Hide resolved
| `private_tenant_enabled` | Enable or disable the private tenant. Default is true. |
| `default_tenant` | Use to set the tenant that is available when users log in. |
| `server_username` | Must match the name of the OpenSearch Dashboards server user from `opensearch_dashboards.yml`. Default is `kibanaserver`. |
| `index` | Must match the name of the OpenSearch Dashboards index from `opensearch_dashboards.yml`. Default is `.kibana`. |
| `do_not_fail_on_forbidden` | If true, the security plugin removes any content that a user is not allowed to see from search results. If false, the plugin returns a security exception. Default is false. |
cwillum marked this conversation as resolved.
Show resolved Hide resolved

`opensearch_dashboards.yml` has some additional settings:
The `opensearch_dashboards.yml` file includes additional settings:

```yml
opensearch.username: kibanaserver
Expand All @@ -40,14 +44,14 @@ opensearch_security.multitenancy.tenants.preferred: ["Private", "Global"]
opensearch_security.multitenancy.enable_filter: false
```

Setting | Description
:--- | :---
`opensearch.requestHeadersAllowlist` | OpenSearch Dashboards requires that you add all HTTP headers to the allow list so that the headers pass to OpenSearch. Multi-tenancy uses a specific header, `securitytenant`, that must be present with the standard `Authorization` header. If the `securitytenant` header is not on the allow list, OpenSearch Dashboards starts with a red status.
`opensearch_security.multitenancy.enabled` | Enables or disables multi-tenancy in OpenSearch Dashboards. Default is true.
`opensearch_security.multitenancy.tenants.enable_global` | Enables or disables the global tenant. Default is true.
`opensearch_security.multitenancy.tenants.enable_private` | Enables or disables the private tenant. Default is true.
`opensearch_security.multitenancy.tenants.preferred` | Lets you change ordering in the **Tenants** tab of OpenSearch Dashboards. By default, the list starts with global and private (if enabled) and then proceeds alphabetically. You can add tenants here to move them to the top of the list.
`opensearch_security.multitenancy.enable_filter` | If you have many tenants, you can add a search bar to the top of the list. Default is false.
| Setting | Description |
| :--- | :--- |
| `opensearch.requestHeadersAllowlist` | OpenSearch Dashboards requires that you add all HTTP headers to the allow list so that the headers pass to OpenSearch. Multi-tenancy uses a specific header, `securitytenant`, that must be present with the standard `Authorization` header. If the `securitytenant` header is not on the allow list, OpenSearch Dashboards starts with a red status.
| `opensearch_security.multitenancy.enabled` | Enables or disables multi-tenancy in OpenSearch Dashboards. Default is true. |
| `opensearch_security.multitenancy.tenants.enable_global` | Enables or disables the global tenant. Default is true. |
| `opensearch_security.multitenancy.tenants.enable_private` | Enables or disables the private tenant. Default is true. |
| `opensearch_security.multitenancy.tenants.preferred` | Lets you change ordering in the **Tenants** tab of OpenSearch Dashboards. By default, the list starts with global and private (if enabled) and then proceeds alphabetically. You can add tenants here to move them to the top of the list. |
cwillum marked this conversation as resolved.
Show resolved Hide resolved
| `opensearch_security.multitenancy.enable_filter` | If you have many tenants, you can add a search bar to the top of the list. Default is false. |


## Add tenants
Expand Down
15 changes: 9 additions & 6 deletions _security/multi-tenancy/tenant-index.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,18 +10,19 @@ redirect_from:

# OpenSearch Dashboards multi-tenancy

*Tenants* in OpenSearch Dashboards are spaces for saving index patterns, visualizations, dashboards, and other OpenSearch Dashboards objects. Tenants are useful for safely sharing your work with other OpenSearch Dashboards users. You can control which roles have access to a tenant and whether those roles have read or write access. By default, all OpenSearch Dashboards users have access to two independent tenants:
*Tenants* in OpenSearch Dashboards are spaces for saving index patterns, visualizations, dashboards, and other OpenSearch Dashboards objects. OpenSearch allows users to create multiple tenants for multiple uses. Tenants are useful for safely sharing your work with other OpenSearch Dashboards users. You can control which roles have access to a tenant and whether those roles have read or write access. By default, all OpenSearch Dashboards users have access to two independent tenants: private and global. Multi-tenancy also provides the option to create custom tenants.
cwillum marked this conversation as resolved.
Show resolved Hide resolved

- **Private** - This tenant is exclusive to each user and can't be shared. You can't use it to access routes or index patterns made by the user's global tenant.
- **Global** - This tenant is shared between every OpenSearch Dashboards user.
- **Private** - This tenant is exclusive to each user and can't be shared. It does not allow you to access routes or index patterns made by the user's global tenant.
cwillum marked this conversation as resolved.
Show resolved Hide resolved
cwillum marked this conversation as resolved.
Show resolved Hide resolved
- **Global** - This tenant is shared between every OpenSearch Dashboards user. It does allow for sharing objects among users who have access to it.
cwillum marked this conversation as resolved.
Show resolved Hide resolved
- **Custom** - Administrators can create custom tenants and assign them to specific roles. Once created, these tenants can then provide spaces for specific groups of users.
cwillum marked this conversation as resolved.
Show resolved Hide resolved

The global tenant is not a *primary* tenant such that any action done within the global tenant is not replicated to a user's private tenant. If you make a change to your global tenant, you won't see that change reflected in your private tenant. Some example changes include, but are not limited to:
The global tenant is not a *primary* tenant in the sense that it replicates its content in a private tenant. To the contrary, if you make a change to your global tenant, you won't see that change reflected in your private tenant. Some example changes include, but are not limited to:
cwillum marked this conversation as resolved.
Show resolved Hide resolved

- Change advanced settings
- Create visualizations
- Create index patterns

You might use the private tenant for exploratory work, create detailed visualizations with your team in an `analysts` tenant, and maintain a summary dashboard for corporate leadership in an `executive` tenant.
To provide a practical example, you might use the private tenant for exploratory work, create detailed visualizations with your team in an `analysts` tenant, and maintain a summary dashboard for corporate leadership in an `executive` tenant.

If you share a visualization or dashboard with someone, you can see that the URL includes the tenant:

Expand All @@ -31,5 +32,7 @@ http://<opensearch_dashboards_host>:5601/app/opensearch-dashboards?security_tena

## Next steps

To get started with tenants, see [Multi-tenancy configuration]({{site.url}}{{site.baseurl}}/security/multi-tenancy/multi-tenancy-config/) for information on enabling multi-tenancy, adding tenants, and assigning roles to tenants.
To get started with tenants, see [Multi-tenancy configuration]({{site.url}}{{site.baseurl}}/security/multi-tenancy/multi-tenancy-config/) for information about enabling multi-tenancy, adding tenants, and assigning roles to tenants.

To see information about making dynamic changes to the multi-tenancy configuration, see [Dynamic configuration in OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/security/multi-tenancy/dynamic-config/).
cwillum marked this conversation as resolved.
Show resolved Hide resolved