Elasticsearch OpenSearch Security – Configuration (Certificates)

Average Read Time

5 Mins

Elasticsearch OpenSearch Security – Configuration (Certificates)

Opster Expert Team - Gustavo

Aug-2022

Average Read Time

5 Mins

Opster Team

Sep 11, 2022

Average Read Time

5 Mins


In addition to reading this guide, we recommend you run the Elasticsearch Health Check-Up. It will detect issues and improve your Elasticsearch performance by analyzing your shard sizes, threadpools, memory, snapshots, disk watermarks and more.

The Elasticsearch Check-Up is free and requires no installation.

To manage all aspects of your OpenSearch operation, you can use Opster’s Management Console (OMC). The OMC makes it easy to orchestrate and manage OpenSearch in any environment. Using the OMC you can deploy multiple clusters, configure node roles, scale cluster resources, manage certificates and more – all from a single interface, for free. Check it out here.

Quick Links

Introduction

This article is Part II of a 3-part series on how to secure an OpenSearch cluster. 

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

  1. Replace the demo certificates.

  2. Reconfigure opensearch.yml to use your certificates.

  3. Reconfigure config.yml to use your authentication backend (if you don’t plan to use the internal user database).

  4. Modify the configuration YAML files.

  5. If you plan to use the internal user database, set a password policy in opensearch.yml.

  6. Apply changes using securityadmin.sh.

  7. Start OpenSearch.

  8. 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_filepathRequired. 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_filepathRequired. Path to the certificate’s key file (PKCS #8), which must be under the config directory, specified using a relative path.
ssl.transport.pemtrustedcas_filepathRequired. Path to the root CAs (PEM format), which must be under the config directory, specified using a relative path.
ssl.transport.enforce_hostname_verificationOptional. Whether to verify hostnames on the transport layer. Default is true.
ssl.http.enabledOptional. Whether to enable TLS on the REST layer. If enabled, only HTTPS is allowed. Default is false.
ssl.http.pemcert_filepathRequired. 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_filepathRequired. Path to the certificate’s key file (PKCS #8), which must be under the config directory, specified using a relative path.
ssl.http.pemtrustedcas_filepathRequired. Path to the root CAs (PEM format), which must be under the config directory, specified using a relative path.
allow_default_init_securityindexIf 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_dnAdmin 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_dnThe 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.ymlAny initial user, requires a hashed password. Use plugins/opensearch-security/tools/hash.sh -p to create a password. Also change the password of the reference users you want to keep.
opensearch.ymlAs described earlier in this article.
allowlist.ymlSecurity at endpoint level.
roles.ymlInitial security roles.
roles_mapping.ymlInitial roles mapping.
action_groups.ymlInitial action groups.
tenants.ymlInitial 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.ymlEnables 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. 



Run the Check-Up to get a customized report like this:

Analyze your cluster
Skip to content