This version of the OpenSearch documentation is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.

Modifying the YAML files

The Security installation provides a number of YAML configuration files that are used to store the necessary settings that define the way the Security plugin manages users, roles, and activity within the cluster. These settings range from configurations for authentication backends to lists of allowed endpoints and HTTP requests.

Before running securityadmin.sh to load the settings into the .opendistro_security index, perform an initial configuration of the YAML files. The files can be found in the config/opensearch-security directory. It’s also good practice to back up these files so that you can reuse them for other clusters.

The approach we recommend for using the YAML files is to first configure reserved and hidden resources, such as the admin and kibanaserver users. Thereafter you can create other users, roles, mappings, action groups, and tenants using OpenSearch Dashboards or the REST API.

internal_users.yml

This file contains any initial users that you want to add to the Security plugin’s internal user database.

The file format requires a hashed password. To generate one, run plugins/opensearch-security/tools/hash.sh -p <new-password>. If you decide to keep any of the demo users, change their passwords and re-run securityadmin.sh to apply the new passwords.

  1. ---
  2. # This is the internal user database
  3. # The hash value is a bcrypt hash and can be generated with plugin/tools/hash.sh
  5. _meta:
  6.   type: "internalusers"
  7.   config_version: 2
  9. # Define your internal users here
  10. new-user:
  11.   hash: "$2y$12$88IFVl6IfIwCFh5aQYfOmuXVL9j2hz/GusQb35o.4sdTDAEMTOD.K"
  12.   reserved: false
  13.   hidden: false
  14.   opendistro_security_roles:
  15.   - "specify-some-security-role-here"
  16.   backend_roles:
  17.   - "specify-some-backend-role-here"
  18.   attributes:
  19.     attribute1: "value1"
  20.   static: false
  22. ## Demo users
  24. admin:
  25.   hash: "$2a$12$VcCDgh2NDk07JGN0rjGbM.Ad41qVR/YFJcgHp0UGns5JDymv..TOG"
  26.   reserved: true
  27.   backend_roles:
  28.   - "admin"
  29.   description: "Demo admin user"
  31. kibanaserver:
  32.   hash: "$2a$12$4AcgAt3xwOWadA5s5blL6ev39OXDNhmOesEoo33eZtrq2N0YrU3H."
  33.   reserved: true
  34.   description: "Demo user for the OpenSearch Dashboards server"
  36. kibanaro:
  37.   hash: "$2a$12$JJSXNfTowz7Uu5ttXfeYpeYE0arACvcwlPBStB1F.MI7f0U9Z4DGC"
  38.   reserved: false
  39.   backend_roles:
  40.   - "kibanauser"
  41.   - "readall"
  42.   attributes:
  43.     attribute1: "value1"
  44.     attribute2: "value2"
  45.     attribute3: "value3"
  46.   description: "Demo read-only user for OpenSearch dashboards"
  48. logstash:
  49.   hash: "$2a$12$u1ShR4l4uBS3Uv59Pa2y5.1uQuZBrZtmNfqB3iM/.jL0XoV9sghS2"
  50.   reserved: false
  51.   backend_roles:
  52.   - "logstash"
  53.   description: "Demo logstash user"
  55. readall:
  56.   hash: "$2a$12$ae4ycwzwvLtZxwZ82RmiEunBbIPiAmGZduBAjKN0TXdwQFtCwARz2"
  57.   reserved: false
  58.   backend_roles:
  59.   - "readall"
  60.   description: "Demo readall user"
  62. snapshotrestore:
  63.   hash: "$2y$12$DpwmetHKwgYnorbgdvORCenv4NAK8cPUg8AI6pxLCuWf/ALc0.v7W"
  64.   reserved: false
  65.   backend_roles:
  66.   - "snapshotrestore"
  67.   description: "Demo snapshotrestore user"

opensearch.yml

