Add documentation for dynamic configuration of tenancy in Dashboards

_security/multi-tenancy/dynamic-config.md

@@ -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
+
+Multi-tenancy includes dynamic configuration options in OpenSearch Dashboards so you can manage 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 descriptions of the options currently covered by dynamic configuration:
+
+- **Disable or enable multi-tenancy** - Administrators can disable and enable multi-tenancy dynamically. Disabling multi-tenancy does not pose a risk of data loss. If and when an administrator chooses to reenable tenancy, all previously saved objects are preserved and made available.  The default is `true`.
+
+  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 reenabled all previously saved objects are preserved and made available.
+- **Default tenant** - This option allows an administrator to choose either a global, private, or custom tenant as the default when users log in. In cases 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 more information about this setting.
+
+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. 
+
+The global tenant, however, is a special case. Because this tenant is never disabled, users with the 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.
+
+
+## Configuring multi-tenancy in OpenSearch Dashboards
+
+To configure multi-tenancy in Dashboards, follow these steps:
+
+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 pop-up window appears listing the configuration items you've changed and asks you to review your changes.
+1. Select the check boxes beside the items you want to confirm and then select **Apply changes**. The changes are implemented dynamically.
+
+
+## Configuring multi-tenancy with the REST API
+
+In addition to using the Dashboards interface, you can manage dynamic configurations using the REST API. 
+
+### Get tenancy configuration
+
+The GET call retrieves settings for the dynamic configuration:
+
+```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
+
+The PUT call updates settings for dynamic configuration:
+
+```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:
+
+```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"
+}
+```
+

_security/multi-tenancy/mt-agg-view.md

@@ -34,9 +34,9 @@ In subsequent releases, we plan to expand the functionality of this feature to i
 
 In this first experimental phase of development, there are some limitations that should be observed before enabling the feature and using it in a test environment:
 
-* The feature can only be used in a new cluster. At this time, the feature is not suported by clusters already in use.
+* The feature can only be used in a new cluster. At this time, the feature is not supported 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](#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.
 
 These limitations will be addressed in upcoming releases.
 

_security/multi-tenancy/multi-tenancy-config.md

@@ -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`. |
+| `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` | When `true`, the Security plugin removes any content that a user is not allowed to see from the search results. When `false`, the plugin returns a security exception. Default is `false`. |
 
-`opensearch_dashboards.yml` has some additional settings:
+The `opensearch_dashboards.yml` file includes additional settings:
 
 ```yml
 opensearch.username: kibanaserver
@@ -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 private tenants. 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`. |
 
 
 ## Add tenants

_security/multi-tenancy/tenant-index.md

@@ -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: the global tenant and a private tenant. Multi-tenancy also provides the option to create custom tenants.
 
-- **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. 
+- **Global** -- This tenant is shared between every OpenSearch Dashboards user. It does allow for sharing objects among users who have access to it.
+- **Private** -- This tenant is exclusive to each user and can't be shared. It does not allow you to access routes or index patterns created by the user's global tenant.
+- **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.
 
-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 the following:
 
 - 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:
 
@@ -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.
+
+For 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/).