Enabling SSL for the Elastic Stack using an external certificate

Configure SSL for the Elastic Stack using a properly chained certificate from a trusted certificate authority (CA).

Before you begin

You must be a cluster administrator.
You must ensure that the clock settings on the server and client are identical. Otherwise, errors may occur.

You must be a cluster administrator.

About this task

Follow these steps if you want to:

Enable SSL for the first time (in other words, if you disabled SSL during installation by setting DISABLESSL=Y).
Use a properly chained certificate from a trusted CA that replaces the default self-signed certificate when SSL is enabled during installation.

When SSL is enabled for the Elastic Stack, a trust relationship between the server and the client is established by sending a server certificate to the client. The client validates the certificates that are signed by a trusted CA. For your production environment, ensure that you use a properly chained certificate that is issued or signed by a trusted CA. By default the Elastic Stack uses the TLSv1.2 protocol.

Note: On a local file system, Tier 1 files must be generated on all management hosts. On a shared file system, the files need to be generated on a shared file system location that all management hosts can access.

Procedure

Stop the elk-shipper, elk-indexer, elk-elasticsearch, elk-elasticsearch-master, and elk-elasticsearch-data services:
```
egosh service stop elk-shipper elk-indexer elk-elasticsearch elk-elasticsearch-master elk-elasticsearch-data
```
Generate the server trust store file by running:
```
keytool -importcert -noprompt -alias srvalias -file cacert.pem_location -keystore serverTrustStore.jks -storepass storepass
```
where cacert.pem_location is the path to the cacert.pem file that you saved previously, and storepass specifies the keystore password; for example: Liberty.
Secure communication between the elk-shipper and elk-indexer services by enabling host name and certificate verification. This verification is disabled by default. Ensure that you enable this verification in your production environment. For this step, you require the SSL certificate in .pem format (for example, cert.pem) that you downloaded in Enabling SSL for the cluster management console using a self-signed certificate.
1. Rename this .pem certificate (for example, cert.pem) as certificate.pem. If your vendor provided multiple .pem certificates, concatenate each file into a single .pem file, called certificate.pem, in the following order:
```
-----BEGIN CERTIFICATE----- 
[contents of server certificate]
-----END CERTIFICATE----- 
-----BEGIN CERTIFICATE----- 
[contents of intermediate certificate]
-----END CERTIFICATE----- 
-----BEGIN CERTIFICATE----- 
[contents of root certificate]
-----END CERTIFICATE----
```
2. Edit $EGO_TOP/integration/elk/conf/indexer/indexer.conf to specify the path to your SSL keystore and certificate. For example:
```
# cat $EGO_TOP/integration/elk/conf/indexer/indexer.conf
input {
  beats {
    port => "5043"
    ssl => true
    ssl_certificate => "path_to_certificate.pem"
    ssl_key =>"path_to_private_key.key"
  }
}
```
  where:
  - path_to_certificate.pem specifies the path to the .pem certificate (for example, certificate.pem). Ensure that the certificate is deployed to all hosts in your production cluster.
  - path_to_private.key specifies the path to the private key that you generated in Enabling SSL for the cluster management console using a self-signed certificate (for example, private.key).
  Attention: Do not include any redundant or unused configuration files in the {ELK_CONFDIR}/indexer directory. Otherwise, the elk-indexer service fails to start.
3. On all your hosts, edit the $EGO_TOP/integration/elk/conf/filebeat.yml.template file:
  - Remove the insecure: true setting to enable client verification of server certificates and host name.
  - Update the certificate_authorities setting to point to your root CA certificate.
  For example:
```
# cat $EGO_TOP/integration/elk/conf/filebeat.yml.template
filebeat:
  config_dir: "../conf/"

output:
  logstash:
    hosts: [@INDEXERS@]
    loadbalance: true
    ssl.certificate_authorities: ["${DEPLOY_HOME}/${ELK_VERSION}/scripts/lumberjack.crt"]
    ssl.verification_mode: none
```
  where path_to_certificate.pem specifies the path to the .pem certificate (for example, certificate.pem).
Secure communication to the Elasticsearch services (elk-elasticsearch, elk-elasticsearch-master, and elk-elasticsearch-data). For this step, you require an SSL certificate in .pem format (for example, cert.pem):
1. Move the SSL keystore and certificate to a location that is shared by all nodes.
2. Enable SSL for the Elastic Stack services by setting the searchguard.ssl.http.enabled parameter to true in the Elasticsearch configuration file. The configuration file is located at $EGO_CONFDIR/../../integration/elk/conf/elasticsearch/elasticsearch.yml. To disable SSL, see Disabling SSL for the Elastic Stack.
3. Encrypt the password using the securityUtilities command. For more information, see:
  - Liberty profile: securityUtility command