In addition to many OpenSearch settings, this file contains paths to TLS certificates and their attributes, such as distinguished names and trusted certificate authorities.

  1. plugins.security.ssl.transport.pemcert_filepath: esnode.pem
  2. plugins.security.ssl.transport.pemkey_filepath: esnode-key.pem
  3. plugins.security.ssl.transport.pemtrustedcas_filepath: root-ca.pem
  4. plugins.security.ssl.transport.enforce_hostname_verification: false
  5. plugins.security.ssl.http.enabled: true
  6. plugins.security.ssl.http.pemcert_filepath: esnode.pem
  7. plugins.security.ssl.http.pemkey_filepath: esnode-key.pem
  8. plugins.security.ssl.http.pemtrustedcas_filepath: root-ca.pem
  9. plugins.security.allow_unsafe_democertificates: true
  10. plugins.security.allow_default_init_securityindex: true
  11. plugins.security.authcz.admin_dn:
  12.   - CN=kirk,OU=client,O=client,L=test, C=de
  14. plugins.security.audit.type: internal_opensearch
  15. plugins.security.enable_snapshot_restore_privilege: true
  16. plugins.security.check_snapshot_restore_write_privileges: true
  17. plugins.security.cache.ttl_minutes: 60
  18. plugins.security.restapi.roles_enabled: ["all_access", "security_rest_api_access"]
  19. plugins.security.system_indices.enabled: true
  20. 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*"]
  21. node.max_local_storage_nodes: 3

Refining your configuration

The plugins.security.allow_default_init_securityindex setting, when set to true, sets the Security plugin to its default security settings if an attempt to create the security index fails when OpenSearch launches. Default security settings are stored in YAML files contained in the opensearch-project/security/config directory. By default, this setting is false.

  1. plugins.security.allow_default_init_securityindex: true

An authentication cache for the Security plugin exists to help speed up authentication by temporarily storing user objects returned from the backend so that the Security plugin is not required to make repeated requests for them. To determine how long it takes for caching to time out, you can use the plugins.security.cache.ttl_minutes property to set a value in minutes. The default is 60. You can disable caching by setting the value to 0.

  1. plugins.security.cache.ttl_minutes: 60

Enabling user access to system indexes

Mapping a system index permission to a user allows that user to modify the system index specified in the permission’s name (the one exception is the Security plugin’s system index). The plugins.security.system_indices.permissions.enabled setting provides a way for administrators to make this permission available for or hidden from role mapping.

When set to true, the feature is enabled and users with permission to modify roles can create roles that include permissions that grant access to system indexes:

  1. plugins.security.system_indices.permissions.enabled: true

When set to false, the permission is disabled and only admins with an admin certificate can make changes to system indexes. By default, the permission is set to false in a new cluster.

To learn more about system index permissions, see System index permissions.

Password settings

If you want to run your users’ passwords against some validation, specify a regular expression (regex) in this file. You can also include an error message that loads when passwords don’t pass validation. The following example demonstrates how to include a regex so OpenSearch requires new passwords to be a minimum of eight characters with at least one uppercase, one lowercase, one digit, and one special character.

Note that OpenSearch validates only users and passwords created through OpenSearch Dashboards or the REST API.

  1. plugins.security.restapi.password_validation_regex: '(?=.*[A-Z])(?=.*[^a-zA-Z\d])(?=.*[0-9])(?=.*[a-z]).{8,}'
  2. plugins.security.restapi.password_validation_error_message: "Password must be minimum 8 characters long and must contain at least one uppercase letter, one lowercase letter, one digit, and one special character."

In addition, a score-based password strength estimator allows you to set a threshold for password strength when creating a new internal user or updating a user’s password. This feature makes use of the zxcvbn library to apply a policy that emphasizes a password’s complexity rather than its capacity to meet traditional criteria such as uppercase keys, numerals, and special characters.

For information about creating users, see Create users.

This feature is not compatible with users specified as reserved. For information about reserved resources, see Reserved and hidden resources.

Score-based password strength requires two settings to configure the feature. The following table describes the two settings.

