Skip to main content
Skip table of contents

How to create signing certificates for Shinydocs Pro

Some connectors for Shinydocs Pro require the use of signed certificates in order for Shinydocs Pro to safely and securely connect with an external data source or content repository.

You may wish to secure Shinydocs Pro using certificates from your own certificate authority or from a trusted certificate authority. This article provides the necessary details required to generate the certificate signing requests, and to apply them to the Shinydocs Pro installation.

Prerequisites
Overview
Generating a Host Certificate
Generating a Client Certificate
OpenSearch Configuration
OpenSearch Dashboards Configuration
Control Center Configuration
Enterprise Search Configuration

Prerequisites

  • OpenSSL 3.x must be installed and running on the system

  • Note the DNS names and IP addresses of the host system(s) where Shinydocs Pro is installed. This includes the following systems:

    • OpenSearch

    • OpenSearch Dashboards

    • Shinydocs Control Center

    • Shinydocs Enterprise Search

Shinydocs Pro installs each of the four components above onto the same host by default. If you are installing Shinydocs Pro onto only one host, only one host certificate is required for the four components listed above.

Overview

The following certificate signing requests will need to be generated so that a certificate authority can generate the required certificates:

  • OpenSearch

    • Host Certificate

    • Admin Certificate (i.e. a client certificate used to apply security configuration changes to the OpenSearch cluster)

  • OpenSearch Dashboards

    • Host Certificate

    • Client Certificate (Must have the common name set as ‘kibanaserver’)

      • Note that the client certificate signing request is OPTIONAL and is only required if you wish to use certificate-based authentication for OpenSearch Dashboards instead of connecting to OpenSearch via of username / password. Note: users will still need to authenticate using one of the many authentication methods available in OpenSearch, this option simply establishes the API connection to OpenSearch through the Dashboards process.

  • Shinydocs Control Center

    • Host Certificate

  • Shinydocs Enterprise Search

    • Host Certificate

Generating a Host Certificate

Prerequisites

  • Fully Qualified Domain Name of the host (e.g., opensearch01.example.local)

  • Hostname (e.g., opensearch01)

  • IP Address of the host (e.g., 10.0.1.15)

  • Country Code (e.g., CA for Canada, US for the United States of America)

  • State or Province (e.g. Ontario or New York)

  • Locality Name or City (e.g., Kitchener or Buffalo)

  • Organization Name (e.g., Shinydocs Corporation or Example Inc)

  • Organization Unit (e.g. Information Technology)

  • Common Name / Fully Qualified Domain Name (e.g., opensearch01.example.local)

Generating the Certificate Signing Request (CSR)

  1. From a command prompt, execute the following command to generate a key and certificate signing request, substituting the values from above in the command line when requested by the command prompt.

    CODE 
    openssl req -addext "subjectAltName = DNS:<FQDN>,DNS:<hostname>,IP:<IP Address>" -newkey rsa:4096 -keyout <hostname>.key -out <hostname>.csr -noenc

    For example:

    CODE 
    openssl req -addext "subjectAltName = DNS:opensearch01.example.local,DNS:opensearch01,IP:10.0.1.15" -newkey rsa:4096 -keyout opensearch01.key -out opensearch01.csr -noenc

  2. The execution of the command should look something like this

    CODE 
    openssl req -addext "subjectAltName = DNS:opensearch01.example.local,DNS:opensearch01,IP:10.0.1.15" -newkey rsa:4096 -keyout opensearch01.key -out opensearch01.csr -noenc
