From a710633932d319fbd2bccb7c76ce6837a1838361 Mon Sep 17 00:00:00 2001 From: AntonEliatra Date: Fri, 10 May 2024 14:38:26 +0100 Subject: [PATCH 01/13] adding a get started with security page #6668 Signed-off-by: AntonEliatra --- _getting-started/security.md | 145 +++++++++++++++++++++++++++++++++++ 1 file changed, 145 insertions(+) create mode 100644 _getting-started/security.md diff --git a/_getting-started/security.md b/_getting-started/security.md new file mode 100644 index 0000000000..89689b02d2 --- /dev/null +++ b/_getting-started/security.md @@ -0,0 +1,145 @@ +--- +layout: default +title: Getting started with OpenSearch security +nav_order: 60 +--- + +# Getting started with OpenSearch security +The simplest way to get started with security in OpenSearch is using the demo configuration. Naturally, this is configuration should never be used in production, as it uses demo certificates and default passwords. All of this configuration should be updated with your custom details prior to moving to production. + +# Demo configuration +## OpenSearch +OpenSearch comes bundled with a number of useful scripts, one of which is `install_demo_configuration.sh` (or `install_demo_configuration.bat` for windows). +This script is normally located in `plugins/opensearch-security/tools` and can perform the following actions: +- create demo certificates for TLS encryption on transport and REST layer. +- configure demo users, roles, role mappings. +- configure security plugin to use internal database for authentication and authorization. +- update `opensearch.yml` file with basic configuration needed to get the cluster started. + +Prior to running the `install_demo_configuration.sh` script you must create environment variable named `OPENSEARCH_INITIAL_ADMIN_PASSWORD` with strong password, as this will be used as password for admin user to authenticate with OpenSearch. Once this is completed, you can execute `install_demo_configuration.sh` and follow the terminal prompt to enter necessary details. + +Once this is complete, you can start OpenSearch and test out the configuration by running the below command: +`curl -k -XGET -uadmin: https://:9200` +You should see similar output to the following: +``` +{ + "name" : "smoketestnode", + "cluster_name" : "opensearch", + "cluster_uuid" : "0a5DYAk0Rbi14wqT3TqMiQ", + "version" : { + "distribution" : "opensearch", + "number" : "2.13.0", + "build_type" : "tar", + "build_hash" : "7ec678d1b7c87d6e779fdef94e33623e1f1e2647", + "build_date" : "2024-03-26T00:04:51.025238748Z", + "build_snapshot" : false, + "lucene_version" : "9.10.0", + "minimum_wire_compatibility_version" : "7.10.0", + "minimum_index_compatibility_version" : "7.0.0" + }, + "tagline" : "The OpenSearch Project: https://opensearch.org/" +} +``` +## OpenSearch Dashboards +OpenSearch Dashboards comes built in with basic configuration already available in `config/opensearch_dashboards.yml` +``` +opensearch.hosts: [https://localhost:9200] +opensearch.ssl.verificationMode: none +opensearch.username: kibanaserver +opensearch.password: kibanaserver +opensearch.requestHeadersWhitelist: [authorization, securitytenant] + +opensearch_security.multitenancy.enabled: true +opensearch_security.multitenancy.tenants.preferred: [Private, Global] +opensearch_security.readonly_mode.roles: [kibana_read_only] +# Use this setting if you are running opensearch-dashboards without https +opensearch_security.cookie.secure: false +``` +You can start the binary or service, depending on which method was used to install OpenSearch and OpenSearch Dashboards. +Once OpenSearch Dashboards is started, you should see following two lines in the logs: +``` +[info][listening] Server running at http://localhost:5601 +[info][server][OpenSearchDashboards][http] http server running at http://localhost:5601 +``` + +You can now access the OpenSearch Dashboards using http://localhost:5601 in your browser. Using username `admin` and password that was configured in `OPENSEARCH_INITIAL_ADMIN_PASSWORD` environment variable. + +# Adding users +There are three ways to add users, roles, etc. + - updating appropriate yaml file (`internal_users.yml` file for adding/updating/removing users) + - using API + - using OpenSearch Dashboards UI + +Security configuration files are usually located in `config/opensearch-security` directory +{: .note} + +You can add OpenSearch Dashboards user by updating `internal_users.yml` file as follows: + +``` +test-user: + hash: "$2y$12$CkxFoTAJKsZaWv/m8VoZ6ePG3DBeBTAvoo4xA2P21VCS9w2RYumsG" + backend_roles: + - "test-backend-role" + - "kibanauser" + description: "test user user" +``` +The `hash` string is generated using `hash.sh` script located in `plugins/opensearch-security/tools/` directory. In this case password of `secretpassword` was used. +Note the use of build in backend role `kibanauser` which is going to give user permissions needed to navigate OpenSearch Dashboards. + +# Creating role + +The structure of the role in `roles.yml` file is as follows: +``` +: + cluster_permissions: + - + index_permissions: + - index_patterns: + - + allowed_actions: + - +``` + +Using this structure you can configure a new role to give access to specific indices, see the following configuration: + +``` +human_resources: + index_permissions: + - index_patterns: + - "humanresources" + allowed_actions: + - "READ" +``` +Note that the cluster permissions are not listed in this example, as these are provided by built in role `kibana_user` which is already mapped using `kibanauser` backend role. + +# Mapping users to roles +When user logs in to OpenSearch, they need to be mapped to appropriate role in order to obtain the correct permissions. This mapping is done via `roles_mapping.yml` file, with the following structure: +``` +: + users: + - + - ... + backend_roles: + - +``` + +In order to map the newly created user `test-user` to the role `human_resources`, you can use the following configuration in `roles_mapping.yml` file: +``` +human_resources: + backend_roles: + - test-backend-role +``` + +If you examine the already existing roles_mappings.yml file, you can see the backend role of `kibanauser` is already being mapped to `kibana_user` role, see the following configuration: +``` +kibana_user: + reserved: false + backend_roles: + - "kibanauser" + description: "Maps kibanauser to kibana_user" +``` + +# Uploading the configuration to security index +The final step in configuring users, roles and any other security configuration is uploading it to OpenSearch security index. Simply updating the files, without uploading, will not have any impact on the configuration that is running in OpenSearch. +To upload configuration, following command can be used with admin certificate that was generated with demo install: +`plugins/opensearch-security/tools/securityadmin.sh -cd "config/opensearch-security" -icl -key "../kirk-key.pem" -cert "../kirk.pem" -cacert "../root-ca.pem" -nhnv` From 90b03a2ac3afbc4ceb4e1fdb326db3f197232806 Mon Sep 17 00:00:00 2001 From: AntonEliatra Date: Mon, 13 May 2024 10:19:51 +0100 Subject: [PATCH 02/13] fixing vale errors #6668 Signed-off-by: AntonEliatra --- _getting-started/security.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/_getting-started/security.md b/_getting-started/security.md index 89689b02d2..8f75d132dc 100644 --- a/_getting-started/security.md +++ b/_getting-started/security.md @@ -7,18 +7,17 @@ nav_order: 60 # Getting started with OpenSearch security The simplest way to get started with security in OpenSearch is using the demo configuration. Naturally, this is configuration should never be used in production, as it uses demo certificates and default passwords. All of this configuration should be updated with your custom details prior to moving to production. -# Demo configuration -## OpenSearch +# OpenSearch Demo configuration OpenSearch comes bundled with a number of useful scripts, one of which is `install_demo_configuration.sh` (or `install_demo_configuration.bat` for windows). This script is normally located in `plugins/opensearch-security/tools` and can perform the following actions: - create demo certificates for TLS encryption on transport and REST layer. - configure demo users, roles, role mappings. -- configure security plugin to use internal database for authentication and authorization. +- configure Security plugin to use internal database for authentication and authorization. - update `opensearch.yml` file with basic configuration needed to get the cluster started. Prior to running the `install_demo_configuration.sh` script you must create environment variable named `OPENSEARCH_INITIAL_ADMIN_PASSWORD` with strong password, as this will be used as password for admin user to authenticate with OpenSearch. Once this is completed, you can execute `install_demo_configuration.sh` and follow the terminal prompt to enter necessary details. -Once this is complete, you can start OpenSearch and test out the configuration by running the below command: +Once this is complete, you can start OpenSearch and test out the configuration by running the following command: `curl -k -XGET -uadmin: https://:9200` You should see similar output to the following: ``` @@ -40,8 +39,8 @@ You should see similar output to the following: "tagline" : "The OpenSearch Project: https://opensearch.org/" } ``` -## OpenSearch Dashboards -OpenSearch Dashboards comes built in with basic configuration already available in `config/opensearch_dashboards.yml` +# OpenSearch Dashboards +In order to quickly get started with OpenSearch Dashboards, you can add the below configuration to `opensearch_dashboards.yml`: ``` opensearch.hosts: [https://localhost:9200] opensearch.ssl.verificationMode: none @@ -65,8 +64,8 @@ Once OpenSearch Dashboards is started, you should see following two lines in the You can now access the OpenSearch Dashboards using http://localhost:5601 in your browser. Using username `admin` and password that was configured in `OPENSEARCH_INITIAL_ADMIN_PASSWORD` environment variable. # Adding users -There are three ways to add users, roles, etc. - - updating appropriate yaml file (`internal_users.yml` file for adding/updating/removing users) +There are three ways to add users, roles, and other security configuration. + - updating appropriate configuration files (`internal_users.yml` file for adding/updating/removing users) - using API - using OpenSearch Dashboards UI @@ -100,7 +99,7 @@ The structure of the role in `roles.yml` file is as follows: - ``` -Using this structure you can configure a new role to give access to specific indices, see the following configuration: +Using this structure you can configure a new role to give access to specific indexes, see the following configuration: ``` human_resources: @@ -140,6 +139,6 @@ kibana_user: ``` # Uploading the configuration to security index -The final step in configuring users, roles and any other security configuration is uploading it to OpenSearch security index. Simply updating the files, without uploading, will not have any impact on the configuration that is running in OpenSearch. +The final step in configuring users, roles and any other security configuration is uploading it to OpenSearch security index. Only updating the files, without uploading, will not have any impact on the configuration that is running in OpenSearch. To upload configuration, following command can be used with admin certificate that was generated with demo install: `plugins/opensearch-security/tools/securityadmin.sh -cd "config/opensearch-security" -icl -key "../kirk-key.pem" -cert "../kirk.pem" -cacert "../root-ca.pem" -nhnv` From c448911b574a16100e93c7348d6e40e77f5053d3 Mon Sep 17 00:00:00 2001 From: AntonEliatra Date: Mon, 13 May 2024 10:24:31 +0100 Subject: [PATCH 03/13] fixing vale errors #6668 Signed-off-by: AntonEliatra --- _getting-started/security.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_getting-started/security.md b/_getting-started/security.md index 8f75d132dc..cfc53ea902 100644 --- a/_getting-started/security.md +++ b/_getting-started/security.md @@ -7,7 +7,7 @@ nav_order: 60 # Getting started with OpenSearch security The simplest way to get started with security in OpenSearch is using the demo configuration. Naturally, this is configuration should never be used in production, as it uses demo certificates and default passwords. All of this configuration should be updated with your custom details prior to moving to production. -# OpenSearch Demo configuration +# OpenSearch demo configuration OpenSearch comes bundled with a number of useful scripts, one of which is `install_demo_configuration.sh` (or `install_demo_configuration.bat` for windows). This script is normally located in `plugins/opensearch-security/tools` and can perform the following actions: - create demo certificates for TLS encryption on transport and REST layer. @@ -40,7 +40,7 @@ You should see similar output to the following: } ``` # OpenSearch Dashboards -In order to quickly get started with OpenSearch Dashboards, you can add the below configuration to `opensearch_dashboards.yml`: +In order to quickly get started with OpenSearch Dashboards, you can add the following configuration to `opensearch_dashboards.yml`: ``` opensearch.hosts: [https://localhost:9200] opensearch.ssl.verificationMode: none From 73f82ceab83215bdec6bf9d1ef18e287c7ba6f02 Mon Sep 17 00:00:00 2001 From: AntonEliatra Date: Mon, 13 May 2024 18:27:06 +0100 Subject: [PATCH 04/13] adding role configurations for users without kibanauser mapping #2359 Signed-off-by: AntonEliatra --- _getting-started/security.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/_getting-started/security.md b/_getting-started/security.md index cfc53ea902..95cd4d076f 100644 --- a/_getting-started/security.md +++ b/_getting-started/security.md @@ -111,6 +111,7 @@ human_resources: ``` Note that the cluster permissions are not listed in this example, as these are provided by built in role `kibana_user` which is already mapped using `kibanauser` backend role. + # Mapping users to roles When user logs in to OpenSearch, they need to be mapped to appropriate role in order to obtain the correct permissions. This mapping is done via `roles_mapping.yml` file, with the following structure: ``` @@ -138,6 +139,19 @@ kibana_user: description: "Maps kibanauser to kibana_user" ``` +If you do not want to map the user to built in role `kibana_user` and only want to give the user full access to a subset of indexes, you can use the following role configuration and delete the role mapping for `kibana_user`: + +``` +: + cluster_permissions: + - "indices:data/write/bulk" + index_permissions: + - index_patterns: + - "humanresource" + allowed_actions: + - "indices_all" +``` + # Uploading the configuration to security index The final step in configuring users, roles and any other security configuration is uploading it to OpenSearch security index. Only updating the files, without uploading, will not have any impact on the configuration that is running in OpenSearch. To upload configuration, following command can be used with admin certificate that was generated with demo install: From 75e609d8140f974a210b7a5c267e06843761563e Mon Sep 17 00:00:00 2001 From: AntonEliatra Date: Thu, 16 May 2024 10:34:40 +0100 Subject: [PATCH 05/13] updating the page layout for getting started with security #6668 Signed-off-by: AntonEliatra --- _getting-started/security.md | 46 ++++++++++++++++-------------------- 1 file changed, 21 insertions(+), 25 deletions(-) diff --git a/_getting-started/security.md b/_getting-started/security.md index 95cd4d076f..5432578220 100644 --- a/_getting-started/security.md +++ b/_getting-started/security.md @@ -5,19 +5,22 @@ nav_order: 60 --- # Getting started with OpenSearch security -The simplest way to get started with security in OpenSearch is using the demo configuration. Naturally, this is configuration should never be used in production, as it uses demo certificates and default passwords. All of this configuration should be updated with your custom details prior to moving to production. + +The most straight forward way to get started with security in OpenSearch is using the demo configuration. Some parts of this configuration should never be used in production, for example demo certificates and default passwords. These parts of demo configuration should be updated with your custom details prior to moving to production. # OpenSearch demo configuration -OpenSearch comes bundled with a number of useful scripts, one of which is `install_demo_configuration.sh` (or `install_demo_configuration.bat` for windows). -This script is normally located in `plugins/opensearch-security/tools` and can perform the following actions: -- create demo certificates for TLS encryption on transport and REST layer. -- configure demo users, roles, role mappings. -- configure Security plugin to use internal database for authentication and authorization. -- update `opensearch.yml` file with basic configuration needed to get the cluster started. -Prior to running the `install_demo_configuration.sh` script you must create environment variable named `OPENSEARCH_INITIAL_ADMIN_PASSWORD` with strong password, as this will be used as password for admin user to authenticate with OpenSearch. Once this is completed, you can execute `install_demo_configuration.sh` and follow the terminal prompt to enter necessary details. +OpenSearch comes bundled with a number of useful scripts, one of which is `install_demo_configuration.sh` (or `install_demo_configuration.bat` for Windows). +This script is usually located in `plugins/opensearch-security/tools` and performs the following actions: + +- creates demo certificates for TLS encryption on transport and REST layer. +- configures demo users, roles, role mappings. +- configures Security plugin to use internal database for authentication and authorization. +- updates `opensearch.yml` file with basic configuration needed to get the cluster started. + +Prior to running the `install_demo_configuration.sh` script you must create environment variable named `OPENSEARCH_INITIAL_ADMIN_PASSWORD` set to strong password, as this will be used as password for admin user to authenticate with OpenSearch. Once this is set, you can execute `install_demo_configuration.sh` and follow the terminal prompt to enter necessary details. -Once this is complete, you can start OpenSearch and test out the configuration by running the following command: +After the script is executed, you can start OpenSearch and test out the configuration by running the following command: `curl -k -XGET -uadmin: https://:9200` You should see similar output to the following: ``` @@ -39,7 +42,9 @@ You should see similar output to the following: "tagline" : "The OpenSearch Project: https://opensearch.org/" } ``` + # OpenSearch Dashboards + In order to quickly get started with OpenSearch Dashboards, you can add the following configuration to `opensearch_dashboards.yml`: ``` opensearch.hosts: [https://localhost:9200] @@ -64,7 +69,9 @@ Once OpenSearch Dashboards is started, you should see following two lines in the You can now access the OpenSearch Dashboards using http://localhost:5601 in your browser. Using username `admin` and password that was configured in `OPENSEARCH_INITIAL_ADMIN_PASSWORD` environment variable. # Adding users -There are three ways to add users, roles, and other security configuration. + +There are three ways to add users, roles, and other security configuration: + - updating appropriate configuration files (`internal_users.yml` file for adding/updating/removing users) - using API - using OpenSearch Dashboards UI @@ -113,6 +120,7 @@ Note that the cluster permissions are not listed in this example, as these are p # Mapping users to roles + When user logs in to OpenSearch, they need to be mapped to appropriate role in order to obtain the correct permissions. This mapping is done via `roles_mapping.yml` file, with the following structure: ``` : @@ -139,20 +147,8 @@ kibana_user: description: "Maps kibanauser to kibana_user" ``` -If you do not want to map the user to built in role `kibana_user` and only want to give the user full access to a subset of indexes, you can use the following role configuration and delete the role mapping for `kibana_user`: - -``` -: - cluster_permissions: - - "indices:data/write/bulk" - index_permissions: - - index_patterns: - - "humanresource" - allowed_actions: - - "indices_all" -``` - # Uploading the configuration to security index -The final step in configuring users, roles and any other security configuration is uploading it to OpenSearch security index. Only updating the files, without uploading, will not have any impact on the configuration that is running in OpenSearch. -To upload configuration, following command can be used with admin certificate that was generated with demo install: + +The final step in configuring users, roles and any other security configuration is uploading it to OpenSearch security index. Only updating the files, without uploading them, will not have any impact on the configuration that is running in OpenSearch. +To upload configuration, following command can be used with admin certificate that was generated during `install_demo_configuration.sh` execution: `plugins/opensearch-security/tools/securityadmin.sh -cd "config/opensearch-security" -icl -key "../kirk-key.pem" -cert "../kirk.pem" -cacert "../root-ca.pem" -nhnv` From 6f31214c8acf6cebf29d3c10947a8a2b348d88b2 Mon Sep 17 00:00:00 2001 From: AntonEliatra Date: Mon, 27 May 2024 09:21:44 +0100 Subject: [PATCH 06/13] Apply suggestions from code review Co-authored-by: Darshit Chanpura Co-authored-by: Stephen Crawford <65832608+scrawfor99@users.noreply.github.com> Signed-off-by: AntonEliatra --- _getting-started/security.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/_getting-started/security.md b/_getting-started/security.md index 5432578220..4aeccf26bb 100644 --- a/_getting-started/security.md +++ b/_getting-started/security.md @@ -6,12 +6,12 @@ nav_order: 60 # Getting started with OpenSearch security -The most straight forward way to get started with security in OpenSearch is using the demo configuration. Some parts of this configuration should never be used in production, for example demo certificates and default passwords. These parts of demo configuration should be updated with your custom details prior to moving to production. +The demo configuration is the most straightforward way to get started with security in OpenSearch. Certain aspects of this configuration, such as demo certificates and default passwords, should never be used in production. These parts of the demo configuration should be updated with your custom information before proceeding to production. # OpenSearch demo configuration -OpenSearch comes bundled with a number of useful scripts, one of which is `install_demo_configuration.sh` (or `install_demo_configuration.bat` for Windows). -This script is usually located in `plugins/opensearch-security/tools` and performs the following actions: +OpenSearch comes bundled with a number of useful scripts, one of which is the `install_demo_configuration.sh` (or `install_demo_configuration.bat` for Windows). +This script is located in `plugins/opensearch-security/tools` and performs the following actions: - creates demo certificates for TLS encryption on transport and REST layer. - configures demo users, roles, role mappings. @@ -21,7 +21,7 @@ This script is usually located in `plugins/opensearch-security/tools` and perfor Prior to running the `install_demo_configuration.sh` script you must create environment variable named `OPENSEARCH_INITIAL_ADMIN_PASSWORD` set to strong password, as this will be used as password for admin user to authenticate with OpenSearch. Once this is set, you can execute `install_demo_configuration.sh` and follow the terminal prompt to enter necessary details. After the script is executed, you can start OpenSearch and test out the configuration by running the following command: -`curl -k -XGET -uadmin: https://:9200` +`curl -k -XGET -u admin: https://:9200` You should see similar output to the following: ``` { @@ -70,16 +70,16 @@ You can now access the OpenSearch Dashboards using http://localhost:5601 in your # Adding users -There are three ways to add users, roles, and other security configuration: +There are three ways to add users, roles, and other security related configurations: - updating appropriate configuration files (`internal_users.yml` file for adding/updating/removing users) - using API - using OpenSearch Dashboards UI -Security configuration files are usually located in `config/opensearch-security` directory +Security configuration files are located in `config/opensearch-security` directory. {: .note} -You can add OpenSearch Dashboards user by updating `internal_users.yml` file as follows: +You can add a OpenSearch Dashboards user by updating the `internal_users.yml` file as follows: ``` test-user: @@ -89,12 +89,12 @@ test-user: - "kibanauser" description: "test user user" ``` -The `hash` string is generated using `hash.sh` script located in `plugins/opensearch-security/tools/` directory. In this case password of `secretpassword` was used. -Note the use of build in backend role `kibanauser` which is going to give user permissions needed to navigate OpenSearch Dashboards. +The `hash` string is generated using `hash.sh` script located in `plugins/opensearch-security/tools/` directory. In this case the hash of the string `secretpassword` was used. +Note the use of built-in backend role `kibanauser` which is going to give user permissions needed to navigate OpenSearch Dashboards. # Creating role -The structure of the role in `roles.yml` file is as follows: +The structure of a role in `roles.yml` file is as follows: ``` : cluster_permissions: @@ -106,7 +106,7 @@ The structure of the role in `roles.yml` file is as follows: - ``` -Using this structure you can configure a new role to give access to specific indexes, see the following configuration: +Using this structure you can configure a new role to give access to specific indexes. For example, see the following configuration: ``` human_resources: @@ -116,12 +116,12 @@ human_resources: allowed_actions: - "READ" ``` -Note that the cluster permissions are not listed in this example, as these are provided by built in role `kibana_user` which is already mapped using `kibanauser` backend role. +Note that the cluster permissions are not listed in this example, as these are provided by built-in role `kibana_user` which is already mapped using `kibanauser` backend role. # Mapping users to roles -When user logs in to OpenSearch, they need to be mapped to appropriate role in order to obtain the correct permissions. This mapping is done via `roles_mapping.yml` file, with the following structure: +When a user logs in to OpenSearch, they need to be mapped to appropriate role in order to obtain the correct permissions. This mapping is done via `roles_mapping.yml` file, with the following structure: ``` : users: @@ -138,7 +138,7 @@ human_resources: - test-backend-role ``` -If you examine the already existing roles_mappings.yml file, you can see the backend role of `kibanauser` is already being mapped to `kibana_user` role, see the following configuration: +If you examine the already existing `roles_mappings.yml` file, you can see the backend role `kibanauser` has been mapped to `kibana_user` role. You can search for the following configuration in the file: ``` kibana_user: reserved: false @@ -149,6 +149,6 @@ kibana_user: # Uploading the configuration to security index -The final step in configuring users, roles and any other security configuration is uploading it to OpenSearch security index. Only updating the files, without uploading them, will not have any impact on the configuration that is running in OpenSearch. +The final step in configuring users, roles and any other security configuration is uploading it to OpenSearch security index. Only updating the files, without uploading them, will not change any configuration inside the already running OpenSearch cluster. To upload configuration, following command can be used with admin certificate that was generated during `install_demo_configuration.sh` execution: -`plugins/opensearch-security/tools/securityadmin.sh -cd "config/opensearch-security" -icl -key "../kirk-key.pem" -cert "../kirk.pem" -cacert "../root-ca.pem" -nhnv` +`./plugins/opensearch-security/tools/securityadmin.sh -cd "config/opensearch-security" -icl -key "../kirk-key.pem" -cert "../kirk.pem" -cacert "../root-ca.pem" -nhnv` From 9b2aad7b49d10e7206ba9cf962085a26242f62c2 Mon Sep 17 00:00:00 2001 From: AntonEliatra Date: Mon, 27 May 2024 09:37:18 +0100 Subject: [PATCH 07/13] adding additional details to getting started with security Signed-off-by: AntonEliatra --- _getting-started/security.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/_getting-started/security.md b/_getting-started/security.md index 4aeccf26bb..f67a848be9 100644 --- a/_getting-started/security.md +++ b/_getting-started/security.md @@ -18,7 +18,7 @@ This script is located in `plugins/opensearch-security/tools` and performs the f - configures Security plugin to use internal database for authentication and authorization. - updates `opensearch.yml` file with basic configuration needed to get the cluster started. -Prior to running the `install_demo_configuration.sh` script you must create environment variable named `OPENSEARCH_INITIAL_ADMIN_PASSWORD` set to strong password, as this will be used as password for admin user to authenticate with OpenSearch. Once this is set, you can execute `install_demo_configuration.sh` and follow the terminal prompt to enter necessary details. +Prior to running the `install_demo_configuration.sh` script you must create environment variable named `OPENSEARCH_INITIAL_ADMIN_PASSWORD` set to strong password, as this will be used as password for admin user to authenticate with OpenSearch. You can use online tool [tryzxcvbn](https://lowe.github.io/tryzxcvbn/) to test the strength of any password. Once this is set, you can execute `install_demo_configuration.sh` and follow the terminal prompt to enter necessary details. After the script is executed, you can start OpenSearch and test out the configuration by running the following command: `curl -k -XGET -u admin: https://:9200` @@ -60,6 +60,10 @@ opensearch_security.readonly_mode.roles: [kibana_read_only] opensearch_security.cookie.secure: false ``` You can start the binary or service, depending on which method was used to install OpenSearch and OpenSearch Dashboards. + +When using binary, you need to supply `--no-base-path` to `yarn start` command to set a url without a base-path. If this is not set, a random 3-letter base-path will be added. +{: .note} + Once OpenSearch Dashboards is started, you should see following two lines in the logs: ``` [info][listening] Server running at http://localhost:5601 From a305c579033cdead5cb0c12a88819ccd500b95cb Mon Sep 17 00:00:00 2001 From: AntonEliatra Date: Mon, 27 May 2024 09:41:05 +0100 Subject: [PATCH 08/13] adding additional details to getting started with security Signed-off-by: AntonEliatra --- _getting-started/security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_getting-started/security.md b/_getting-started/security.md index f67a848be9..31c016a3e7 100644 --- a/_getting-started/security.md +++ b/_getting-started/security.md @@ -18,7 +18,7 @@ This script is located in `plugins/opensearch-security/tools` and performs the f - configures Security plugin to use internal database for authentication and authorization. - updates `opensearch.yml` file with basic configuration needed to get the cluster started. -Prior to running the `install_demo_configuration.sh` script you must create environment variable named `OPENSEARCH_INITIAL_ADMIN_PASSWORD` set to strong password, as this will be used as password for admin user to authenticate with OpenSearch. You can use online tool [tryzxcvbn](https://lowe.github.io/tryzxcvbn/) to test the strength of any password. Once this is set, you can execute `install_demo_configuration.sh` and follow the terminal prompt to enter necessary details. +Prior to running the `install_demo_configuration.sh` script you must create environment variable named `OPENSEARCH_INITIAL_ADMIN_PASSWORD` set to strong password, as this will be used as password for admin user to authenticate with OpenSearch. You can use online tool [zxcvbn](https://lowe.github.io/tryzxcvbn/) to test the strength of any password. Once this is set, you can execute `install_demo_configuration.sh` and follow the terminal prompt to enter necessary details. After the script is executed, you can start OpenSearch and test out the configuration by running the following command: `curl -k -XGET -u admin: https://:9200` From 66c624957e3929a613e90cb46c56668a3836547e Mon Sep 17 00:00:00 2001 From: AntonEliatra Date: Tue, 28 May 2024 21:55:03 +0100 Subject: [PATCH 09/13] Update security.md Signed-off-by: AntonEliatra --- _getting-started/security.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_getting-started/security.md b/_getting-started/security.md index 31c016a3e7..3ab700f6d2 100644 --- a/_getting-started/security.md +++ b/_getting-started/security.md @@ -18,7 +18,7 @@ This script is located in `plugins/opensearch-security/tools` and performs the f - configures Security plugin to use internal database for authentication and authorization. - updates `opensearch.yml` file with basic configuration needed to get the cluster started. -Prior to running the `install_demo_configuration.sh` script you must create environment variable named `OPENSEARCH_INITIAL_ADMIN_PASSWORD` set to strong password, as this will be used as password for admin user to authenticate with OpenSearch. You can use online tool [zxcvbn](https://lowe.github.io/tryzxcvbn/) to test the strength of any password. Once this is set, you can execute `install_demo_configuration.sh` and follow the terminal prompt to enter necessary details. +Prior to running the `install_demo_configuration.sh` script you must create environment variable named `OPENSEARCH_INITIAL_ADMIN_PASSWORD` set to strong password, as this will be used as password for admin user to authenticate with OpenSearch. You can use online tool [Zxcvbn](https://lowe.github.io/tryzxcvbn/) to test the strength of any password. Once this is set, you can execute `install_demo_configuration.sh` and follow the terminal prompt to enter necessary details. After the script is executed, you can start OpenSearch and test out the configuration by running the following command: `curl -k -XGET -u admin: https://:9200` @@ -61,7 +61,7 @@ opensearch_security.cookie.secure: false ``` You can start the binary or service, depending on which method was used to install OpenSearch and OpenSearch Dashboards. -When using binary, you need to supply `--no-base-path` to `yarn start` command to set a url without a base-path. If this is not set, a random 3-letter base-path will be added. +When using binary, you need to supply `--no-base-path` to `yarn start` command to set a URL without a base-path. If this is not set, a random 3-letter base-path will be added. {: .note} Once OpenSearch Dashboards is started, you should see following two lines in the logs: From 2ed0849287612dda22d3cc23fdc940b23a5d76fe Mon Sep 17 00:00:00 2001 From: AntonEliatra Date: Tue, 28 May 2024 22:15:26 +0100 Subject: [PATCH 10/13] Update security.md Signed-off-by: AntonEliatra --- _getting-started/security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_getting-started/security.md b/_getting-started/security.md index 3ab700f6d2..f7f279689f 100644 --- a/_getting-started/security.md +++ b/_getting-started/security.md @@ -18,7 +18,7 @@ This script is located in `plugins/opensearch-security/tools` and performs the f - configures Security plugin to use internal database for authentication and authorization. - updates `opensearch.yml` file with basic configuration needed to get the cluster started. -Prior to running the `install_demo_configuration.sh` script you must create environment variable named `OPENSEARCH_INITIAL_ADMIN_PASSWORD` set to strong password, as this will be used as password for admin user to authenticate with OpenSearch. You can use online tool [Zxcvbn](https://lowe.github.io/tryzxcvbn/) to test the strength of any password. Once this is set, you can execute `install_demo_configuration.sh` and follow the terminal prompt to enter necessary details. +Prior to running the `install_demo_configuration.sh` script you must create environment variable named `OPENSEARCH_INITIAL_ADMIN_PASSWORD` set to strong password, as this will be used as password for admin user to authenticate with OpenSearch. You can use online tool [_Zxcvbn_](https://lowe.github.io/tryzxcvbn/) to test the strength of any password. Once this is set, you can execute `install_demo_configuration.sh` and follow the terminal prompt to enter necessary details. After the script is executed, you can start OpenSearch and test out the configuration by running the following command: `curl -k -XGET -u admin: https://:9200` From 61b90d18a0b3b1a33f4c9d5fd1205fabf2d4fec8 Mon Sep 17 00:00:00 2001 From: AntonEliatra Date: Fri, 31 May 2024 12:18:25 +0100 Subject: [PATCH 11/13] adding link for existing docs for demo config Signed-off-by: AntonEliatra --- _getting-started/security.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/_getting-started/security.md b/_getting-started/security.md index f7f279689f..9989bd1de7 100644 --- a/_getting-started/security.md +++ b/_getting-started/security.md @@ -18,6 +18,9 @@ This script is located in `plugins/opensearch-security/tools` and performs the f - configures Security plugin to use internal database for authentication and authorization. - updates `opensearch.yml` file with basic configuration needed to get the cluster started. +You can find complete details regarding demo configuration and how to get up and running quickly at [Setting up a demo configuration]({{site.url}}{{site.baseurl}}/security/configuration/demo-configuration/) +{: .note} + Prior to running the `install_demo_configuration.sh` script you must create environment variable named `OPENSEARCH_INITIAL_ADMIN_PASSWORD` set to strong password, as this will be used as password for admin user to authenticate with OpenSearch. You can use online tool [_Zxcvbn_](https://lowe.github.io/tryzxcvbn/) to test the strength of any password. Once this is set, you can execute `install_demo_configuration.sh` and follow the terminal prompt to enter necessary details. After the script is executed, you can start OpenSearch and test out the configuration by running the following command: From 4b7cd2f377df2b10b03f49b5e1043efd605ae973 Mon Sep 17 00:00:00 2001 From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Date: Tue, 4 Jun 2024 11:46:55 -0500 Subject: [PATCH 12/13] Doc review Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --- _getting-started/security.md | 85 ++++++++++++++++++++++++------------ 1 file changed, 58 insertions(+), 27 deletions(-) diff --git a/_getting-started/security.md b/_getting-started/security.md index 9989bd1de7..ed4feca683 100644 --- a/_getting-started/security.md +++ b/_getting-started/security.md @@ -6,26 +6,34 @@ nav_order: 60 # Getting started with OpenSearch security -The demo configuration is the most straightforward way to get started with security in OpenSearch. Certain aspects of this configuration, such as demo certificates and default passwords, should never be used in production. These parts of the demo configuration should be updated with your custom information before proceeding to production. +The demo configuration is the most straightforward way to get started with security in OpenSearch. OpenSearch comes bundled with a number of useful scripts, including `install_demo_configuration.sh` (or `install_demo_configuration.bat` for Windows). -# OpenSearch demo configuration - -OpenSearch comes bundled with a number of useful scripts, one of which is the `install_demo_configuration.sh` (or `install_demo_configuration.bat` for Windows). This script is located in `plugins/opensearch-security/tools` and performs the following actions: -- creates demo certificates for TLS encryption on transport and REST layer. -- configures demo users, roles, role mappings. -- configures Security plugin to use internal database for authentication and authorization. -- updates `opensearch.yml` file with basic configuration needed to get the cluster started. +- Creates demo certificates for TLS encryption on both the transport and REST layers. +- Configures demo users, roles, role mappings. +- Configures the Security plugin to use internal database for authentication and authorization. +- Updates the `opensearch.yml` file with basic configuration needed to get the cluster started. You can find complete details regarding demo configuration and how to get up and running quickly at [Setting up a demo configuration]({{site.url}}{{site.baseurl}}/security/configuration/demo-configuration/) {: .note} -Prior to running the `install_demo_configuration.sh` script you must create environment variable named `OPENSEARCH_INITIAL_ADMIN_PASSWORD` set to strong password, as this will be used as password for admin user to authenticate with OpenSearch. You can use online tool [_Zxcvbn_](https://lowe.github.io/tryzxcvbn/) to test the strength of any password. Once this is set, you can execute `install_demo_configuration.sh` and follow the terminal prompt to enter necessary details. +Certain aspects of this configuration, such as demo certificates and default passwords, should never be used in production. These parts of the demo configuration should be updated with your custom information before proceeding to production. +{: .warning} + +## Setting up the demo configuration + +Prior to running the `install_demo_configuration.sh` script you must create environment variable named `OPENSEARCH_INITIAL_ADMIN_PASSWORD` set to a strong password. This will be used as the password for the admin user to authenticate with OpenSearch. Use the online tool [_Zxcvbn_](https://lowe.github.io/tryzxcvbn/) to test the strength of any password. After this is set, you can execute `install_demo_configuration.sh` and follow the terminal prompt to enter necessary details. After the script is executed, you can start OpenSearch and test out the configuration by running the following command: -`curl -k -XGET -u admin: https://:9200` + +``` +curl -k -XGET -u admin: https://:9200 +``` +{% include copy.html %} + You should see similar output to the following: + ``` { "name" : "smoketestnode", @@ -46,9 +54,10 @@ You should see similar output to the following: } ``` -# OpenSearch Dashboards +## Setting up OpenSearch Dashboards In order to quickly get started with OpenSearch Dashboards, you can add the following configuration to `opensearch_dashboards.yml`: + ``` opensearch.hosts: [https://localhost:9200] opensearch.ssl.verificationMode: none @@ -62,31 +71,35 @@ opensearch_security.readonly_mode.roles: [kibana_read_only] # Use this setting if you are running opensearch-dashboards without https opensearch_security.cookie.secure: false ``` +{% include copy.html %} + You can start the binary or service, depending on which method was used to install OpenSearch and OpenSearch Dashboards. When using binary, you need to supply `--no-base-path` to `yarn start` command to set a URL without a base-path. If this is not set, a random 3-letter base-path will be added. {: .note} -Once OpenSearch Dashboards is started, you should see following two lines in the logs: +After OpenSearch Dashboards is started, you should see following two lines in the logs: + ``` [info][listening] Server running at http://localhost:5601 [info][server][OpenSearchDashboards][http] http server running at http://localhost:5601 ``` +{% include copy.html %} -You can now access the OpenSearch Dashboards using http://localhost:5601 in your browser. Using username `admin` and password that was configured in `OPENSEARCH_INITIAL_ADMIN_PASSWORD` environment variable. +You can now access the OpenSearch Dashboards using http://localhost:5601 in your browser. Use the username `admin` and the password that was configured in `OPENSEARCH_INITIAL_ADMIN_PASSWORD` environment variable. # Adding users There are three ways to add users, roles, and other security related configurations: - - updating appropriate configuration files (`internal_users.yml` file for adding/updating/removing users) - - using API - - using OpenSearch Dashboards UI + - Updating appropriate configuration files (`internal_users.yml` file for adding/updating/removing users) + - Using the API + - Using the OpenSearch Dashboards UI Security configuration files are located in `config/opensearch-security` directory. {: .note} -You can add a OpenSearch Dashboards user by updating the `internal_users.yml` file as follows: +You can add an OpenSearch Dashboards user by updating the `internal_users.yml` file with the following settings: ``` test-user: @@ -96,12 +109,16 @@ test-user: - "kibanauser" description: "test user user" ``` +{% include copy.html %} + The `hash` string is generated using `hash.sh` script located in `plugins/opensearch-security/tools/` directory. In this case the hash of the string `secretpassword` was used. + Note the use of built-in backend role `kibanauser` which is going to give user permissions needed to navigate OpenSearch Dashboards. -# Creating role +## Creating roles + +Roles inside of `roles.yml` use the following structure: -The structure of a role in `roles.yml` file is as follows: ``` : cluster_permissions: @@ -112,8 +129,9 @@ The structure of a role in `roles.yml` file is as follows: allowed_actions: - ``` +{% include copy.html %} -Using this structure you can configure a new role to give access to specific indexes. For example, see the following configuration: +Using this structure you can configure a new role to give access to specific indexes, such as the following example configuration: ``` human_resources: @@ -123,12 +141,15 @@ human_resources: allowed_actions: - "READ" ``` -Note that the cluster permissions are not listed in this example, as these are provided by built-in role `kibana_user` which is already mapped using `kibanauser` backend role. +{% include copy.html %} +Note that the cluster permissions are not listed in this example, as these are provided by built-in role `kibana_user` which is already mapped using the `kibanauser` backend role. -# Mapping users to roles -When a user logs in to OpenSearch, they need to be mapped to appropriate role in order to obtain the correct permissions. This mapping is done via `roles_mapping.yml` file, with the following structure: +## Mapping users to roles + +When a user logs into OpenSearch, they need to be mapped to the appropriate role in order to obtain the correct permissions. This mapping is done using the `roles_mapping.yml` file with the following structure: + ``` : users: @@ -137,15 +158,19 @@ When a user logs in to OpenSearch, they need to be mapped to appropriate role in backend_roles: - ``` +{% include copy.html %} In order to map the newly created user `test-user` to the role `human_resources`, you can use the following configuration in `roles_mapping.yml` file: + ``` human_resources: backend_roles: - test-backend-role ``` +{% include copy.html %} + +For an additional example, the `roles_mappings.yml` file includes the following backend role `kibanauser` has been mapped to `kibana_user` role: -If you examine the already existing `roles_mappings.yml` file, you can see the backend role `kibanauser` has been mapped to `kibana_user` role. You can search for the following configuration in the file: ``` kibana_user: reserved: false @@ -153,9 +178,15 @@ kibana_user: - "kibanauser" description: "Maps kibanauser to kibana_user" ``` +{% include copy.html %} -# Uploading the configuration to security index +## Uploading the configuration to security index The final step in configuring users, roles and any other security configuration is uploading it to OpenSearch security index. Only updating the files, without uploading them, will not change any configuration inside the already running OpenSearch cluster. -To upload configuration, following command can be used with admin certificate that was generated during `install_demo_configuration.sh` execution: -`./plugins/opensearch-security/tools/securityadmin.sh -cd "config/opensearch-security" -icl -key "../kirk-key.pem" -cert "../kirk.pem" -cacert "../root-ca.pem" -nhnv` + +To upload configuration, the following command can be used with admin certificate that was generated during `install_demo_configuration.sh` execution: + +``` +./plugins/opensearch-security/tools/securityadmin.sh -cd "config/opensearch-security" -icl -key "../kirk-key.pem" -cert "../kirk.pem" -cacert "../root-ca.pem" -nhnv +``` +{% include copy.html %} From 835a8d52d3e03d2979bbd90e983daea6780c06b6 Mon Sep 17 00:00:00 2001 From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Date: Tue, 4 Jun 2024 15:48:50 -0500 Subject: [PATCH 13/13] Apply suggestions from code review Co-authored-by: Nathan Bower Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --- _getting-started/security.md | 52 ++++++++++++++++++------------------ 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/_getting-started/security.md b/_getting-started/security.md index ed4feca683..1bed87b50d 100644 --- a/_getting-started/security.md +++ b/_getting-started/security.md @@ -6,33 +6,33 @@ nav_order: 60 # Getting started with OpenSearch security -The demo configuration is the most straightforward way to get started with security in OpenSearch. OpenSearch comes bundled with a number of useful scripts, including `install_demo_configuration.sh` (or `install_demo_configuration.bat` for Windows). +The demo configuration is the most straightforward way to get started with OpenSearch security. OpenSearch comes bundled with a number of useful scripts, including `install_demo_configuration.sh` (or `install_demo_configuration.bat` for Windows). This script is located in `plugins/opensearch-security/tools` and performs the following actions: - Creates demo certificates for TLS encryption on both the transport and REST layers. -- Configures demo users, roles, role mappings. -- Configures the Security plugin to use internal database for authentication and authorization. -- Updates the `opensearch.yml` file with basic configuration needed to get the cluster started. +- Configures demo users, roles, and role mappings. +- Configures the Security plugin to use an internal database for authentication and authorization. +- Updates the `opensearch.yml` file with the basic configuration needed to start the cluster. -You can find complete details regarding demo configuration and how to get up and running quickly at [Setting up a demo configuration]({{site.url}}{{site.baseurl}}/security/configuration/demo-configuration/) +You can find more information about the demo configuration and how to quickly get started at [Setting up a demo configuration]({{site.url}}{{site.baseurl}}/security/configuration/demo-configuration/). {: .note} -Certain aspects of this configuration, such as demo certificates and default passwords, should never be used in production. These parts of the demo configuration should be updated with your custom information before proceeding to production. +Certain aspects of this configuration, such as demo certificates and default passwords, should never be used in production. These parts of the demo configuration should be replaced with your custom information before proceeding to production. {: .warning} ## Setting up the demo configuration -Prior to running the `install_demo_configuration.sh` script you must create environment variable named `OPENSEARCH_INITIAL_ADMIN_PASSWORD` set to a strong password. This will be used as the password for the admin user to authenticate with OpenSearch. Use the online tool [_Zxcvbn_](https://lowe.github.io/tryzxcvbn/) to test the strength of any password. After this is set, you can execute `install_demo_configuration.sh` and follow the terminal prompt to enter necessary details. +Prior to running the `install_demo_configuration.sh` script, you must create an environment variable named `OPENSEARCH_INITIAL_ADMIN_PASSWORD` with a strong password. This will be used as the password for the admin user to authenticate with OpenSearch. Use the online tool [_Zxcvbn_](https://lowe.github.io/tryzxcvbn/) to test the strength of any password. After this, you can execute `install_demo_configuration.sh` and follow the terminal prompt to enter necessary details. -After the script is executed, you can start OpenSearch and test out the configuration by running the following command: +After the script is executed, you can start OpenSearch and test the configuration by running the following command: ``` curl -k -XGET -u admin: https://:9200 ``` {% include copy.html %} -You should see similar output to the following: +You should see output similar to the following: ``` { @@ -75,10 +75,10 @@ opensearch_security.cookie.secure: false You can start the binary or service, depending on which method was used to install OpenSearch and OpenSearch Dashboards. -When using binary, you need to supply `--no-base-path` to `yarn start` command to set a URL without a base-path. If this is not set, a random 3-letter base-path will be added. +When using binary, you need to supply `--no-base-path` to `yarn start` command to set a URL without a base path. If this is not set, a random three-letter base path will be added. {: .note} -After OpenSearch Dashboards is started, you should see following two lines in the logs: +After starting OpenSearch Dashboards, you should see the following two log lines: ``` [info][listening] Server running at http://localhost:5601 @@ -86,17 +86,17 @@ After OpenSearch Dashboards is started, you should see following two lines in th ``` {% include copy.html %} -You can now access the OpenSearch Dashboards using http://localhost:5601 in your browser. Use the username `admin` and the password that was configured in `OPENSEARCH_INITIAL_ADMIN_PASSWORD` environment variable. +You can now access OpenSearch Dashboards using http://localhost:5601 in your browser. Use the username `admin` and the password that was configured in the `OPENSEARCH_INITIAL_ADMIN_PASSWORD` environment variable. # Adding users -There are three ways to add users, roles, and other security related configurations: +There are three ways to add users, roles, and other security-related configurations: - - Updating appropriate configuration files (`internal_users.yml` file for adding/updating/removing users) + - Updating appropriate configuration files (`internal_users.yml` for adding/updating/removing users) - Using the API - Using the OpenSearch Dashboards UI -Security configuration files are located in `config/opensearch-security` directory. +Security configuration files are located in the `config/opensearch-security` directory. {: .note} You can add an OpenSearch Dashboards user by updating the `internal_users.yml` file with the following settings: @@ -111,13 +111,13 @@ test-user: ``` {% include copy.html %} -The `hash` string is generated using `hash.sh` script located in `plugins/opensearch-security/tools/` directory. In this case the hash of the string `secretpassword` was used. +The `hash` string is generated using the `hash.sh` script located in the `plugins/opensearch-security/tools/` directory. In this case, the hash of the string `secretpassword` was used. -Note the use of built-in backend role `kibanauser` which is going to give user permissions needed to navigate OpenSearch Dashboards. +Note the use of the built-in backend role `kibanauser`, which provides the user permissions needed to navigate OpenSearch Dashboards. ## Creating roles -Roles inside of `roles.yml` use the following structure: +Roles contained in `roles.yml` use the following structure: ``` : @@ -131,7 +131,7 @@ Roles inside of `roles.yml` use the following structure: ``` {% include copy.html %} -Using this structure you can configure a new role to give access to specific indexes, such as the following example configuration: +Using this structure, you can configure a new role to provide access to specific indexes, such as the role configured in the following example: ``` human_resources: @@ -143,12 +143,12 @@ human_resources: ``` {% include copy.html %} -Note that the cluster permissions are not listed in this example, as these are provided by built-in role `kibana_user` which is already mapped using the `kibanauser` backend role. +Note that the cluster permissions are not listed in this example because these are provided by the built-in role `kibana_user`, which is already mapped using the `kibanauser` backend role. ## Mapping users to roles -When a user logs into OpenSearch, they need to be mapped to the appropriate role in order to obtain the correct permissions. This mapping is done using the `roles_mapping.yml` file with the following structure: +When a user logs in to OpenSearch, they need to be mapped to the appropriate role in order to obtain the correct permissions. This mapping is performed using the `roles_mapping.yml` file with the following structure: ``` : @@ -160,7 +160,7 @@ When a user logs into OpenSearch, they need to be mapped to the appropriate role ``` {% include copy.html %} -In order to map the newly created user `test-user` to the role `human_resources`, you can use the following configuration in `roles_mapping.yml` file: +In order to map the newly created user `test-user` to the role `human_resources`, you can use the following configuration in the `roles_mapping.yml` file: ``` human_resources: @@ -169,7 +169,7 @@ human_resources: ``` {% include copy.html %} -For an additional example, the `roles_mappings.yml` file includes the following backend role `kibanauser` has been mapped to `kibana_user` role: +As an additional example, the `roles_mappings.yml` file includes the backend role `kibanauser` that has been mapped to the `kibana_user` role: ``` kibana_user: @@ -180,11 +180,11 @@ kibana_user: ``` {% include copy.html %} -## Uploading the configuration to security index +## Uploading the configuration to a security index -The final step in configuring users, roles and any other security configuration is uploading it to OpenSearch security index. Only updating the files, without uploading them, will not change any configuration inside the already running OpenSearch cluster. +The final step in configuring a user, role, or any other security configuration is uploading it to a OpenSearch security index. Only updating the files, without uploading them, will not change the configuration of an already running OpenSearch cluster. -To upload configuration, the following command can be used with admin certificate that was generated during `install_demo_configuration.sh` execution: +To upload a configuration, the following command can be used with the admin certificate that was generated during `install_demo_configuration.sh` execution: ``` ./plugins/opensearch-security/tools/securityadmin.sh -cd "config/opensearch-security" -icl -key "../kirk-key.pem" -cert "../kirk.pem" -cacert "../root-ca.pem" -nhnv