SettingDescription
plugins.security.restapi.password_min_lengthSets the minimum number of characters for the password length. The default is 8. This is also the minimum.
plugins.security.restapi.password_score_based_validation_strengthSets a threshold to determine whether the password is strong or weak. There are four values that represent a threshold’s increasing complexity.
fair–A very “guessable” password: provides protection from throttled online attacks.
good–A somewhat guessable password: provides protection from unthrottled online attacks.
strong–A safely “unguessable” password: provides moderate protection from an offline, slow-hash scenario.
very_strong–A very unguessable password: provides strong protection from an offline, slow-hash scenario.

The following example shows the settings configured for the opensearch.yml file and enabling a password with a minimum of 10 characters and a threshold requiring the highest strength:

  1. plugins.security.restapi.password_min_length: 10
  2. plugins.security.restapi.password_score_based_validation_strength: very_strong

When you try to create a user with a password that doesn’t reach the specified threshold, the system generates a “weak password” warning, indicating that the password needs to be modified before you can save the user.

The following example shows the response from the Create user API when the password is weak:

  1. {
  2.   "status": "error",
  3.   "reason": "Weak password"
  4. }

allowlist.yml

You can use allowlist.yml to add any endpoints and HTTP requests to a list of allowed endpoints and requests. If enabled, all users except the super admin are allowed access to only the specified endpoints and HTTP requests, and all other HTTP requests associated with the endpoint are denied. For example, if GET _cluster/settings is added to the allow list, users cannot submit PUT requests to _cluster/settings to update cluster settings.

Note that while you can configure access to endpoints this way, for most cases, it is still best to configure permissions using the Security plugin’s users and roles, which have more granular settings.

  1. ---
  2. _meta:
  3.   type: "allowlist"
  4.   config_version: 2
  6. # Description:
  7. # enabled - feature flag.
  8. # if enabled is false, all endpoints are accessible.
  9. # if enabled is true, all users except the SuperAdmin can only submit the allowed requests to the specified endpoints.
  10. # SuperAdmin can access all APIs.
  11. # SuperAdmin is defined by the SuperAdmin certificate, which is configured with the opensearch.yml setting plugins.security.authcz.admin_dn:
  12. # Refer to the example setting in opensearch.yml to learn more about configuring SuperAdmin.
  13. #
  14. # requests - map of allow listed endpoints and HTTP requests
  16. #this name must be config
  17. config:
  18.   enabled: true
  19.   requests:
  20.     /_cluster/settings:
  21.       - GET
  22.     /_cat/nodes:
  23.       - GET

To enable PUT requests to cluster settings, add PUT to the list of allowed operations under /_cluster/settings.

  1. requests:
  2.   /_cluster/settings:
  3.     - GET
  4.     - PUT

You can also add custom indexes to the allow list. allowlist.yml doesn’t support wildcards, so you must manually specify all of the indexes you want to add.

  1. requests: # Only allow GET requests to /sample-index1/_doc/1 and /sample-index2/_doc/1
  2.   /sample-index1/_doc/1:
  3.     - GET
  4.   /sample-index2/_doc/1:
  5.     - GET

roles.yml

This file contains any initial roles that you want to add to the Security plugin. Aside from some metadata, the default file is empty, because the Security plugin has a number of static roles that it adds automatically.

  1. ---
  2. complex-role:
  3.   reserved: false
  4.   hidden: false
  5.   cluster_permissions:
  6.   - "read"
  7.   - "cluster:monitor/nodes/stats"
  8.   - "cluster:monitor/task/get"
  9.   index_permissions:
  10.   - index_patterns:
  11.     - "opensearch_dashboards_sample_data_*"
  12.     dls: "{\"match\": {\"FlightDelay\": true}}"
  13.     fls:
  14.     - "~FlightNum"
  15.     masked_fields:
  16.     - "Carrier"
  17.     allowed_actions:
  18.     - "read"
  19.   tenant_permissions:
  20.   - tenant_patterns:
  21.     - "analyst_*"
  22.     allowed_actions:
  23.     - "kibana_all_write"
  24.   static: false
  25. _meta:
  26.   type: "roles"
  27.   config_version: 2