.+.........+......+..+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*.............+......+..+.........+...............+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*.+.....+................+..+.+..+...+.......+..+......+.......+.........+........+............+......+.........+...+.+..+....+...........+......................+......+......+.....+.........+.+.....+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
.+...+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*........+......+....+.....+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*................+..+.......+.....+....+.....................+......+...+.....+...............................+.........+.........+...........+.+.....................+..............+......+...+.......+...+...........+.............+............+...+..+.+........+.+......+..+.......+...........+.......+..+....+..+...........................+.............+...+...........+...+......+.+......+..+.......+......+........+...............+....+..+...............+......+...+.........+...+...................+...........+...+....+........+.......+......+.........+.....+.......+...............+...+......+...........+...+.............+...+..+............................+.........+........+.............+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [XX]:CA
State or Province Name (full name) []:Ontario
Locality Name (eg, city) [Default City]:Kitchener
Organization Name (eg, company) [Default Company Ltd]:Shinydocs Corporation
Organizational Unit Name (eg, section) []:Information Technology
Common Name (eg, your name or your server's hostname) []:opensearch01.example.local
Email Address []:

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

  3. Ensure a copy of the private key (.key file) is available for use and stored in a safe place. It will be needed later and should be protected.

  4. Submit the CSR to the certificate authority to start the process to get the certificate.

Generating a Client Certificate

Prerequisites

  • Common Name (can be any name, but descriptive is best) (e.g., os.admin, shinydocs-search, shinydocs-control-center, etc.)

  • Country Code (e.g., CA for Canada, US for the United States of America)

  • State or Province (e.g., Ontario or New York)

  • Locality Name or City (e.g., Kitchener or Buffalo)

  • Organization Name (e.g., Shinydocs Corporation or Example Inc)

  • Organization Unit (e.g., Information Technology)

Generating the Certificate Signing Request (CSR)

  1. From a command prompt, execute the following command to generate a key and certificate signing request, substituting the values from above in the command line when requested by the command prompt.

    CODE 
    openssl req -newkey rsa:4096 -keyout <commonname>.key -out <commonname>.csr -noenc

    For example:

    CODE 
    openssl req -newkey rsa:4096 -keyout os.admin.key -out os.admin.csr -noenc

  2. The execution of the command should look something like this

    CODE 
    openssl req -newkey rsa:4096 -keyout os.admin.key -out os.admin.csr -noenc
.+.....+...+.............+..+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*.+.....+......+..................+....+...+...+.........+......+.....+.+...+...........+.......+...+............+..+..........+..+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*.+...+......+.+......+.....+...............+.............+.........+.....+.......+......+..+......+.+........+......................+.....+...................+......+........+......+.......+........................+...............+.....+...+............+................+..+............+...+......+.+...+......+.........+.....................+............+..+...+..................+......+.+.........+.....+..........+...+......+..+.........+....+..............+......+............+...+.+...+.................+...+.......+...+......+.........+...+..+............+..........+...............+.....+......+.........+....+.........+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
......+......+....+.....+.......+.....+....+...+.....+...............+.......+...+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*.+......+..+.+.....+....+...+..+.+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++*.+.........+..+.........+..........+...+..............................+.....+.+..+...+....+.....+......+.+......+..+.............+..+......+.+.....+.........+.+.....................+..+.+...............+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [XX]:CA
State or Province Name (full name) []:Ontario
Locality Name (eg, city) [Default City]:Kitchener
Organization Name (eg, company) [Default Company Ltd]:Shinydocs Corporation
Organizational Unit Name (eg, section) []:Information Technology
Common Name (eg, your name or your server's hostname) []:os.admin
Email Address []:

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

  3. Ensure a copy of the private key (.key file) is available for use and stored in a safe place. It will be needed later and should be protected.

  4. Submit the CSR to the certificate authority to start the process to get the certificate.

OpenSearch Configuration

Once the certificate from the signing authority is obtained, it is time to configure OpenSearch to use it.

Prerequisites

  • Root certificate from the Certificate Authority in PEM (Base64 Ascii) format.

  • The certificate for the OpenSearch host is obtained above.

  • The private key is generated when creating the certificate signing request.

  • The certificate for the OpenSearch admin is obtained above.

  • The admin private key is generated when creating the certificate signing request.

  • The distinguished name of the admin certificate (e.g., CN=os.admin,OU=Information Technology,O=Shinydocs Corporation,L=Kitchener,ST=Ontario,C=CA)

    CODE 
    # obtain the dn of the admin certifiate using the command 
openssl x509 -subject -nameopt RFC2253 -noout -in <admin-cert>

    For example:

    CODE 
    openssl x509 -subject -nameopt RFC2253 -noout -in os.admin.pem

# which outputs: 
subject=CN=os.admin,OU=Information Technology,O=Shinydocs Corporation,L=Kitchener,ST=Ontario,C=CA

#copy the whole line except for the `subject=` prefix
CN=os.admin,OU=Information Technology,O=Shinydocs Corporation,L=Kitchener,ST=Ontario,C=CA

Configuration

  1. Place the certificates and keys from above into the OpenSearch config directory. (Note: It is OPTIONAL to create a new sub-directory under the opensearch/config directory and move the generated certificates and keys to it; however, it must be a child directory of that config directory)

  2. Edit the opensearch.yml file in the OpenSearch config directory and ensure the following settings are specified. (Note: all the certificate paths are relative from the config directory)

    CODE 
    plugins.security.ssl.transport.pemcert_filepath: <host-certificate-file-path>
plugins.security.ssl.transport.pemkey_filepath: <host-certificate-key-file-path>
plugins.security.ssl.transport.pemtrustedcas_filepath: <root certificate-file-path>
plugins.security.ssl.transport.enforce_hostname_verification: true
plugins.security.ssl.http.enabled: true
plugins.security.ssl.http.pemcert_filepath: <host-certificate-file-path>
plugins.security.ssl.http.pemkey_filepath: <host-certificate-key-file-path>
plugins.security.ssl.http.pemtrustedcas_filepath: <root certificate-file-path>
plugins.security.ssl.http.enabled_protocols: 
  - 'TLSv1.2'
  - 'TLSv1.3'
plugins.security.allow_unsafe_democertificates: false
plugins.security.allow_default_init_securityindex: true
plugins.security.authcz.admin_dn: 
  - CN=<full Distinguished Name of the admin certificate>

plugins.security.audit.type: internal_opensearch
plugins.security.enable_snapshot_restore_privilege: true
plugins.security.check_snapshot_restore_write_privileges: true
plugins.security.restapi.roles_enabled: ["all_access", "security_rest_api_access"]
plugins.security.system_indices.enabled: true
plugins.security.system_indices.indices: [".plugins-ml-config", ".plugins-ml-connector", ".plugins-ml-model-group", ".plugins-ml-model", ".plugins-ml-task", ".opendistro-alerting-config", ".opendistro-alerting-alert*", ".opendistro-anomaly-results*", ".opendistro-anomaly-detector*", ".opendistro-anomaly-checkpoints", ".opendistro-anomaly-detection-state", ".opendistro-reports-*", ".opensearch-notifications-*", ".opensearch-notebooks", ".opensearch-observability", ".ql-datasources", ".opendistro-asynchronous-search-response*", ".replication-metadata-store", ".opensearch-knn-models"]
node.max_local_storage_nodes: 3

    For example:

    CODE 
    plugins.security.ssl.transport.pemcert_filepath: opensearch01.pem
plugins.security.ssl.transport.pemkey_filepath: opensearch.key
plugins.security.ssl.transport.pemtrustedcas_filepath: root-ca.pem
plugins.security.ssl.transport.enforce_hostname_verification: true
plugins.security.ssl.http.enabled: true
plugins.security.ssl.http.pemcert_filepath: opensearch01.pem
plugins.security.ssl.http.pemkey_filepath: opensearch01.key
plugins.security.ssl.http.pemtrustedcas_filepath: root-ca.pem 
plugins.security.ssl.http.enabled_protocols: 
  - 'TLSv1.2'
  - 'TLSv1.3'
plugins.security.allow_unsafe_democertificates: false
plugins.security.allow_default_init_securityindex: true
plugins.security.authcz.admin_dn: 
  - CN=os.admin,OU=Information Technology,O=Shinydocs Corporation,L=Kitchener,ST=Ontario,C=CA

plugins.security.audit.type: internal_opensearch
plugins.security.enable_snapshot_restore_privilege: true
plugins.security.check_snapshot_restore_write_privileges: true
plugins.security.restapi.roles_enabled: ["all_access", "security_rest_api_access"]
plugins.security.system_indices.enabled: true
plugins.security.system_indices.indices: [".plugins-ml-config", ".plugins-ml-connector", ".plugins-ml-model-group", ".plugins-ml-model", ".plugins-ml-task", ".opendistro-alerting-config", ".opendistro-alerting-alert*", ".opendistro-anomaly-results*", ".opendistro-anomaly-detector*", ".opendistro-anomaly-checkpoints", ".opendistro-anomaly-detection-state", ".opendistro-reports-*", ".opensearch-notifications-*", ".opensearch-notebooks", ".opensearch-observability", ".ql-datasources", ".opendistro-asynchronous-search-response*", ".replication-metadata-store", ".opensearch-knn-models"]
node.max_local_storage_nodes:

  3. Restart the OpenSearch service.

  4. Open a browser and go to https://hostname:9200.

  5. The connection should be considered secure, and the user should be prompted for authentication.

OpenSearch Dashboards Configuration

Once the certificate from the signing authority is obtained, it is time to configure OpenSearch Dashboards to use the certificate.

Prerequisites

  • Root certificate from the Certificate Authority in PEM (Base64 Ascii) format.

  • The certificate for the OpenSearch Dashboards host is obtained above.

  • The private key is generated when creating the certificate signing request.

  • A decision about using a username / password or a certificate-based authentication to connect to OpenSearch.

  • If using username / password:

    • Credentials to connect Dashboards to OpenSearch (username: kibanaserver, password is either configured or the default one kibanaserver). If using the default, it is a good idea to change it!

  • If using certificate authentication:

    • The client certificate for kibanaserver

    • The client's private key for the kibanaserver

Configuration

  1. Place the certificates and keys from above in a location Opensearch Dashboards can access. Unlike OpenSearch above, it does not need to reside in the OpenSearch Dashboards opensearch-dashboards/config directory.

  2. Edit the opensearch_dashboards.yml file in the OpenSearch config directory and ensure the following settings are in the file. (Note: all the certificate paths must be absolute paths, and must use \\ instead of \ if running on Windows. Otherwise, a Unix-style slash / is fine).

  3. Based on the required authentication type, add the following configurations:

    • For username / password authentication

      CODE 
      opensearch.hosts: [https://<opensearch-host-name>:9200]
opensearch.ssl.verificationMode: full
opensearch.requestHeadersAllowlist: [authorization, securitytenant]

opensearch_security.multitenancy.enabled: false
opensearch_security.readonly_mode.roles: [kibana_read_only]
opensearch_security.cookie.secure: true

opensearch.username: kibanaserver
opensearch.password: <password of kibanaserver user>

server.ssl.enabled: true
server.ssl.certificate: "<path to the host certificate from above>"
server.ssl.key: "<path to the host private key from above>"
opensearch.ssl.certificateAuthorities: [ "<path to the root certificate from above>" ]

    • For certificate-based authentication

      CODE 
      opensearch.hosts: [https://<opensearch-host-name>:9200]
opensearch.ssl.verificationMode: full
opensearch.requestHeadersAllowlist: [authorization, securitytenant]

opensearch_security.multitenancy.enabled: false
opensearch_security.readonly_mode.roles: [kibana_read_only]
opensearch_security.cookie.secure: true

server.ssl.enabled: true
server.ssl.certificate: "<path to the host certificate from above>"
server.ssl.key: "<path to the host private key from above>"
opensearch.ssl.certificateAuthorities: [ "<path to the root certificate from above>" ]
opensearch.ssl.certificate: "<path to the kibanaserver client certificate>"
opensearch.ssl.key: "<path to the kibanserver private key>"

  4. Restart the Dashboards Service, and connect to the system at https://<dashboards-host-name>:5601. Now, a login screen should appear when visiting the Dashboards link.

Control Center Configuration

Once the certificate from the signing authority is obtained, it is time to configure the Control Center to use it.

Prerequisites

  • The certificate for the Control Center host is obtained above.

  • The private key is generated when creating the certificate signing request.

Configuration

  1. In order for Control Center’s web server to use a certificate, it needs to be imported into the Local Computer Certificates Personal Store on the Windows system.

  2. To do this, the certificate and key must be combined into a PKCS12 store using the command below (Note: an export password can be provided or leave it blank. In case an export password is provided, it will be required in the next step):

    CODE 
    openssl pkcs12 -export -out <hostname>.pfx -inkey <hostname>.key -in <hostname>.cer

    For example:

    CODE 
     openssl pkcs12 -export -out controlcenter.pfx -inkey controlcenter.key -in controlcenter.cer

  3. On the host that is running Control Center, double-click the .pfx file created by the command above to start the certificate import wizard.

    1. Select Local Machine for the certificate Store Location

    2. Click Next

    3. Confirm the Path to the file and click Next

    4. Enter the export password if one was specified above.

    5. Mark the key as exportable

    6. Click Next

    7. Click the radio button Place all certificates in the following store

    8. Click Browse

    9. In the popup window, select Personal

    10. Click Next

    11. Click Finish

    12. An import success message box appears.

  4. When running the Shinydocs Control Center service as a user other than the Local system, user permissions need to be granted to access the private key:

    1. Open Manage Computer Certificates from the Start menu.

    2. Open the Personal Store

    3. Open the Certificates Store

    4. Select the certificate that is being used.

    5. Right-click the certificate, select All Tasks → Manage Private Keys

    6. Add the service account to the ACLs with Read permission.

  5. Edit the appsettings.Production.json in the Control Center directory to replace the subject entry with the subject of the issued certificate.
    Old Version

    CODE 
    {
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://*:5000"
      },
      "HttpsInlineCertAndKeyFile": {
        "Url": "https://*:5001",
        "Certificate": {
          "Subject": "localhost.localdomain",
          "Store": "My",
          "Location": "LocalMachine",
          "AllowInvalid": true
        }
      }
    }
  }

     

    New Version (Subject is controlcenter.example.local)

    CODE 
    {
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://*:5000"
      },
      "HttpsInlineCertAndKeyFile": {
        "Url": "https://*:5001",
        "Certificate": {
          "Subject": "controlcenter.example.local",
          "Store": "My",
          "Location": "LocalMachine",
          "AllowInvalid": true
        }
      }
    }
  }

