From c4cf6838bf8bfd6264a914d07fa71cb8a6c0a855 Mon Sep 17 00:00:00 2001 From: aetter Date: Tue, 8 Jun 2021 15:35:12 -0700 Subject: [PATCH] Updates security settings --- docs/alerting/api.md | 2 +- docs/alerting/monitors.md | 4 +- docs/alerting/security.md | 2 +- docs/im/index-rollups/index.md | 2 +- docs/im/index-rollups/rollup-api.md | 4 +- docs/im/ism/api.md | 5 +- docs/opensearch/install/docker-security.md | 48 ++++++------ docs/opensearch/install/docker.md | 6 +- docs/security/access-control/api.md | 12 +-- docs/security/access-control/field-masking.md | 4 +- docs/security/access-control/impersonation.md | 4 +- docs/security/access-control/multi-tenancy.md | 20 ++--- docs/security/access-control/users-roles.md | 4 +- docs/security/audit-logs/field-reference.md | 2 +- docs/security/audit-logs/index.md | 40 +++++----- docs/security/audit-logs/storage-types.md | 52 ++++++------- docs/security/configuration/client-auth.md | 2 +- docs/security/configuration/configuration.md | 12 +-- docs/security/configuration/disable.md | 2 +- .../configuration/generate-certificates.md | 6 +- docs/security/configuration/ldap.md | 4 +- docs/security/configuration/openid-connect.md | 24 +++--- docs/security/configuration/proxy.md | 6 +- docs/security/configuration/saml.md | 2 +- docs/security/configuration/security-admin.md | 2 +- docs/security/configuration/system-indices.md | 6 +- docs/security/configuration/tls.md | 78 +++++++++---------- docs/troubleshoot/openid-connect.md | 14 ++-- docs/troubleshoot/tls.md | 8 +- 29 files changed, 188 insertions(+), 189 deletions(-) diff --git a/docs/alerting/api.md b/docs/alerting/api.md index eb0e8364..867ecf18 100644 --- a/docs/alerting/api.md +++ b/docs/alerting/api.md @@ -460,7 +460,7 @@ GET _plugins/_alerting//stats/ "failed": 0 }, "cluster_name": "475300751431:alerting65-dont-delete", - "opensearch.scheduled_jobs.enabled": true, + "plugins.scheduled_jobs.enabled": true, "scheduled_job_index_exists": true, "scheduled_job_index_status": "green", "nodes_on_schedule": 9, diff --git a/docs/alerting/monitors.md b/docs/alerting/monitors.md index 66d483b8..0b24bf23 100644 --- a/docs/alerting/monitors.md +++ b/docs/alerting/monitors.md @@ -78,8 +78,8 @@ You can enter individual email addresses or an email group in the **Recipients** If your email provider requires SSL or TLS, you must authenticate each sender account before you can send an email. Enter these credentials in the OpenSearch keystore using the CLI. Run the following commands (in your OpenSearch directory) to enter your username and password. The `` is the name you entered for **Sender** earlier. ```bash -./bin/opensearch-keystore add opendistro.alerting.destination.email..username -./bin/opensearch-keystore add opendistro.alerting.destination.email..password +./bin/opensearch-keystore add plugins.alerting.destination.email..username +./bin/opensearch-keystore add plugins.alerting.destination.email..password ``` **Note**: Keystore settings are node-specific. You must run these commands on each node. diff --git a/docs/alerting/security.md b/docs/alerting/security.md index b046ec31..3e04e321 100644 --- a/docs/alerting/security.md +++ b/docs/alerting/security.md @@ -44,7 +44,7 @@ Next, enable the following setting: PUT _cluster/settings { "transient": { - "opendistro.alerting.filter_by_backend_roles": "true" + "plugins.alerting.filter_by_backend_roles": "true" } } ``` diff --git a/docs/im/index-rollups/index.md b/docs/im/index-rollups/index.md index e83fe5a4..d4545243 100644 --- a/docs/im/index-rollups/index.md +++ b/docs/im/index-rollups/index.md @@ -1,6 +1,6 @@ --- layout: default -title: Index Rollups +title: Index rollups nav_order: 35 parent: Index management has_children: true diff --git a/docs/im/index-rollups/rollup-api.md b/docs/im/index-rollups/rollup-api.md index a13106cc..cd781d56 100644 --- a/docs/im/index-rollups/rollup-api.md +++ b/docs/im/index-rollups/rollup-api.md @@ -1,7 +1,7 @@ --- layout: default -title: Index Rollups API -parent: Index Rollups +title: Index rollups API +parent: Index rollups grand_parent: Index management redirect_from: /docs/ism/rollup-api/ nav_order: 9 diff --git a/docs/im/ism/api.md b/docs/im/ism/api.md index cfab714f..71f31124 100644 --- a/docs/im/ism/api.md +++ b/docs/im/ism/api.md @@ -452,13 +452,12 @@ GET _plugins/_ism/explain/index_1 ```json { "index_1": { - "index.opendistro.index_state_management.policy_id": "policy_1" + "index.plugins.index_state_management.policy_id": "policy_1" } } ``` -The `opendistro.index_state_management.policy_id` setting is deprecated starting from version 1.13.0. -We retain this field in the response API for consistency. +The `plugins.index_state_management.policy_id` setting is deprecated starting from ODFE version 1.13.0. We retain this field in the response API for consistency. --- diff --git a/docs/opensearch/install/docker-security.md b/docs/opensearch/install/docker-security.md index 88a3f18d..dd61e320 100644 --- a/docs/opensearch/install/docker-security.md +++ b/docs/opensearch/install/docker-security.md @@ -112,26 +112,26 @@ networks: Then make your changes to `opensearch.yml`. For a full list of settings, see [Security](../../../security/configuration/). This example adds (extremely) verbose audit logging: ```yml -opensearch_security.ssl.transport.pemcert_filepath: node.pem -opensearch_security.ssl.transport.pemkey_filepath: node-key.pem -opensearch_security.ssl.transport.pemtrustedcas_filepath: root-ca.pem -opensearch_security.ssl.transport.enforce_hostname_verification: false -opensearch_security.ssl.http.enabled: true -opensearch_security.ssl.http.pemcert_filepath: node.pem -opensearch_security.ssl.http.pemkey_filepath: node-key.pem -opensearch_security.ssl.http.pemtrustedcas_filepath: root-ca.pem -opensearch_security.allow_default_init_securityindex: true -opensearch_security.authcz.admin_dn: +plugins.security.ssl.transport.pemcert_filepath: node.pem +plugins.security.ssl.transport.pemkey_filepath: node-key.pem +plugins.security.ssl.transport.pemtrustedcas_filepath: root-ca.pem +plugins.security.ssl.transport.enforce_hostname_verification: false +plugins.security.ssl.http.enabled: true +plugins.security.ssl.http.pemcert_filepath: node.pem +plugins.security.ssl.http.pemkey_filepath: node-key.pem +plugins.security.ssl.http.pemtrustedcas_filepath: root-ca.pem +plugins.security.allow_default_init_securityindex: true +plugins.security.authcz.admin_dn: - CN=A,OU=UNIT,O=ORG,L=TORONTO,ST=ONTARIO,C=CA -opensearch_security.nodes_dn: +plugins.security.nodes_dn: - 'CN=N,OU=UNIT,O=ORG,L=TORONTO,ST=ONTARIO,C=CA' -opensearch_security.audit.type: internal_opensearch -opensearch_security.enable_snapshot_restore_privilege: true -opensearch_security.check_snapshot_restore_write_privileges: true -opensearch_security.restapi.roles_enabled: ["all_access", "security_rest_api_access"] +plugins.security.audit.type: internal_opensearch +plugins.security.enable_snapshot_restore_privilege: true +plugins.security.check_snapshot_restore_write_privileges: true +plugins.security.restapi.roles_enabled: ["all_access", "security_rest_api_access"] cluster.routing.allocation.disk.threshold_enabled: false -opensearch_security.audit.config.disabled_rest_categories: NONE -opensearch_security.audit.config.disabled_transport_categories: NONE +plugins.security.audit.config.disabled_rest_categories: NONE +plugins.security.audit.config.disabled_transport_categories: NONE ``` Use this same override process to specify new [authentication settings](../../../security/configuration/configuration/) in `/usr/share/opensearch/plugins/opensearch-security/securityconfig/config.yml`, as well as new default [internal users, roles, mappings, action groups, and tenants](../../../security/configuration/yaml/). @@ -166,13 +166,13 @@ volumes: Remember that the certificates you specify in your Docker Compose file must be the same as the certificates listed in your custom `opensearch.yml` file. At a minimum, you should replace the root, admin, and node certificates with your own. For more information about adding and using certificates, see [Configure TLS certificates](../security/configuration/tls.md). ```yml -opensearch_security.ssl.transport.pemcert_filepath: new-node-cert.pem -opensearch_security.ssl.transport.pemkey_filepath: new-node-cert-key.pem -opensearch_security.ssl.transport.pemtrustedcas_filepath: new-root-ca.pem -opensearch_security.ssl.http.pemcert_filepath: new-node-cert.pem -opensearch_security.ssl.http.pemkey_filepath: new-node-cert-key.pem -opensearch_security.ssl.http.pemtrustedcas_filepath: new-root-ca.pem -opensearch_security.authcz.admin_dn: +plugins.security.ssl.transport.pemcert_filepath: new-node-cert.pem +plugins.security.ssl.transport.pemkey_filepath: new-node-cert-key.pem +plugins.security.ssl.transport.pemtrustedcas_filepath: new-root-ca.pem +plugins.security.ssl.http.pemcert_filepath: new-node-cert.pem +plugins.security.ssl.http.pemkey_filepath: new-node-cert-key.pem +plugins.security.ssl.http.pemtrustedcas_filepath: new-root-ca.pem +plugins.security.authcz.admin_dn: - CN=admin,OU=SSL,O=Test,L=Test,C=DE ``` diff --git a/docs/opensearch/install/docker.md b/docs/opensearch/install/docker.md index effdf768..38c511d0 100644 --- a/docs/opensearch/install/docker.md +++ b/docs/opensearch/install/docker.md @@ -299,7 +299,7 @@ docker build --tag=opensearch-custom-plugin . docker run -p 9200:9200 -p 9600:9600 -v /usr/share/opensearch/data opensearch-custom-plugin ``` -You can also use a `Dockerfile` to pass your own certificates for use with the [Security](../../../security/) plugin, similar to the `-v` argument in [Configure OpenSearch](#configure-opensearch): +You can also use a `Dockerfile` to pass your own certificates for use with the [security](../../../security/) plugin, similar to the `-v` argument in [Configure OpenSearch](#configure-opensearch): ``` FROM opensearchproject/opensearch:{{site.opensearch_version}} @@ -313,11 +313,11 @@ Alternately, you might want to remove a plugin. This `Dockerfile` removes the se ``` FROM opensearchproject/opensearch:{{site.opensearch_version}} -RUN /usr/share/opensearch/bin/opensearch-plugin remove opensearch_security +RUN /usr/share/opensearch/bin/opensearch-plugin remove opensearch-security COPY --chown=opensearch:opensearch opensearch.yml /usr/share/opensearch/config/ ``` -In this case, `opensearch.yml` is a "vanilla" version of the file with no OpenSearch entries. It might look like this: +In this case, `opensearch.yml` is a "vanilla" version of the file with no plugin entries. It might look like this: ```yml cluster.name: "docker-cluster" diff --git a/docs/security/access-control/api.md b/docs/security/access-control/api.md index 91402708..4a1314c5 100644 --- a/docs/security/access-control/api.md +++ b/docs/security/access-control/api.md @@ -24,13 +24,13 @@ The security plugin REST API lets you programmatically create and manage users, Just like OpenSearch permissions, you control access to the security plugin REST API using roles. Specify roles in `opensearch.yml`: ```yml -opensearch_security.restapi.roles_enabled: ["", ...] +plugins.security.restapi.roles_enabled: ["", ...] ``` These roles can now access all APIs. To prevent access to certain APIs: ```yml -opensearch_security.restapi.endpoints_disabled..: ["", ...] +plugins.security.restapi.endpoints_disabled..: ["", ...] ``` Possible values for `endpoint` are: @@ -55,15 +55,15 @@ Possible values for `method` are: For example, the following configuration grants three roles access to the REST API, but then prevents `test-role` from making PUT, POST, DELETE, or PATCH requests to `_opensearch/_security/api/roles` or `_opensearch/_security/api/internalusers`: ```yml -opensearch_security.restapi.roles_enabled: ["all_access", "security_rest_api_access", "test-role"] -opensearch_security.restapi.endpoints_disabled.test-role.ROLES: ["PUT", "POST", "DELETE", "PATCH"] -opensearch_security.restapi.endpoints_disabled.test-role.INTERNALUSERS: ["PUT", "POST", "DELETE", "PATCH"] +plugins.security.restapi.roles_enabled: ["all_access", "security_rest_api_access", "test-role"] +plugins.security.restapi.endpoints_disabled.test-role.ROLES: ["PUT", "POST", "DELETE", "PATCH"] +plugins.security.restapi.endpoints_disabled.test-role.INTERNALUSERS: ["PUT", "POST", "DELETE", "PATCH"] ``` To use the PUT and PATCH methods for the [configuration APIs](#configuration), add the following line to `opensearch.yml`: ```yml -opensearch_security.unsupported.restapi.allow_securityconfig_modification: true +plugins.security.unsupported.restapi.allow_securityconfig_modification: true ``` diff --git a/docs/security/access-control/field-masking.md b/docs/security/access-control/field-masking.md index 84095953..a6e6c3dd 100644 --- a/docs/security/access-control/field-masking.md +++ b/docs/security/access-control/field-masking.md @@ -32,12 +32,12 @@ Field masking works alongside field-level security on the same per-role, per-ind You set the salt (a random string used to hash your data) in `opensearch.yml`: ```yml -opensearch_security.compliance.salt: abcdefghijklmnopqrstuvqxyz1234567890 +plugins.security.compliance.salt: abcdefghijklmnopqrstuvqxyz1234567890 ``` Property | Description :--- | :--- -`opensearch_security.compliance.salt` | The salt to use when generating the hash value. Must be at least 32 characters. Only ASCII characters are allowed. Optional. +`plugins.security.compliance.salt` | The salt to use when generating the hash value. Must be at least 32 characters. Only ASCII characters are allowed. Optional. Setting the salt is optional, but we highly recommend it. diff --git a/docs/security/access-control/impersonation.md b/docs/security/access-control/impersonation.md index 1fcfc70a..458ba9e6 100644 --- a/docs/security/access-control/impersonation.md +++ b/docs/security/access-control/impersonation.md @@ -20,7 +20,7 @@ Impersonation can occur on either the REST interface or at the transport layer. To allow one user to impersonate another, add the following to `opensearch.yml`: ```yml -opensearch_security.authcz.rest_impersonation_user: +plugins.security.authcz.rest_impersonation_user: : - - @@ -34,7 +34,7 @@ The impersonated user field supports wildcards. Setting it to `*` allows `AUTHEN In a similar fashion, add the following to enable transport layer impersonation: ```yml -opensearch_security.authcz.impersonation_dn: +plugins.security.authcz.impersonation_dn: "CN=spock,OU=client,O=client,L=Test,C=DE": - worf ``` diff --git a/docs/security/access-control/multi-tenancy.md b/docs/security/access-control/multi-tenancy.md index 4434535c..ff92c951 100644 --- a/docs/security/access-control/multi-tenancy.md +++ b/docs/security/access-control/multi-tenancy.md @@ -48,21 +48,21 @@ Setting | Description opensearch.username: kibanaserver opensearch.password: kibanaserver opensearch.requestHeadersWhitelist: ["securitytenant","Authorization"] -opensearch_security.multitenancy.enabled: true -opensearch_security.multitenancy.tenants.enable_global: true -opensearch_security.multitenancy.tenants.enable_private: true -opensearch_security.multitenancy.tenants.preferred: ["Private", "Global"] -opensearch_security.multitenancy.enable_filter: false +plugins.security.multitenancy.enabled: true +plugins.security.multitenancy.tenants.enable_global: true +plugins.security.multitenancy.tenants.enable_private: true +plugins.security.multitenancy.tenants.preferred: ["Private", "Global"] +plugins.security.multitenancy.enable_filter: false ``` Setting | Description :--- | :--- `opensearch.requestHeadersWhitelist` | OpenSearch Dashboards requires that you whitelist all HTTP headers that it passes to OpenSearch. Multi-tenancy uses a specific header, `securitytenant`, that must be present with the standard `Authorization` header. If the `securitytenant` header is not whitelisted, 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. +`plugins.security.multitenancy.enabled` | Enables or disables multi-tenancy in OpenSearch Dashboards. Default is true. +`plugins.security.multitenancy.tenants.enable_global` | Enables or disables the global tenant. Default is true. +`plugins.security.multitenancy.tenants.enable_private` | Enables or disables the private tenant. Default is true. +`plugins.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. +`plugins.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 diff --git a/docs/security/access-control/users-roles.md b/docs/security/access-control/users-roles.md index daab6bf2..a6288c14 100644 --- a/docs/security/access-control/users-roles.md +++ b/docs/security/access-control/users-roles.md @@ -110,13 +110,13 @@ Role | Description `anomaly_full_access` | Grants full permissions to all anomaly detection actions. `anomaly_read_access` | Grants permissions to view detectors, but not create, modify, or delete detectors. `all_access` | Grants full access to the cluster: all cluster-wide operations, write to all indices, write to all tenants. -`kibana_read_only` | A special role that prevents users from making changes to visualizations, dashboards, and other OpenSearch Dashboards objects. See `opensearch_security.readonly_mode.roles` in `opensearch_dashboards.yml`. Pair with the `kibana_user` role. +`kibana_read_only` | A special role that prevents users from making changes to visualizations, dashboards, and other OpenSearch Dashboards objects. See `plugins.security.readonly_mode.roles` in `opensearch_dashboards.yml`. Pair with the `kibana_user` role. `kibana_user` | Grants permissions to use OpenSearch Dashboards: cluster-wide searches, index monitoring, and write to various OpenSearch Dashboards indices. `logstash` | Grants permissions for Logstash to interact with the cluster: cluster-wide searches, cluster monitoring, and write to the various Logstash indices. `manage_snapshots` | Grants permissions to manage snapshot repositories, take snapshots, and restore snapshots. `readall` | Grants permissions for cluster-wide searches like `msearch` and search permissions for all indices. `readall_and_monitor` | Same as `readall`, but with added cluster monitoring permissions. -`security_rest_api_access` | A special role that allows access to the REST API. See `opensearch_security.restapi.roles_enabled` in `opensearch.yml` and [Access control for the API](../api/#access-control-for-the-api). +`security_rest_api_access` | A special role that allows access to the REST API. See `plugins.security.restapi.roles_enabled` in `opensearch.yml` and [Access control for the API](../api/#access-control-for-the-api). `reports_read_access` | Grants permissions to generate on-demand reports, download existing reports, and view report definitions, but not to create report definitions. `reports_instances_read_access` | Grants permissions to generate on-demand reports and download existing reports, but not to view or create report definitions. `reports_full_access` | Grants full permissions to reports. diff --git a/docs/security/audit-logs/field-reference.md b/docs/security/audit-logs/field-reference.md index 9694cf28..541f9fbd 100644 --- a/docs/security/audit-logs/field-reference.md +++ b/docs/security/audit-logs/field-reference.md @@ -18,7 +18,7 @@ The following attributes are logged for all event categories, independent of the Name | Description :--- | :--- `audit_format_version` | The audit log message format version. -`audit_category` | The audit log category, one of FAILED_LOGIN, MISSING_PRIVILEGES, BAD_HEADERS, SSL_EXCEPTION, opensearch_SECURITY_INDEX_ATTEMPT, AUTHENTICATED or GRANTED_PRIVILEGES. +`audit_category` | The audit log category. FAILED_LOGIN, MISSING_PRIVILEGES, BAD_HEADERS, SSL_EXCEPTION, OPENSEARCH_SECURITY_INDEX_ATTEMPT, AUTHENTICATED, or GRANTED_PRIVILEGES. `audit_node_id ` | The ID of the node where the event was generated. `audit_node_name` | The name of the node where the event was generated. `audit_node_host_address` | The host address of the node where the event was generated. diff --git a/docs/security/audit-logs/index.md b/docs/security/audit-logs/index.md index b0d5c072..97b4948b 100644 --- a/docs/security/audit-logs/index.md +++ b/docs/security/audit-logs/index.md @@ -16,7 +16,7 @@ To enable audit logging: 1. Add the following line to `opensearch.yml` on each node: ```yml - opensearch_security.audit.type: internal_opensearch + plugins.security.audit.type: internal_opensearch ``` This setting stores audit logs on the current cluster. For other storage options, see [Audit Log Storage Types](storage-types/). @@ -57,22 +57,22 @@ These default log settings work well for most use cases, but you can change sett To exclude categories, set: ```yml -opensearch_security.audit.config.disabled_rest_categories: -opensearch_security.audit.config.disabled_transport_categories: +plugins.security.audit.config.disabled_rest_categories: +plugins.security.audit.config.disabled_transport_categories: ``` For example: ```yml -opensearch_security.audit.config.disabled_rest_categories: AUTHENTICATED, opensearch_SECURITY_INDEX_ATTEMPT -opensearch_security.audit.config.disabled_transport_categories: GRANTED_PRIVILEGES +plugins.security.audit.config.disabled_rest_categories: AUTHENTICATED, opensearch_SECURITY_INDEX_ATTEMPT +plugins.security.audit.config.disabled_transport_categories: GRANTED_PRIVILEGES ``` If you want to log events in all categories, use `NONE`: ```yml -opensearch_security.audit.config.disabled_rest_categories: NONE -opensearch_security.audit.config.disabled_transport_categories: NONE +plugins.security.audit.config.disabled_rest_categories: NONE +plugins.security.audit.config.disabled_transport_categories: NONE ``` @@ -81,8 +81,8 @@ opensearch_security.audit.config.disabled_transport_categories: NONE By default, the security plugin logs events on both REST and the transport layer. You can disable either type: ```yml -opensearch_security.audit.enable_rest: false -opensearch_security.audit.enable_transport: false +plugins.security.audit.enable_rest: false +plugins.security.audit.enable_transport: false ``` @@ -91,7 +91,7 @@ opensearch_security.audit.enable_transport: false By default, the security plugin includes the body of the request (if available) for both REST and the transport layer. If you do not want or need the request body, you can disable it: ```yml -opensearch_security.audit.log_request_body: false +plugins.security.audit.log_request_body: false ``` @@ -113,10 +113,10 @@ audit_trace_resolved_indices: [ You can disable this feature by setting: ```yml -opensearch_security.audit.resolve_indices: false +plugins.security.audit.resolve_indices: false ``` -Disabling this feature only takes effect if `opensearch_security.audit.log_request_body` is also set to `false`. +Disabling this feature only takes effect if `plugins.security.audit.log_request_body` is also set to `false`. {: .note } @@ -127,7 +127,7 @@ Bulk requests can contain many indexing operations. By default, the security plu The security plugin can be configured to log each indexing operation as a separate event: ```yml -opensearch_security.audit.resolve_bulk_requests: true +plugins.security.audit.resolve_bulk_requests: true ``` This change can create a massive number of events in the audit logs, so we don't recommend enabling this setting if you make heavy use of the `_bulk` API. @@ -138,7 +138,7 @@ This change can create a massive number of events in the audit logs, so we don't You can exclude certain requests from being logged completely, by either configuring actions (for transport requests) and/or HTTP request paths (REST): ```yml -opensearch_security.audit.ignore_requests: ["indices:data/read/*", "SearchRequest"] +plugins.security.audit.ignore_requests: ["indices:data/read/*", "SearchRequest"] ``` @@ -147,7 +147,7 @@ opensearch_security.audit.ignore_requests: ["indices:data/read/*", "SearchReques By default, the security plugin logs events from all users, but excludes the internal OpenSearch Dashboards server user `kibanaserver`. You can exclude other users: ```yml -opensearch_security.audit.ignore_users: +plugins.security.audit.ignore_users: - kibanaserver - admin ``` @@ -155,7 +155,7 @@ opensearch_security.audit.ignore_users: If requests from all users should be logged, use `NONE`: ```yml -opensearch_security.audit.ignore_users: NONE +plugins.security.audit.ignore_users: NONE ``` @@ -164,13 +164,13 @@ opensearch_security.audit.ignore_users: NONE By default, the security plugin stores audit events in a daily rolling index named `auditlog-YYYY.MM.dd`. You can configure the name of the index in `opensearch.yml`: ```yml -opensearch_security.audit.config.index: myauditlogindex +plugins.security.audit.config.index: myauditlogindex ``` Use a date pattern in the index name to configure daily, weekly, or monthly rolling indices: ```yml -opensearch_security.audit.config.index: "'auditlog-'YYYY.MM.dd" +plugins.security.audit.config.index: "'auditlog-'YYYY.MM.dd" ``` For a reference on the date pattern format, see the [Joda DateTimeFormat documentation](http://www.joda.org/joda-time/apidocs/org/joda/time/format/DateTimeFormat.html). @@ -181,11 +181,11 @@ For a reference on the date pattern format, see the [Joda DateTimeFormat documen The Search plugin logs events asynchronously, which keeps performance impact on your cluster minimal. The plugin uses a fixed thread pool to log events. You can define the number of threads in the pool in `opensearch.yml`: ```yml -opensearch_security.audit.threadpool.size: +plugins.security.audit.threadpool.size: ``` The default setting is `10`. Setting this value to `0` disables the thread pool, which means the plugin logs events synchronously. To set the maximum queue length per thread: ```yml -opensearch_security.audit.threadpool.max_queue_len: 100000 +plugins.security.audit.threadpool.max_queue_len: 100000 ``` diff --git a/docs/security/audit-logs/storage-types.md b/docs/security/audit-logs/storage-types.md index 84fc3c32..b64adce8 100644 --- a/docs/security/audit-logs/storage-types.md +++ b/docs/security/audit-logs/storage-types.md @@ -21,7 +21,7 @@ log4j | Writes the events to a Log4j logger. You can use any Log4j [appender](ht You configure the output location in `opensearch.yml`: ``` -opensearch_security.audit.type: +plugins.security.audit.type: ``` `external_opensearch`, `webhook`, and `log4j` all have additional configuration options. Details follow. @@ -32,16 +32,16 @@ opensearch_security.audit.type: ] -opensearch_security.audit.config.index: -opensearch_security.audit.config.type: _doc +plugins.security.audit.type: external_opensearch +plugins.security.audit.config.http_endpoints: [] +plugins.security.audit.config.index: +plugins.security.audit.config.type: _doc ``` -The security plugin uses the OpenSearch REST API to send events, just like any other indexing request. For `opensearch_security.audit.config.http_endpoints`, use a comma-separated list of hosts/IP addresses and the REST port (default 9200). +The security plugin uses the OpenSearch REST API to send events, just like any other indexing request. For `plugins.security.audit.config.http_endpoints`, use a comma-separated list of hosts/IP addresses and the REST port (default 9200). ``` -opensearch_security.audit.config.http_endpoints: [192.168.178.1:9200,192.168.178.2:9200] +plugins.security.audit.config.http_endpoints: [192.168.178.1:9200,192.168.178.2:9200] ``` If you use `external_opensearch` and the remote cluster also uses the security plugin, you must supply some additional parameters for authentication. These parameters depend on which authentication type you configured for the remote cluster. @@ -51,16 +51,16 @@ If you use `external_opensearch` and the remote cluster also uses the security p Name | Data Type | Description :--- | :--- | :--- -`opensearch_security.audit.config.enable_ssl` | Boolean | If you enabled SSL/TLS on the receiving cluster, set to true. The default is false. -`opensearch_security.audit.config.verify_hostnames` | Boolean | Whether to verify the hostname of the SSL/TLS certificate of the receiving cluster. Default is true. -`opensearch_security.audit.config.pemtrustedcas_filepath` | String | The trusted root certificate of the external OpenSearch cluster, relative to the `config` directory. -`opensearch_security.audit.config.pemtrustedcas_content` | String | Instead of specifying the path (`opensearch_security.audit.config.pemtrustedcas_filepath`), you can configure the Base64-encoded certificate content directly. -`opensearch_security.audit.config.enable_ssl_client_auth` | Boolean | Whether to enable SSL/TLS client authentication. If you set this to true, the audit log module sends the node's certificate along with the request. The receiving cluster can use this certificate to verify the identity of the caller. -`opensearch_security.audit.config.pemcert_filepath` | String | The path to the TLS certificate to send to the external OpenSearch cluster, relative to the `config` directory. -`opensearch_security.audit.config.pemcert_content` | String | Instead of specifying the path (`opensearch_security.audit.config.pemcert_filepath`), you can configure the Base64-encoded certificate content directly. -`opensearch_security.audit.config.pemkey_filepath` | String | The path to the private key of the TLS certificate to send to the external OpenSearch cluster, relative to the `config` directory. -`opensearch_security.audit.config.pemkey_content` | String | Instead of specifying the path (`opensearch_security.audit.config.pemkey_filepath`), you can configure the Base64-encoded certificate content directly. -`opensearch_security.audit.config.pemkey_password` | String | The password of the private key. +`plugins.security.audit.config.enable_ssl` | Boolean | If you enabled SSL/TLS on the receiving cluster, set to true. The default is false. +`plugins.security.audit.config.verify_hostnames` | Boolean | Whether to verify the hostname of the SSL/TLS certificate of the receiving cluster. Default is true. +`plugins.security.audit.config.pemtrustedcas_filepath` | String | The trusted root certificate of the external OpenSearch cluster, relative to the `config` directory. +`plugins.security.audit.config.pemtrustedcas_content` | String | Instead of specifying the path (`plugins.security.audit.config.pemtrustedcas_filepath`), you can configure the Base64-encoded certificate content directly. +`plugins.security.audit.config.enable_ssl_client_auth` | Boolean | Whether to enable SSL/TLS client authentication. If you set this to true, the audit log module sends the node's certificate along with the request. The receiving cluster can use this certificate to verify the identity of the caller. +`plugins.security.audit.config.pemcert_filepath` | String | The path to the TLS certificate to send to the external OpenSearch cluster, relative to the `config` directory. +`plugins.security.audit.config.pemcert_content` | String | Instead of specifying the path (`plugins.security.audit.config.pemcert_filepath`), you can configure the Base64-encoded certificate content directly. +`plugins.security.audit.config.pemkey_filepath` | String | The path to the private key of the TLS certificate to send to the external OpenSearch cluster, relative to the `config` directory. +`plugins.security.audit.config.pemkey_content` | String | Instead of specifying the path (`plugins.security.audit.config.pemkey_filepath`), you can configure the Base64-encoded certificate content directly. +`plugins.security.audit.config.pemkey_password` | String | The password of the private key. ### Basic auth settings @@ -68,8 +68,8 @@ Name | Data Type | Description If you enabled HTTP basic authentication on the receiving cluster, use these settings to specify the username and password: ```yml -opensearch_security.audit.config.username: -opensearch_security.audit.config.password: +plugins.security.audit.config.username: +plugins.security.audit.config.password: ``` @@ -79,11 +79,11 @@ Use the following keys to configure the `webhook` storage type. Name | Data Type | Description :--- | :--- | :--- -`opensearch_security.audit.config.webhook.url` | String | The HTTP or HTTPS URL to send the logs to. -`opensearch_security.audit.config.webhook.ssl.verify` | Boolean | If true, the TLS certificate provided by the endpoint (if any) will be verified. If set to false, no verification is performed. You can disable this check if you use self-signed certificates. -`opensearch_security.audit.config.webhook.ssl.pemtrustedcas_filepath` | String | The path to the trusted certificate against which the webhook's TLS certificate is validated. -`opensearch_security.audit.config.webhook.ssl.pemtrustedcas_content` | String | Same as `opensearch_security.audit.config.webhook.ssl.pemtrustedcas_content`, but you can configure the base 64 encoded certificate content directly. -`opensearch_security.audit.config.webhook.format` | String | The format in which the audit log message is logged, can be one of `URL_PARAMETER_GET`, `URL_PARAMETER_POST`, `TEXT`, `JSON`, `SLACK`. See [Formats](#formats). +`plugins.security.audit.config.webhook.url` | String | The HTTP or HTTPS URL to send the logs to. +`plugins.security.audit.config.webhook.ssl.verify` | Boolean | If true, the TLS certificate provided by the endpoint (if any) will be verified. If set to false, no verification is performed. You can disable this check if you use self-signed certificates. +`plugins.security.audit.config.webhook.ssl.pemtrustedcas_filepath` | String | The path to the trusted certificate against which the webhook's TLS certificate is validated. +`plugins.security.audit.config.webhook.ssl.pemtrustedcas_content` | String | Same as `plugins.security.audit.config.webhook.ssl.pemtrustedcas_content`, but you can configure the base 64 encoded certificate content directly. +`plugins.security.audit.config.webhook.format` | String | The format in which the audit log message is logged, can be one of `URL_PARAMETER_GET`, `URL_PARAMETER_POST`, `TEXT`, `JSON`, `SLACK`. See [Formats](#formats). ### Formats @@ -102,8 +102,8 @@ Format | Description The `log4j` storage type lets you specify the name of the logger and log level. ```yml -opensearch_security.audit.config.log4j.logger_name: audit -opensearch_security.audit.config.log4j.level: INFO +plugins.security.audit.config.log4j.logger_name: audit +plugins.security.audit.config.log4j.level: INFO ``` By default, the security plugin uses the logger name `audit` and logs the events on `INFO` level. Audit events are stored in JSON format. diff --git a/docs/security/configuration/client-auth.md b/docs/security/configuration/client-auth.md index 96229b18..85ec8b0b 100644 --- a/docs/security/configuration/client-auth.md +++ b/docs/security/configuration/client-auth.md @@ -19,7 +19,7 @@ Another benefit of client certificate authentication is you can use it along wit To enable client certificate authentication, you must first set `clientauth_mode` in `opensearch.yml` to either `OPTIONAL` or `REQUIRE`: ```yml -opensearch_security.ssl.http.clientauth_mode: OPTIONAL +plugins.security.ssl.http.clientauth_mode: OPTIONAL ``` Next, enable client certificate authentication in the `client_auth_domain` section of `config.yml`. diff --git a/docs/security/configuration/configuration.md b/docs/security/configuration/configuration.md index 5cd2582d..debc6496 100755 --- a/docs/security/configuration/configuration.md +++ b/docs/security/configuration/configuration.md @@ -151,15 +151,15 @@ Due to the nature of Kerberos, you must define some settings in `opensearch.yml` In `opensearch.yml`, define the following: ```yml -opensearch_security.kerberos.krb5_filepath: '/etc/krb5.conf' -opensearch_security.kerberos.acceptor_keytab_filepath: 'eskeytab.tab' +plugins.security.kerberos.krb5_filepath: '/etc/krb5.conf' +plugins.security.kerberos.acceptor_keytab_filepath: 'eskeytab.tab' ``` -`opensearch_security.kerberos.krb5_filepath` defines the path to your Kerberos configuration file. This file contains various settings regarding your Kerberos installation, for example, the realm names, hostnames, and ports of the Kerberos key distribution center (KDC). +`plugins.security.kerberos.krb5_filepath` defines the path to your Kerberos configuration file. This file contains various settings regarding your Kerberos installation, for example, the realm names, hostnames, and ports of the Kerberos key distribution center (KDC). -`opensearch_security.kerberos.acceptor_keytab_filepath` defines the path to the keytab file, which contains the principal that the security plugin uses to issue requests against Kerberos. +`plugins.security.kerberos.acceptor_keytab_filepath` defines the path to the keytab file, which contains the principal that the security plugin uses to issue requests against Kerberos. -`opensearch_security.kerberos.acceptor_principal: 'HTTP/localhost'` defines the principal that the security plugin uses to issue requests against Kerberos. This value must be present in the keytab file. +`plugins.security.kerberos.acceptor_principal: 'HTTP/localhost'` defines the principal that the security plugin uses to issue requests against Kerberos. This value must be present in the keytab file. Due to security restrictions, the keytab file must be placed in `config` or a subdirectory, and the path in `opensearch.yml` must be relative, not absolute. {: .warning } @@ -273,7 +273,7 @@ eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJsb2dnZWRJbkFzIjoiYWRtaW4iLCJpYXQiOjE0MjI ### Configure JSON web tokens -If JSON web tokens are the only authentication method that you use, disable the user cache by setting `opensearch_security.cache.ttl_minutes: 0`. +If JSON web tokens are the only authentication method that you use, disable the user cache by setting `plugins.security.cache.ttl_minutes: 0`. {: .warning } Set up an authentication domain and choose `jwt` as the HTTP authentication type. Because the tokens already contain all required information to verify the request, `challenge` must be set to `false` and `authentication_backend` to `noop`. diff --git a/docs/security/configuration/disable.md b/docs/security/configuration/disable.md index 7278f48c..27397bd9 100755 --- a/docs/security/configuration/disable.md +++ b/docs/security/configuration/disable.md @@ -11,7 +11,7 @@ nav_order: 99 You might want to temporarily disable the security plugin to make testing or internal usage more straightforward. To disable the plugin, add the following line in `opensearch.yml`: ```yml -opensearch_security.disabled: true +plugins.security.disabled: true ``` A more permanent option is to remove the security plugin entirely. Delete the `plugins/opensearch-security` folder on all nodes, and delete the `opensearch_security` configuration entries from `opensearch.yml`. diff --git a/docs/security/configuration/generate-certificates.md b/docs/security/configuration/generate-certificates.md index cfee2c4a..c7b160d8 100755 --- a/docs/security/configuration/generate-certificates.md +++ b/docs/security/configuration/generate-certificates.md @@ -89,7 +89,7 @@ Just like the root certificate, use the `-days` option to specify an expiration Follow the steps in [Generate an admin certificate](#generate-an-admin-certificate) with new file names to generate a new certificate for each node and as many client certificates as you need. Each certificate should use its own private key. -If you generate node certificates and have `opensearch_security.ssl.transport.enforce_hostname_verification` set to `true` (default), be sure to specify a common name (CN) for the certificate that matches the hostname of the intended node. If you want to use the same node certificate on all nodes (not recommended), set hostname verification to `false`. For more information, see [Configure TLS certificates](../tls/#advanced-hostname-verification-and-dns-lookup). +If you generate node certificates and have `plugins.security.ssl.transport.enforce_hostname_verification` set to `true` (default), be sure to specify a common name (CN) for the certificate that matches the hostname of the intended node. If you want to use the same node certificate on all nodes (not recommended), set hostname verification to `false`. For more information, see [Configure TLS certificates](../tls/#advanced-hostname-verification-and-dns-lookup). ### Sample script @@ -134,9 +134,9 @@ openssl req -new -key node-key.pem -subj "/C=CA/ST=ONTARIO/L=TORONTO/O=ORG/OU=UN If you created admin and node certificates, you must specify their distinguished names (DNs) in `opensearch.yml` on all nodes: ```yml -opensearch_security.authcz.admin_dn: +plugins.security.authcz.admin_dn: - 'CN=ADMIN,OU=UNIT,O=ORG,L=TORONTO,ST=ONTARIO,C=CA' -opensearch_security.nodes_dn: +plugins.security.nodes_dn: - 'CN=node1.example.com,OU=UNIT,O=ORG,L=TORONTO,ST=ONTARIO,C=CA' - 'CN=node2.example.com,OU=UNIT,O=ORG,L=TORONTO,ST=ONTARIO,C=CA' ``` diff --git a/docs/security/configuration/ldap.md b/docs/security/configuration/ldap.md index c73a1c37..a71c22d7 100755 --- a/docs/security/configuration/ldap.md +++ b/docs/security/configuration/ldap.md @@ -154,8 +154,8 @@ Name | Description By default, the security plugin validates the TLS certificate of the LDAP servers against the root CA configured in `opensearch.yml`, either as a PEM certificate or a truststore: ``` -opensearch_security.ssl.transport.pemtrustedcas_filepath: ... -opensearch_security.ssl.http.truststore_filepath: ... +plugins.security.ssl.transport.pemtrustedcas_filepath: ... +plugins.security.ssl.http.truststore_filepath: ... ``` If your server uses a certificate signed by a different CA, import this CA into your truststore or add it to your trusted CA file on each node. diff --git a/docs/security/configuration/openid-connect.md b/docs/security/configuration/openid-connect.md index 83950966..ddb1dbcb 100755 --- a/docs/security/configuration/openid-connect.md +++ b/docs/security/configuration/openid-connect.md @@ -244,7 +244,7 @@ Name | Description Activate OpenID Connect by adding the following to `opensearch_dashboards.yml`: ``` -opensearch_security.auth.type: "openid" +plugins.security.auth.type: "openid" ``` @@ -266,29 +266,29 @@ OpenID Connect providers usually publish their configuration in JSON format unde Name | Description :--- | :--- -`opensearch_security.openid.connect_url` | The URL where the IdP publishes the OpenID metadata. Required. -`opensearch_security.openid.client_id` | The ID of the OpenID Connect client configured in your IdP. Required. -`opensearch_security.openid.client_secret` | The client secret of the OpenID Connect client configured in your IdP. Required. -`opensearch_security.openid.scope` | The [scope of the identity token](https://auth0.com/docs/scopes/current) issued by the IdP. Optional. Default is `openid profile email address phone`. -`opensearch_security.openid.header` | HTTP header name of the JWT token. Optional. Default is `Authorization`. -`opensearch_security.openid.logout_url` | The logout URL of your IdP. Optional. Only necessary if your IdP does not publish the logout URL in its metadata. -`opensearch_security.openid.base_redirect_url` | The base of the redirect URL that will be sent to your IdP. Optional. Only necessary when OpenSearch Dashboards is behind a reverse proxy, in which case it should be different than `server.host` and `server.port` in `opensearch_dashboards.yml`. +`plugins.security.openid.connect_url` | The URL where the IdP publishes the OpenID metadata. Required. +`plugins.security.openid.client_id` | The ID of the OpenID Connect client configured in your IdP. Required. +`plugins.security.openid.client_secret` | The client secret of the OpenID Connect client configured in your IdP. Required. +`plugins.security.openid.scope` | The [scope of the identity token](https://auth0.com/docs/scopes/current) issued by the IdP. Optional. Default is `openid profile email address phone`. +`plugins.security.openid.header` | HTTP header name of the JWT token. Optional. Default is `Authorization`. +`plugins.security.openid.logout_url` | The logout URL of your IdP. Optional. Only necessary if your IdP does not publish the logout URL in its metadata. +`plugins.security.openid.base_redirect_url` | The base of the redirect URL that will be sent to your IdP. Optional. Only necessary when OpenSearch Dashboards is behind a reverse proxy, in which case it should be different than `server.host` and `server.port` in `opensearch_dashboards.yml`. ### Configuration example ```yml # Enable OpenID authentication -opensearch_security.auth.type: "openid" +plugins.security.auth.type: "openid" # The IdP metadata endpoint -opensearch_security.openid.connect_url: "http://keycloak.example.com:8080/auth/realms/master/.well-known/openid-configuration" +plugins.security.openid.connect_url: "http://keycloak.example.com:8080/auth/realms/master/.well-known/openid-configuration" # The ID of the OpenID Connect client in your IdP -opensearch_security.openid.client_id: "opensearch-dashboards-sso" +plugins.security.openid.client_id: "opensearch-dashboards-sso" # The client secret of the OpenID Connect client -opensearch_security.openid.client_secret: "a59c51f5-f052-4740-a3b0-e14ba355b520" +plugins.security.openid.client_secret: "a59c51f5-f052-4740-a3b0-e14ba355b520" # Use HTTPS instead of HTTP opensearch.url: "https://.com:" diff --git a/docs/security/configuration/proxy.md b/docs/security/configuration/proxy.md index e3e6d296..2c4fdf91 100644 --- a/docs/security/configuration/proxy.md +++ b/docs/security/configuration/proxy.md @@ -202,7 +202,7 @@ opensearch.requestHeadersWhitelist: ["securitytenant","Authorization","x-forward You must also enable the authentication type in `opensearch_dashboards.yml`: ```yml -opensearch_security.auth.type: "proxy" -opensearch_security.proxycache.user_header: "x-proxy-user" -opensearch_security.proxycache.roles_header: "x-proxy-roles" +plugins.security.auth.type: "proxy" +plugins.security.proxycache.user_header: "x-proxy-user" +plugins.security.proxycache.roles_header: "x-proxy-roles" ``` diff --git a/docs/security/configuration/saml.md b/docs/security/configuration/saml.md index e81d3545..a8c64797 100755 --- a/docs/security/configuration/saml.md +++ b/docs/security/configuration/saml.md @@ -302,7 +302,7 @@ authc: Because most of the SAML-specific configuration is done in the security plugin, just activate SAML in your `opensearch_dashboards.yml` by adding the following: ``` -opensearch_security.auth.type: "saml" +plugins.security.auth.type: "saml" ``` In addition, the OpenSearch Dashboards endpoint for validating the SAML assertions must be whitelisted: diff --git a/docs/security/configuration/security-admin.md b/docs/security/configuration/security-admin.md index d692ac0c..01caaa6a 100755 --- a/docs/security/configuration/security-admin.md +++ b/docs/security/configuration/security-admin.md @@ -20,7 +20,7 @@ After the `.opensearch_security` index is initialized, you can use OpenSearch Da You can configure all certificates that should have admin privileges in `opensearch.yml` by specifying respective distinguished names (DNs). If you use the demo certificates, for example, you can use the `kirk` certificate: ```yml -opensearch_security.authcz.admin_dn: +plugins.security.authcz.admin_dn: - CN=kirk,OU=client,O=client,L=test,C=DE ``` diff --git a/docs/security/configuration/system-indices.md b/docs/security/configuration/system-indices.md index 95611552..d65190f7 100644 --- a/docs/security/configuration/system-indices.md +++ b/docs/security/configuration/system-indices.md @@ -13,8 +13,8 @@ By default, OpenSearch has a protected system index, `.opensearch_security`, whi You can add additional system indices in in `opensearch.yml`. In addition to automatically creating `.opensearch_security`, the demo configuration adds several indices for the various OpenSearch plugins that integrate with the security plugin: ```yml -opendistro_security.system_indices.enabled: true -opendistro_security.system_indices.indices: [".opendistro-alerting-config", ".opendistro-alerting-alert*", ".opendistro-anomaly-results*", ".opendistro-anomaly-detector*", ".opendistro-anomaly-checkpoints", ".opendistro-anomaly-detection-state", ".opendistro-reports-*", ".opendistro-notifications-*", ".opendistro-notebooks", ".opendistro-asynchronous-search-response*"] +plugins.security.system_indices.enabled: true +plugins.security.system_indices.indices: [".opendistro-alerting-config", ".opendistro-alerting-alert*", ".opendistro-anomaly-results*", ".opendistro-anomaly-detector*", ".opendistro-anomaly-checkpoints", ".opendistro-anomaly-detection-state", ".opendistro-reports-*", ".opendistro-notifications-*", ".opendistro-notebooks", ".opendistro-asynchronous-search-response*"] ``` To access these indices, you must authenticate with an [admin certificate](../tls/#configure-admin-certificates): @@ -23,4 +23,4 @@ To access these indices, you must authenticate with an [admin certificate](../tl curl -k --cert ./kirk.pem --key ./kirk-key.pem -XGET 'https://localhost:9200/.opensearch_security/_search' ``` -The alternative is to remove indices from the `opensearch_security.system_indices.indices` list on each node and restart OpenSearch. +The alternative is to remove indices from the `plugins.security.system_indices.indices` list on each node and restart OpenSearch. diff --git a/docs/security/configuration/tls.md b/docs/security/configuration/tls.md index 36aca4a9..56205e2f 100755 --- a/docs/security/configuration/tls.md +++ b/docs/security/configuration/tls.md @@ -23,20 +23,20 @@ The following tables contain the settings you can use to configure the location Name | Description :--- | :--- -`opensearch_security.ssl.transport.pemkey_filepath` | Path to the certificate's key file (PKCS \#8), which must be under the `config` directory, specified using a relative path. Required. -`opensearch_security.ssl.transport.pemkey_password` | Key password. Omit this setting if the key has no password. Optional. -`opensearch_security.ssl.transport.pemcert_filepath` | Path to the X.509 node certificate chain (PEM format), which must be under the `config` directory, specified using a relative path. Required. -`opensearch_security.ssl.transport.pemtrustedcas_filepath` | Path to the root CAs (PEM format), which must be under the `config` directory, specified using a relative path. Required. +`plugins.security.ssl.transport.pemkey_filepath` | Path to the certificate's key file (PKCS \#8), which must be under the `config` directory, specified using a relative path. Required. +`plugins.security.ssl.transport.pemkey_password` | Key password. Omit this setting if the key has no password. Optional. +`plugins.security.ssl.transport.pemcert_filepath` | Path to the X.509 node certificate chain (PEM format), which must be under the `config` directory, specified using a relative path. Required. +`plugins.security.ssl.transport.pemtrustedcas_filepath` | Path to the root CAs (PEM format), which must be under the `config` directory, specified using a relative path. Required. ### REST layer TLS Name | Description :--- | :--- -`opensearch_security.ssl.http.pemkey_filepath` | Path to the certificate's key file (PKCS \#8), which must be under the `config` directory, specified using a relative path. Required. -`opensearch_security.ssl.http.pemkey_password` | Key password. Omit this setting if the key has no password. Optional. -`opensearch_security.ssl.http.pemcert_filepath` | Path to the X.509 node certificate chain (PEM format), which must be under the `config` directory, specified using a relative path. Required. -`opensearch_security.ssl.http.pemtrustedcas_filepath` | Path to the root CAs (PEM format), which must be under the `config` directory, specified using a relative path. Required. +`plugins.security.ssl.http.pemkey_filepath` | Path to the certificate's key file (PKCS \#8), which must be under the `config` directory, specified using a relative path. Required. +`plugins.security.ssl.http.pemkey_password` | Key password. Omit this setting if the key has no password. Optional. +`plugins.security.ssl.http.pemcert_filepath` | Path to the X.509 node certificate chain (PEM format), which must be under the `config` directory, specified using a relative path. Required. +`plugins.security.ssl.http.pemtrustedcas_filepath` | Path to the root CAs (PEM format), which must be under the `config` directory, specified using a relative path. Required. ## Keystore and truststore files @@ -50,29 +50,29 @@ The following settings configure the location and password of your keystore and Name | Description :--- | :--- -`opensearch_security.ssl.transport.keystore_type` | The type of the keystore file, JKS or PKCS12/PFX. Optional. Default is JKS. -`opensearch_security.ssl.transport.keystore_filepath` | Path to the keystore file, which must be under the `config` directory, specified using a relative path. Required. -`opensearch_security.ssl.transport.keystore_alias: my_alias` | Alias name. Optional. Default is the first alias. -`opensearch_security.ssl.transport.keystore_password` | Keystore password. Default is `changeit`. -`opensearch_security.ssl.transport.truststore_type` | The type of the truststore file, JKS or PKCS12/PFX. Default is JKS. -`opensearch_security.ssl.transport.truststore_filepath` | Path to the truststore file, which must be under the `config` directory, specified using a relative path. Required. -`opensearch_security.ssl.transport.truststore_alias` | Alias name. Optional. Default is all certificates. -`opensearch_security.ssl.transport.truststore_password` | Truststore password. Default is `changeit`. +`plugins.security.ssl.transport.keystore_type` | The type of the keystore file, JKS or PKCS12/PFX. Optional. Default is JKS. +`plugins.security.ssl.transport.keystore_filepath` | Path to the keystore file, which must be under the `config` directory, specified using a relative path. Required. +`plugins.security.ssl.transport.keystore_alias: my_alias` | Alias name. Optional. Default is the first alias. +`plugins.security.ssl.transport.keystore_password` | Keystore password. Default is `changeit`. +`plugins.security.ssl.transport.truststore_type` | The type of the truststore file, JKS or PKCS12/PFX. Default is JKS. +`plugins.security.ssl.transport.truststore_filepath` | Path to the truststore file, which must be under the `config` directory, specified using a relative path. Required. +`plugins.security.ssl.transport.truststore_alias` | Alias name. Optional. Default is all certificates. +`plugins.security.ssl.transport.truststore_password` | Truststore password. Default is `changeit`. ### REST layer TLS Name | Description :--- | :--- -`opensearch_security.ssl.http.enabled` | Whether to enable TLS on the REST layer. If enabled, only HTTPS is allowed. Optional. Default is false. -`opensearch_security.ssl.http.keystore_type` | The type of the keystore file, JKS or PKCS12/PFX. Optional. Default is JKS. -`opensearch_security.ssl.http.keystore_filepath` | Path to the keystore file, which must be under the `config` directory, specified using a relative path. Required. -`opensearch_security.ssl.http.keystore_alias` | Alias name. Optional. Default is the first alias. -`opensearch_security.ssl.http.keystore_password` | Keystore password. Default is `changeit`. -`opensearch_security.ssl.http.truststore_type` | The type of the truststore file, JKS or PKCS12/PFX. Default is JKS. -`opensearch_security.ssl.http.truststore_filepath` | Path to the truststore file, which must be under the `config` directory, specified using a relative path. Required. -`opensearch_security.ssl.http.truststore_alias` | Alias name. Optional. Default is all certificates. -`opensearch_security.ssl.http.truststore_password` | Truststore password. Default is `changeit`. +`plugins.security.ssl.http.enabled` | Whether to enable TLS on the REST layer. If enabled, only HTTPS is allowed. Optional. Default is false. +`plugins.security.ssl.http.keystore_type` | The type of the keystore file, JKS or PKCS12/PFX. Optional. Default is JKS. +`plugins.security.ssl.http.keystore_filepath` | Path to the keystore file, which must be under the `config` directory, specified using a relative path. Required. +`plugins.security.ssl.http.keystore_alias` | Alias name. Optional. Default is the first alias. +`plugins.security.ssl.http.keystore_password` | Keystore password. Default is `changeit`. +`plugins.security.ssl.http.truststore_type` | The type of the truststore file, JKS or PKCS12/PFX. Default is JKS. +`plugins.security.ssl.http.truststore_filepath` | Path to the truststore file, which must be under the `config` directory, specified using a relative path. Required. +`plugins.security.ssl.http.truststore_alias` | Alias name. Optional. Default is all certificates. +`plugins.security.ssl.http.truststore_password` | Truststore password. Default is `changeit`. ## Configure node certificates @@ -80,7 +80,7 @@ Name | Description The security plugin needs to identify inter-cluster requests (i.e. requests between the nodes). The simplest way of configuring node certificates is to list the Distinguished Names (DNs) of these certificates in `opensearch.yml`. All DNs must be included in `opensearch.yml` on all nodes. The security plugin supports wildcards and regular expressions: ```yml -opensearch_security.nodes_dn: +plugins.security.nodes_dn: - 'CN=node.other.com,OU=SSL,O=Test,L=Test,C=DE' - 'CN=*.example.com,OU=SSL,O=Test,L=Test,C=DE' - 'CN=elk-devcluster*' @@ -95,7 +95,7 @@ If your node certificates have an Object ID (OID) identifier in the SAN section, Admin certificates are regular client certificates that have elevated rights to perform administrative tasks. You need an admin certificate to change the the security plugin configuration using `plugins/opensearch-security/tools/securityadmin.sh` or the REST API. Admin certificates are configured in `opensearch.yml` by stating their DN(s): ```yml -opensearch_security.authcz.admin_dn: +plugins.security.authcz.admin_dn: - CN=admin,OU=SSL,O=Test,L=Test,C=DE ``` @@ -112,8 +112,8 @@ If OpenSSL is enabled, but for one reason or another the installation does not w Name | Description :--- | :--- -`opensearch_security.ssl.transport.enable_openssl_if_available` | Enable OpenSSL on the transport layer if available. Optional. Default is true. -`opensearch_security.ssl.http.enable_openssl_if_available` | Enable OpenSSL on the REST layer if available. Optional. Default is true. +`plugins.security.ssl.transport.enable_openssl_if_available` | Enable OpenSSL on the transport layer if available. Optional. Default is true. +`plugins.security.ssl.http.enable_openssl_if_available` | Enable OpenSSL on the REST layer if available. Optional. Default is true. {% comment %} @@ -144,8 +144,8 @@ In addition, when `resolve_hostnames` is enabled, the security plugin resolves t Name | Description :--- | :--- -`opensearch_security.ssl.transport.enforce_hostname_verification` | Whether to verify hostnames on the transport layer. Optional. Default is true. -`opensearch_security.ssl.transport.resolve_hostname` | Whether to resolve hostnames against DNS on the transport layer. Optional. Default is true. Only works if hostname verification is also enabled. +`plugins.security.ssl.transport.enforce_hostname_verification` | Whether to verify hostnames on the transport layer. Optional. Default is true. +`plugins.security.ssl.transport.resolve_hostname` | Whether to resolve hostnames against DNS on the transport layer. Optional. Default is true. Only works if hostname verification is also enabled. ## (Advanced) Client authentication @@ -168,7 +168,7 @@ You can configure the client authentication mode by using the following setting: Name | Description :--- | :--- -opensearch_security.ssl.http.clientauth_mode | The TLS client authentication mode to use. Can be one of `NONE`, `OPTIONAL` (default) or `REQUIRE`. Optional. +plugins.security.ssl.http.clientauth_mode | The TLS client authentication mode to use. Can be one of `NONE`, `OPTIONAL` (default) or `REQUIRE`. Optional. ## (Advanced) Enabled ciphers and protocols @@ -179,18 +179,18 @@ If this setting is not enabled, the ciphers and TLS versions are negotiated betw Name | Data Type | Description :--- | :--- | :--- -`opensearch_security.ssl.http.enabled_ciphers` | Array | Enabled TLS cipher suites for the REST layer. Only Java format is supported. -`opensearch_security.ssl.http.enabled_protocols` | Array | Enabled TLS protocols for the REST layer. Only Java format is supported. -`opensearch_security.ssl.transport.enabled_ciphers` | Array | Enabled TLS cipher suites for the transport layer. Only Java format is supported. -`opensearch_security.ssl.transport.enabled_protocols` | Array | Enabled TLS protocols for the transport layer. Only Java format is supported. +`plugins.security.ssl.http.enabled_ciphers` | Array | Enabled TLS cipher suites for the REST layer. Only Java format is supported. +`plugins.security.ssl.http.enabled_protocols` | Array | Enabled TLS protocols for the REST layer. Only Java format is supported. +`plugins.security.ssl.transport.enabled_ciphers` | Array | Enabled TLS cipher suites for the transport layer. Only Java format is supported. +`plugins.security.ssl.transport.enabled_protocols` | Array | Enabled TLS protocols for the transport layer. Only Java format is supported. ### Example settings ```yml -opensearch_security.ssl.http.enabled_ciphers: +plugins.security.ssl.http.enabled_ciphers: - "TLS_DHE_RSA_WITH_AES_256_CBC_SHA" - "TLS_DHE_DSS_WITH_AES_128_CBC_SHA256" -opensearch_security.ssl.http.enabled_protocols: +plugins.security.ssl.http.enabled_protocols: - "TLSv1.1" - "TLSv1.2" ``` @@ -198,7 +198,7 @@ opensearch_security.ssl.http.enabled_protocols: Because it is insecure, the security plugin disables `TLSv1` by default. If you need to use `TLSv1` and accept the risks, you can still enable it: ```yml -opensearch_security.ssl.http.enabled_protocols: +plugins.security.ssl.http.enabled_protocols: - "TLSv1" - "TLSv1.1" - "TLSv1.2" diff --git a/docs/troubleshoot/openid-connect.md b/docs/troubleshoot/openid-connect.md index 96f175e5..4a920835 100644 --- a/docs/troubleshoot/openid-connect.md +++ b/docs/troubleshoot/openid-connect.md @@ -24,8 +24,8 @@ This page includes troubleshooting steps for using OpenID Connect with the secur To help troubleshoot OpenID Connect, set the log level to `debug` on OpenSearch. Add the following lines in `config/log4j2.properties` and restart the node: ``` -logger.opensearch_security.name = com.amazon.dlic.auth.http.jwt -logger.opensearch_security.level = trace +logger.plugins.security.name = com.amazon.dlic.auth.http.jwt +logger.plugins.security.level = trace ``` This setting prints a lot of helpful information to your log file. If this information isn't sufficient, you can also set the log level to `trace`. @@ -36,7 +36,7 @@ This setting prints a lot of helpful information to your log file. If this infor This error indicates that the security plugin can't reach the metadata endpoint of your IdP. In `opensearch_dashboards.yml`, check the following setting: ``` -opensearch_security.openid.connect_url: "http://keycloak.example.com:8080/auth/realms/master/.well-known/openid-configuration" +plugins.security.openid.connect_url: "http://keycloak.example.com:8080/auth/realms/master/.well-known/openid-configuration" ``` If this error occurs on OpenSearch, check the following setting in `config.yml`: @@ -60,9 +60,9 @@ This indicates that one or more of the OpenSearch Dashboards configuration setti Check `opensearch_dashboards.yml` and make sure you have set the following minimal configuration: ```yml -opensearch_security.openid.connect_url: "..." -opensearch_security.openid.client_id: "..." -opensearch_security.openid.client_secret: "..." +plugins.security.openid.connect_url: "..." +plugins.security.openid.client_id: "..." +plugins.security.openid.client_secret: "..." ``` @@ -81,7 +81,7 @@ Please delete all cached browser data, or try again in a private browser window. To trade the access token for an identity token, most IdPs require you to provide a client secret. Check if the client secret in `opensearch_dashboards.yml` matches the client secret of your IdP configuration: ``` -opensearch_security.openid.client_secret: "..." +plugins.security.openid.client_secret: "..." ``` diff --git a/docs/troubleshoot/tls.md b/docs/troubleshoot/tls.md index 3db3b0d7..7768fd02 100644 --- a/docs/troubleshoot/tls.md +++ b/docs/troubleshoot/tls.md @@ -49,7 +49,7 @@ The security plugin uses the [string representation of Distinguished Names (RFC1 If parts of your DN contain special characters (e.g. a comma), make sure you escape it in your configuration: ```yml -opensearch_security.nodes_dn: +plugins.security.nodes_dn: - 'CN=node-0.example.com,OU=SSL,O=My\, Test,L=Test,C=DE' ``` @@ -58,14 +58,14 @@ You can have whitespace within a field, but not between fields. #### Bad configuration ```yml -opensearch_security.nodes_dn: +plugins.security.nodes_dn: - 'CN=node-0.example.com, OU=SSL,O=My\, Test, L=Test, C=DE' ``` #### Good configuration ```yml -opensearch_security.nodes_dn: +plugins.security.nodes_dn: - 'CN=node-0.example.com,OU=SSL,O=My\, Test,L=Test,C=DE' ``` @@ -197,7 +197,7 @@ ExtendedKeyUsages [ The security plugin disables TLS version 1.0 by default; it is outdated, insecure, and vulnerable. If you need to use `TLSv1` and accept the risks, you can enable it in `opensearch.yml`: ```yml -opensearch_security.ssl.http.enabled_protocols: +plugins.security.ssl.http.enabled_protocols: - "TLSv1" - "TLSv1.1" - "TLSv1.2"