Documentation Commerce Installation Guide

Configure Nginx for your search engine

Last update: Thu Jun 15 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

Topics:
Install
Search

CREATED FOR:

Experienced
Admin
Developer

This topic discusses an example of securing communication between your web server and search engine (Elasticsearch or OpenSearch) using a combination of Transport Layer Security (TLS) encryption and HTTP basic authentication. You can optionally configure other types of authentication as well; we provide references for that information.

(An older term, Secure Sockets Layer (SSL), is frequently used interchangeably with TLS. In this topic, we refer to TLS.)

WARNING

Unless otherwise noted, all commands in this topic must be entered as a user with root privileges.

Recommendations

We recommend the following:

Your web server uses TLS.

TLS is beyond the scope of this topic; however, we strongly recommend you use a real certificate in production and not a self-signed certificate.
Your search engine runs on the same host as a web server. Running the search engine and the web server on different hosts is beyond the scope of this topic.

The advantage of putting search engine and the web server on the same host is that it makes intercepting encrypted communication impossible. The search engine web server does not have to be the same as the Adobe Commerce or Magento Open Source web server; for example, Adobe Commerce can run Apache and Elasticsearch/OpenSearch can run nginx.

If the search engine is exposed to the public web, you should configure authentication. If your search engine instance is protected within your network, this may not be necessary. Work with your hosting provider to determine which security measures you should implement to protect your instance.

More information about TLS

See one of the following resources:

Set up a proxy

NOTE

OpenSearch support was added in 2.4.4. OpenSearch is a compatible fork of ElasticSearch. See Migrate ElasticSearch to OpenSearch for more information.

This section discusses how to configure nginx as an unsecure proxy so that Adobe Commerce can use a search engine running on this server. This section does not discuss setting up HTTP Basic authentication; that is discussed in Secure communication with nginx.

NOTE

The reason the proxy is not secured in this example is that it is easier to set up and verify. You can use TLS with this proxy if you want; to do so, make sure you add the proxy information to your secure server block configuration.

Specify additional configuration files in your global configuration

Make sure your global /etc/nginx/nginx.conf contains the following line so it loads the other configuration files discussed in the following sections:

