Skip to main content
Version: 5.1

Configuring a Certificate for SA Web

Overview​

This article describes the process of configuring TLS parameters for SA Web.

The article is divided into two sections covering the following configuration aspects:

  1. Server Certificate Configuration - this section provides instructions for setting up a TLS server certificate, which will be presented to users when accessing the web interface. It also explains how to install a root CA certificate into the Windows trusted certificate store to eliminate browser warnings. Use this section if you aim to achieve the following:

    • use a certificate separate from the one employed by SA Web for communication with Search Anywhere cluster nodes
    • avoid browser warnings about untrusted connections if the certificate is issued by a trusted Certificate Authority (CA)

  2. Client Certificate Verification Configuration - this section provides instructions for configuring client certificate verification when accessing the web interface. Use this section if you want to achieve the following:

    • authenticate users via certificates
    • deny connections to users without a trusted client certificate (if strict verification is enabled)

Prerequisites​

Note

It is assumed that all necessary certificates have already been generated before starting. If a certificate for accessing SA Web has not yet been obtained, contact your system administrator.

Files Used​

  • ca-server-cert.pem - the root certificate of the Certificate Authority that signed the server certificate
  • ca-client-cert.pem - the root certificate of the Certificate Authority used to verify client certificates
  • server-cert.pem -the server certificate signed by the Certificate Authority
  • server-key.pem - the private key corresponding to the server certificate

Conventions​

  • OSD_HOME - the home directory of SA Web, typically /app/opensearch-dashboards/

Server Certificate Configuration​

Configuring Search Anywhere Web Parameters​

Note

By default, SA Web uses the node certificates for the server, which are also used for communication with Search Anywhere cluster nodes.

Copy the CA-signed certificate and its corresponding private key (in this example, server-cert.pem and server-key.pem) to the $OSD_HOME/config/ directory.

On the host where SA Web is installed, open the <OSD_HOME>/config/opensearch_dashboards.yml file. In the TLS Settings section, replace the current parameters with the following (using the conventions above):

server.ssl.certificate: <OSD_HOME>/config/server-cert.pem
server.ssl.key: <OSD_HOME>/config/server-key.pem

After making these changes, restart and check the status of the opensearch-dashboards service using the following commands:

systemctl restart opensearch-dashboards
systemctl status opensearch-dashboards

The server certificate configuration for SA Web is now complete.

Installing the CA Certificate in the System​

Important!

If your certificate is issued by a publicly trusted Certificate Authority or an organizational CA from a workstation accessing SA Web, the root CA certificate is likely already installed in the OS. In this case, adding the certificate to the trusted store is unnecessary.

To ensure the browser trusts the SA Web certificate, add the CA certificate to the trusted root certification authorities store.

Open the Run dialog by pressing Win + R, type certmgr.msc, and press Enter. This will open the Certificate Manager.

In the left pane, navigate to Trusted Root Certification Authorities - Certificates. Right-click an empty area in the right pane, select Action - All Tasks - Import.

The Certificate Import Wizard will launch. Click Next, then browse and select the certificate file (ca-server-cert.pem) saved on your computer. Click Next again.

Continue clicking Next, keeping the default settings, until the Import was successful message appears.

After completing these steps, the untrusted certificate warning should no longer appear when accessing SA Web.

Client Certificate Verification Configuration​

Copy the CA certificate (in this example, ca-client-cert.pem) to the <OSD_HOME>/config/ directory.

On the host where SA Web is installed, open the <OSD_HOME>/config/opensearch_dashboards.yml file. In the TLS Settings section, specify the following parameters (using the conventions above):

server.ssl.clientAuthentication: required
server.ssl.certificateAuthorities: [ "<OSD_HOME>/config/ca-client-cert.pem" ]
Note

The server.ssl.clientAuthentication parameter accepts either optional or required. When set to required, the web interface service will request the client's browser to send a client certificate signed by a Certificate Authority whose root certificate is specified in server.ssl.certificateAuthorities. If either condition is not met, the client's access to Search Anywhere will be denied.

After making these changes, restart and check the opensearch-dashboards service using the following commands:

systemctl restart opensearch-dashboards
systemctl status opensearch-dashboards

The client certificate verification configuration for SA Web is now complete.