Quick Links
- Introduction
- How to set up certificates in OpenSearch
- Replace the demo certificates
- Reconfigure opensearch.yml to use your certificates
- Reconfigure config.yml to use your authentication backend
- Modify the configuration YAML files
- If you plan to use the internal user database, set a password policy in opensearch.yml
- Apply changes using securityadmin.sh
- Start OpenSearch
- Add users, roles, role mappings, and tenants
- Conclusion
Introduction
This article is Part II of a 3-part series on how to secure an OpenSearch cluster.
- Part I – Access Control (users, roles, permissions, etc)
- Part II – Configuration (certificates)
- Part III – Audit logs (how to create a Dashboard to visualize audit logs)
In Part I – Access Control, we covered how to configure users and roles within a development environment. Now we will prepare our cluster for production by configuring certificates.
The plugin includes demo certificates so that you can get up and running quickly, but before using OpenSearch in a production environment, you must configure it manually.
How to set up certificates in OpenSearch
How to set up certificates in OpenSearch (detailed below):
- Replace the demo certificates
- Reconfigure opensearch.yml to use your certificates
- Reconfigure config.yml to use your authentication backend (if you don’t plan to use the internal user database)
- Modify the configuration YAML files
- If you plan to use the internal user database, set a password policy in opensearch.yml
- Apply changes using securityadmin.sh
- Start OpenSearch
- Add users, roles, role mappings, and tenants
1. Replace the demo certificates.
If you are using the tarball installation, you can just replace the demo certificates with your own. However, if you’re using Docker, you have to edit the YAML storage volume to include the files for the replacement.
This is how the volumes piece of the docker-compose field would look:
volumes: opensearch-data2:/usr/share/opensearch/data ./root-ca.pem:/usr/share/opensearch/config/root-ca.pem ./node.pem:/usr/share/opensearch/config/node.pem ./node-key.pem:/usr/share/opensearch/config/node-key.pem ./admin.pem:/usr/share/opensearch/config/admin.pem ./admin-key.pem:/usr/share/opensearch/config/admin-key.pem ./custom-opensearch.yml:/usr/share/opensearch/config/opensearch.yml ./internal_users.yml:/usr/share/opensearch/config/opensearch-security/internal_users.yml ./roles_mapping.yml:/usr/share/opensearch/config/opensearch-security/roles_mapping.yml ./tenants.yml:/usr/share/opensearch/config/opensearch-security/tenants.yml ./roles.yml:/usr/share/opensearch/config/opensearch-security/roles.yml ./action_groups.yml:/usr/share/opensearch/config/opensearch-security/action_groups.yml
The certificates needed are:
- root-ca.pem
- admin.pem
- admin-key.pem
- node1.pem
- node1-key.pem
You can use your own Certificate Authority to sign the certificates, or go the self-signed route.
2. Reconfigure opensearch.yml to use your certificates.
To configure Docker to read the correct cert files / replace the certificates in the tarball installation, you need to change the opensearch.yml file to use these certificates.
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 plugins.security.nodes_dn:› - 'CN=N,OU=UNIT,O=ORG,L=TORONTO,ST=ONTARIO,C=CA'
Certificate settings
The table below explains each of the above settings. Note the difference between ssl.http and ssl.transport. http is the REST layer, while transport is the Transport layer. The REST layer is the one that handles the communication between the client and the cluster, and the transport layer is the one that handles the internal communication between nodes.
| Name (plugins.security.*) | Description |
| ssl.transport.pemcert_filepath | Required. Path to the X.509 node certificate chain (PEM format), which must be under the config directory, specified using a relative path. |
| ssl.transport.pemkey_filepath | Required. Path to the certificate’s key file (PKCS #8), which must be under the config directory, specified using a relative path. |
| ssl.transport.pemtrustedcas_filepath | Required. Path to the root CAs (PEM format), which must be under the config directory, specified using a relative path. |
| ssl.transport.enforce_hostname_verification | Optional. Whether to verify hostnames on the transport layer. Default is true. |
| ssl.http.enabled | Optional. Whether to enable TLS on the REST layer. If enabled, only HTTPS is allowed. Default is false. |
| ssl.http.pemcert_filepath | Required. Path to the X.509 node certificate chain (PEM format), which must be under the config directory, specified using a relative path. |
| ssl.http.pemkey_filepath | Required. Path to the certificate’s key file (PKCS #8), which must be under the config directory, specified using a relative path. |
| ssl.http.pemtrustedcas_filepath | Required. Path to the root CAs (PEM format), which must be under the config directory, specified using a relative path. |
| allow_default_init_securityindex | If this is set to true, Opensearch Security will automatically initialize the configuration index with the files in the config directory if the index does not exist. WARNING: This will use well-known default passwords. Use only in a private network/environment. |
| authcz.admin_dn | Admin certificates are regular client certificates that have elevated rights to perform administrative tasks. For security reasons, you can’t use wildcards or regular expressions here. |
| nodes_dn | The security plugin needs to identify inter-cluster requests (i.e. requests between the nodes). All DNs must be included in opensearch.yml on all nodes. The security plugin supports wildcards and regular expressions. |
The full list can be found here.
3. Reconfigure config.yml to use your authentication backend
In Part I – Access Control we learned how to use the internal users (also called native users) from Opensearch without using an external source like SSO for the users provisioning.
If you want to use an external source, you have to configure it in the config.yml file. We will cover the external authentication in depth in future articles, but we will point out some of the important parts as reference.
HTTP Basic Auth
As an example, we will use a backend with Basic HTTP implemented for our users.
http_authenticator: type: basic challenge: true
If challenge is set to true, the security plugin sends a 401 status and the browser will show the user a prompt for credentials.
You can find the entire reference file here.
4. Modify the configuration YAML files.
Before running securityadmin.sh to load settings, you can configure initial users, roles, tenants, etc (full reference here).
YAML file functions:
| File | Description |
| internal_users.yml | Any initial user, requires a hashed password. Use plugins/opensearch-security/tools/hash.sh -p |
| opensearch.yml | As described earlier in this article. |
| allowlist.yml | Security at endpoint level. |
| roles.yml | Initial security roles. |
| roles_mapping.yml | Initial roles mapping. |
| action_groups.yml | Initial action groups. |
| tenants.yml | Initial tenants. Tenants are useful for multi-tenancy, to scope different sets of saved objects like Dashboards and provide access to different user roles. |
| nodes_dn.yml | Enables you to add distinguished names (DNs) and allow communication between nodes and/or clusters. |
5. If you plan to use the internal user database, set a password policy in opensearch.yml.
Set the following to validate user passwords created using the rest API, by defining a regex pattern and an error message:
plugins.security.restapi.password_validation_regex: '(?=.*[A-Z])(?=.*[^a-zA-Z\d])(?=.*[0-9])(?=.*[a-z]).{8,}'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.”
6. Apply changes using securityadmin.sh
securityadmin.sh is a script that facilitates customization of security settings and performance of maintenance operations like backup, restore and migrate configurations. This script can be run from any of the nodes, just make sure the script is executable:
chmod +x plugins/opensearch-security/tools/securityadmin.sh
Running this script will load the yml configurations into the .opendistro_security index.
Everytime you make changes in the config/opensearch-security configurations file you have to run the script again.
To run the script use:
plugins/opensearch-security/tools/securityadmin.sh
Example using PEM certificates:
/usr/share/opensearch/plugins/opensearch-security/tools/securityadmin.sh \ -cacert /etc/opensearch/root-ca.pem \ -cert /etc/opensearch/kirk.pem \ -key /etc/opensearch/kirk-key.pem \ -cd /usr/share/opensearch/config/opensearch-security/
Full reference can be found here.
7. Start OpenSearch.
Depending on your installation, start OpenSearch as usual.
8. Add users, roles, role mappings, and tenants.
From here you can add more security assets from the UI, or use the rest API. The recommendation is to use the yml files just for initial/internal users.
UI Reference for security can be found here.
Rest API reference for security can be found here.
Conclusion
In this installment of security configuration in OpenSearch, we learned how to protect our cluster and use the basic authentication.
In Part III we explore Audit Logs, and how to create a Dashboard to visualize these.