4. Edit the Elasticsearch configuration file according to the SSL keystore and certificate. By default, the transport and HTTP communication layers are configured with the same SSL keystore and certificate. The searchguard.nodes_dn parameter must be modified based on the owner (not issuer) of your server endpoint certificates. To use an external certificate, modify the configuration file as follows:
  If you are using an encrypted password for any Search Guard SSL password parameters, you must add double quotation marks around it.
```
searchguard.nodes_dn:
  - 'CN=*,O=IBM,C=CA'
searchguard.ssl.transport.enabled: true
searchguard.ssl.transport.enforce_hostname_verification: false
searchguard.ssl.transport.keystore_filepath: $EGO_TOP/wlp/usr/shared/resources/security/externalKeyStore.jks
searchguard.ssl.transport.truststore_filepath: $EGO_TOP/wlp/usr/shared/resources/security/externalTrustStore.jks
searchguard.ssl.transport.keystore_password: "{aes}ABE7CTHBolSmXwkUH9+xyxpYVO8H4lyllJKito98fpC5"
searchguard.ssl.transport.truststore_password: "{aes}ABE7CTHBolSmXwkUH9+xyxpYVO8H4lyllJKito98fpC5"
searchguard.ssl.transport.keystore.type: jks
searchguard.ssl.transport.truststore.type: jks
searchguard.ssl.transport.keystore_alias: srvalias
searchguard.ssl.transport.truststore_alias: srvalias
searchguard.ssl.transport.enabled.protocols:
   - "TLSv1.2"
searchguard.ssl.http.enabled: true
searchguard.ssl.http.enabled.protocols:
  - "TLSv1.2"
searchguard.ssl.http.keystore_filepath: $EGO_TOP/wlp/usr/shared/resources/security/externalKeyStore.jks
searchguard.ssl.http.truststore_filepath: $EGO_TOP/wlp/usr/shared/resources/security/externalTrustStore.jks
searchguard.ssl.http.keystore_password: "{aes}ABE7CTHBolSmXwkUH9+xyxpYVO8H4lyllJKito98fpC5"
searchguard.ssl.http.truststore_password: "{aes}ABE7CTHBolSmXwkUH9+xyxpYVO8H4lyllJKito98fpC5"
searchguard.ssl.http.keystore.type: jks
searchguard.ssl.http.truststore.type: jks
searchguard.ssl.http.keystore_alias: srvalias
searchguard.ssl.http.truststore_alias: srvalias
```
  Note:
  - The two keystore_alias values refer to the PrivateKeyEntry of the server endpoint certificates in the keystore file.
  - The two truststore_alias values refer to the trustedCertEntry of the root certificate in the truststore file.
5. Check the value of the CA_CERT_PATH parameter in $EGO_CONFDIR/../../integration/elk/conf/elk.conf. By default, this parameter's value is ${EGO_TOP}/wlp/usr/shared/resources/security/cacert.pem.
Start the elk-shipper, elk-indexer, elk-elasticsearch, elk-elasticsearch-master, and elk-elasticsearch-data services:
```
egosh service start elk-shipper elk-indexer elk-elasticsearch elk-elasticsearch-master elk-elasticsearch-data
```

Update the Explorer access protocol so that you can view Explorer reports in the cluster management console after enabling SSL for the Elastic Stack:

Open the $EGO_CONFDIR/../../explorer/config/config.json file for editing.

Locate the "protocol":"http" line, and change it to "protocol":"https".

For example:


{
    "pa.net.port": 5000,
    "pa.metadata": {
        "datasource": "ds1",
        "index": "model"
    },
    "pa.dashboard.default": "cluster_overview",
    "pa.query.size.max": 10000,
    "pa.query.timeout" : 300000,
    "pa.logging": {
        "logLevel": "debug",
        "appName": "server",
        "logDir": "logs",
        "datasource": "ds1"
    },
    "pa.datasources": {
"ds1": {"name": "ES Instance1", "type": "elasticsearch", "hosts": [{"host" : "user.example.ibm.com", "port": 9200, "protocol":"https"}]}
    },
    "pa.allow.cross.domain": "false",
    "pa.allow.limited.access": "true",
    "pa.allow.access.ips": "9.21.52.21",
    "elasticsearch.version" : "7.2.1"
}

Save and close the file.
Restart the Explorer service for the changes to take effect:
```
egosh service stop Explorer
egosh service start Explorer
```