include /etc/nginx/conf.d/*.conf;

Set up nginx as a proxy

This section discusses how to specify who can access the nginx server.

Use a text editor to create a file /etc/nginx/conf.d/magento_es_auth.conf with the following contents:

code language-conf
`server { listen 8080; location /_cluster/health { proxy_pass http://localhost:9200/_cluster/health; } }`

Restart nginx:

code language-bash
`service nginx restart`

Verify the proxy works by entering the following command:

code language-bash
`curl -i http://localhost:<proxy port>/_cluster/health`

For example, if your proxy uses port 8080:

code language-bash
`curl -i http://localhost:8080/_cluster/health`

Messages similar to the following display to indicate success:

code language-terminal

code language-terminal
HTTP/1.1 200 OK Date: Tue, 23 Feb 2019 20:38:03 GMT Content-Type: application/json; charset=UTF-8 Content-Length: 389 Connection: keep-alive {"cluster_name":"elasticsearch","status":"yellow","timed_out":false,"number_of_nodes":1,"number_of_data_nodes":1,"active_primary_shards":5,"active_shards":5,"relocating_shards":0,"initializing_shards":0,"unassigned_shards":5,"delayed_unassigned_shards":0,"number_of_pending_tasks":0,"number_of_in_flight_fetch":0,"task_max_waiting_in_queue_millis":0,"active_shards_percent_as_number":50.0}

HTTP/1.1 200 OK
Date: Tue, 23 Feb 2019 20:38:03 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 389
Connection: keep-alive

{"cluster_name":"elasticsearch","status":"yellow","timed_out":false,"number_of_nodes":1,"number_of_data_nodes":1,"active_primary_shards":5,"active_shards":5,"relocating_shards":0,"initializing_shards":0,"unassigned_shards":5,"delayed_unassigned_shards":0,"number_of_pending_tasks":0,"number_of_in_flight_fetch":0,"task_max_waiting_in_queue_millis":0,"active_shards_percent_as_number":50.0}

Secure communication with nginx

This section discusses how to set up HTTP Basic authentication with your secure proxy. Use of TLS and HTTP Basic authentication together prevents anyone from intercepting communication with Elasticsearch or OpenSearch or with your application server.

Because nginx natively supports HTTP Basic authentication, we recommend it over, for example, Digest authentication, which isn’t recommended in production.

Additional resources:

See the following sections for more information:

Create passwords
Set up access to nginx
Set up a restricted context for the search engine
Verify that communication is secure

Create a password

We recommend you use the Apache htpasswd command to encode passwords for a user with access to Elasticsearch or OpenSearch (named magento_elasticsearch in this example).

To create a password:

Enter the following command to determine if htpasswd is already installed:

code language-bash
`which htpasswd`

If a path displays, it is installed; if the command returns no output, htpasswd is not installed.

If necessary, install htpasswd:
- Ubuntu: apt-get -y install apache2-utils
- CentOS: yum -y install httpd-tools

Create a /etc/nginx/passwd directory to store passwords:

code language-bash
`mkdir -p /etc/nginx/passwd`

code language-bash
`htpasswd -c /etc/nginx/passwd/.<filename> <username>`

note warning
WARNING
For security reasons, `<filename>` should be hidden; that is, it must start with a period.

(Optional). To add another user to your password file, enter the same command without the -c (create) option:

code language-bash
`htpasswd /etc/nginx/passwd/.<filename> <username>`

Verify that the contents of /etc/nginx/passwd is correct.

Set up access to nginx

This section discusses how to specify who can access the nginx server.

WARNING

The example shown is for an unsecure proxy. To use a secure proxy, add the following contents (except the listen port) to your secure server block.

Use a text editor to modify either /etc/nginx/conf.d/magento_es_auth.conf (unsecure) or your secure server block with the following contents:

server {
  listen 8080;
  server_name 127.0.0.1;

  location / {
   limit_except HEAD {
      auth_basic "Restricted";
      auth_basic_user_file  /etc/nginx/passwd/.htpasswd_magento_elasticsearch;
   }
   proxy_pass http://127.0.0.1:9200;
   proxy_redirect off;
   proxy_set_header Host $host;
   proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  }

  location /_aliases {
   auth_basic "Restricted";
   auth_basic_user_file  /etc/nginx/passwd/.htpasswd_magento_elasticsearch;
   proxy_pass http://127.0.0.1:9200;
   proxy_redirect off;
   proxy_set_header Host $host;
   proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  }

  include /etc/nginx/auth/*.conf;
}

NOTE

The search engine listen port shown in the preceding example are examples only. For security reasons, we recommend you use a non-default listen port.

Set up a restricted context for the search engine

This section discusses how to specify who can access the search engine server.

Enter the following command to create a directory to store the authentication configuration:

code language-bash
`mkdir /etc/nginx/auth/`

Use a text editor to create a file /etc/nginx/auth/magento_elasticsearch.conf with the following contents:

code language-conf

code language-conf
`location /elasticsearch { auth_basic "Restricted - elasticsearch"; auth_basic_user_file /etc/nginx/passwd/.htpasswd_magento_elasticsearch; proxy_pass http://127.0.0.1:9200; proxy_redirect off; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; }`

location /elasticsearch {
auth_basic "Restricted - elasticsearch";
auth_basic_user_file /etc/nginx/passwd/.htpasswd_magento_elasticsearch;

proxy_pass http://127.0.0.1:9200;
proxy_redirect off;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

If you set up a secure proxy, delete /etc/nginx/conf.d/magento_es_auth.conf.

Restart nginx and continue with the next section:

code language-bash
`service nginx restart`

Verify

This section discusses two ways to verify that HTTP Basic authentication is working:

Using a curl command to verify you must enter a username and password to get cluster status
Configuring HTTP Basic authentication in the Admin

Use a `curl` command to verify cluster status

Enter the following command:

curl -i http://<hostname, ip, or localhost>:<proxy port>/_cluster/health

For example, if you enter the command on the search engine server and your proxy uses port 8080:

curl -i http://localhost:8080/_cluster/health

The following message displays to indicate authentication failed:

HTTP/1.1 401 Unauthorized
Date: Tue, 23 Feb 2016 20:35:29 GMT
Content-Type: text/html
Content-Length: 194
Connection: keep-alive
WWW-Authenticate: Basic realm="Restricted"
<html>
<head><title>401 Authorization Required</title></head>
<body bgcolor="white">
  <center><h1>401 Authorization Required</h1></center>
</body>
</html>

Now try the following command:

curl -i -u <username>:<password> http://<hostname, ip, or localhost>:<proxy port>/_cluster/health

For example:

curl -i -u magento_elasticsearch:mypassword http://localhost:8080/_cluster/health

This time the command succeeds with a message similar to the following:

HTTP/1.1 200 OK
Date: Tue, 23 Feb 2016 20:38:03 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 389
Connection: keep-alive
{"cluster_name":"elasticsearch","status":"yellow","timed_out":false,"number_of_nodes":1,"number_of_data_nodes":1,"active_primary_shards":5,"active_shards":5,"relocating_shards":0,"initializing_shards":0,"unassigned_shards":5,"delayed_unassigned_shards":0,"number_of_pending_tasks":0,"number_of_in_flight_fetch":0,"task_max_waiting_in_queue_millis":0,"active_shards_percent_as_number":50.0}

Configure HTTP Basic authentication in the Admin

Perform the same tasks as discussed in Search engine configuration except click Yes from the Enable HTTP Auth list and enter your username and password in the provided fields.

Click Test Connection to make sure it works and then click Save Config.

You must flush the cache and reindex before you continue.

recommendation-more-help

0f8e7db5-0e9c-4002-a5b8-a0088077d995

Configure Nginx for your search engine

Recommendations

More information about TLS

Set up a proxy

Specify additional configuration files in your global configuration

Set up nginx as a proxy

Secure communication with nginx

Create a password

Set up access to nginx

Set up a restricted context for the search engine

Verify

Use a curl command to verify cluster status

Configure HTTP Basic authentication in the Admin

Use a `curl` command to verify cluster status