roles_mapping.yml

  1. ---
  2. manage_snapshots:
  3.   reserved: true
  4.   hidden: false
  5.   backend_roles:
  6.   - "snapshotrestore"
  7.   hosts: []
  8.   users: []
  9.   and_backend_roles: []
  10. logstash:
  11.   reserved: false
  12.   hidden: false
  13.   backend_roles:
  14.   - "logstash"
  15.   hosts: []
  16.   users: []
  17.   and_backend_roles: []
  18. own_index:
  19.   reserved: false
  20.   hidden: false
  21.   backend_roles: []
  22.   hosts: []
  23.   users:
  24.   - "*"
  25.   and_backend_roles: []
  26.   description: "Allow full access to an index named like the username"
  27. kibana_user:
  28.   reserved: false
  29.   hidden: false
  30.   backend_roles:
  31.   - "kibanauser"
  32.   hosts: []
  33.   users: []
  34.   and_backend_roles: []
  35.   description: "Maps kibanauser to kibana_user"
  36. complex-role:
  37.   reserved: false
  38.   hidden: false
  39.   backend_roles:
  40.   - "ldap-analyst"
  41.   hosts: []
  42.   users:
  43.   - "new-user"
  44.   and_backend_roles: []
  45. _meta:
  46.   type: "rolesmapping"
  47.   config_version: 2
  48. all_access:
  49.   reserved: true
  50.   hidden: false
  51.   backend_roles:
  52.   - "admin"
  53.   hosts: []
  54.   users: []
  55.   and_backend_roles: []
  56.   description: "Maps admin to all_access"
  57. readall:
  58.   reserved: true
  59.   hidden: false
  60.   backend_roles:
  61.   - "readall"
  62.   hosts: []
  63.   users: []
  64.   and_backend_roles: []
  65. kibana_server:
  66.   reserved: true
  67.   hidden: false
  68.   backend_roles: []
  69.   hosts: []
  70.   users:
  71.   - "kibanaserver"
  72.   and_backend_roles: []

action_groups.yml

This file contains any initial action groups that you want to add to the Security plugin.

Aside from some metadata, the default file is empty, because the Security plugin has a number of static action groups that it adds automatically. These static action groups cover a wide variety of use cases and are a great way to get started with the plugin.

  1. ---
  2. my-action-group:
  3.   reserved: false
  4.   hidden: false
  5.   allowed_actions:
  6.   - "indices:data/write/index*"
  7.   - "indices:data/write/update*"
  8.   - "indices:admin/mapping/put"
  9.   - "indices:data/write/bulk*"
  10.   - "read"
  11.   - "write"
  12.   static: false
  13. _meta:
  14.   type: "actiongroups"
  15.   config_version: 2

tenants.yml

You can use this file to specify and add any number of OpenSearch Dashboards tenants to your OpenSearch cluster. For more information about tenants, see OpenSearch Dashboards multi-tenancy.

Like all of the other YAML files, we recommend you use tenants.yml to add any tenants you must have in your cluster, and then use OpenSearch Dashboards or the REST API if you need to further configure or create any other tenants.

  1. ---
  2. _meta:
  3.   type: "tenants"
  4.   config_version: 2
  5. admin_tenant:
  6.   reserved: false
  7.   description: "Demo tenant for admin user"

nodes_dn.yml

nodes_dn.yml lets you add certificates’ distinguished names (DNs) an allow list to enable communication between any number of nodes and/or clusters. For example, a node that has the DN CN=node1.example.com in its allow list accepts communication from any other node or certificate that uses that DN.

The DNs get indexed into a system index that only a super admin or an admin with a Transport Layer Security (TLS) certificate can access. If you want to programmatically add DNs to your allow lists, use the REST API.

  1. ---
  2. _meta:
  3.   type: "nodesdn"
  4.   config_version: 2
  6. # Define nodesdn mapping name and corresponding values
  7. # cluster1:
  8. #   nodes_dn:
  9. #       - CN=*.example.com