Enterprise Search Configuration

Once the certificate from the signing authority is obtained, it is time to configure Enterprise Search to use it.

Prerequisites

  • The certificate for the Enterprise Search host is obtained above.

  • The private key is generated when creating the certificate signing request.

Configuration

  1. In order for the Enterprise Search’s web server to use a certificate, it needs to be imported into the Local Computer Certificates Personal Store on the Windows system.

  2. To do this, the certificate and key must be combined into a PKCS12 store using the command below, note you can provide an export password, or leave it blank. If you provide a password, you will need it in the next step.

    CODE 
    openssl pkcs12 -export -out <hostname>.pfx -inkey <hostname>.key -in <hostname>.cer

    For example:

    CODE 
    openssl pkcs12 -export -out search.pfx -inkey search.key -in search.cer

  3. On the host that is running Control Center, double-click the .pfx file created by the command above to start the certificate import wizard.

    1. Select Local Machine for the certificate Store Location

    2. Click Next

    3. Confirm the Path to the file and click Next

    4. Enter a password if you specified one above.

    5. Mark the key as exportable

    6. Click Next

    7. Click the radio button Place all certificates in the following store

    8. Click Browse

    9. In the popup window, select Personal

    10. Click Next

    11. Click Finish

    12. You should see an import success message box.

  4. If you are running the Enterprise Search service as a user other than the Local system, user permissions need to be granted to access the private key:

    1. Open Manage Computer Certificates from the Start menu.

    2. Open the Personal Store

    3. Open the Certificates Store

    4. Select the certificate that is being used.

    5. Right click the certificate, select All Tasks → Manage Private Keys

    6. Add the service account to the ACLs with Read permission.

  5. Edit the appsettings.Production.json in the Enterprise Search directory to replace the subject entry with the subject of the issued certificate.
    Old Version

    CODE 
    {
  "Kestrel": {
    "Endpoints": {
      "Https": {
        "Url": "https://localhost:9702",
        "Certificate": {
          "Subject": "localhost.localdomain",
          "Store": "My",
          "Location": "LocalMachine",
          "AllowInvalid": true
        }
      }
    }
  }
}

     

    New Version (Subject is search.example.local)

    CODE 
    {
  "Kestrel": {
    "Endpoints": {
      "Https": {
        "Url": "https://localhost:9702",
        "Certificate": {
          "Subject": "search.example.local",
          "Store": "My",
          "Location": "LocalMachine",
          "AllowInvalid": true
        }
      }
    }
  }
}
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close