YAML files

    The best use of these YAML files is to configure reserved and hidden resources, such as the admin and kibanaserver users. You might find it easier to create other users, roles, mappings, action groups, and tenants using OpenSearch Dashboards or the REST API.

    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 to apply the new passwords.

    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.restapi.roles_enabled: ["all_access", "security_rest_api_access"]
    18. plugins.security.system_indices.enabled: true
    19. 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*"]
    20. node.max_local_storage_nodes: 3

    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.

    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."

    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.

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

    action_groups.yml

    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

    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 .

    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.

    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 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: