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
orNew York
)Locality Name or City (e.g.,
Kitchener
orBuffalo
)Organization Name (e.g.,
Shinydocs Corporation
orExample Inc
)Organization Unit (e.g.
Information Technology
)Common Name / Fully Qualified Domain Name (e.g.,
opensearch01.example.local
)
Generating the Certificate Signing Request (CSR)
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.
CODEopenssl req -addext "subjectAltName = DNS:<FQDN>,DNS:<hostname>,IP:<IP Address>" -newkey rsa:4096 -keyout <hostname>.key -out <hostname>.csr -noenc
For example:
CODEopenssl req -addext "subjectAltName = DNS:opensearch01.example.local,DNS:opensearch01,IP:10.0.1.15" -newkey rsa:4096 -keyout opensearch01.key -out opensearch01.csr -noenc
The execution of the command should look something like this
CODEopenssl 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 []:
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.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
orNew York
)Locality Name or City (e.g.,
Kitchener
orBuffalo
)Organization Name (e.g.,
Shinydocs Corporation
orExample Inc
)Organization Unit (e.g.,
Information Technology
)
Generating the Certificate Signing Request (CSR)
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.
CODEopenssl req -newkey rsa:4096 -keyout <commonname>.key -out <commonname>.csr -noenc
For example:
CODEopenssl req -newkey rsa:4096 -keyout os.admin.key -out os.admin.csr -noenc
The execution of the command should look something like this
CODEopenssl 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 []:
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.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:
CODEopenssl 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
Place the certificates and keys from above into the OpenSearch
config
directory. (Note: It is OPTIONAL to create a new sub-directory under theopensearch/config
directory and move the generated certificates and keys to it; however, it must be a child directory of thatconfig
directory)Edit the
opensearch.yml
file in the OpenSearchconfig
directory and ensure the following settings are specified. (Note: all the certificate paths are relative from theconfig
directory)CODEplugins.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:
CODEplugins.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:
Restart the OpenSearch service.
Open a browser and go to
https://hostname:9200
.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 onekibanaserver
). 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
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.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).Based on the required authentication type, add the following configurations:
For username / password authentication
CODEopensearch.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
CODEopensearch.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>"
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
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.
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):
CODEopenssl pkcs12 -export -out <hostname>.pfx -inkey <hostname>.key -in <hostname>.cer
For example:
CODEopenssl pkcs12 -export -out controlcenter.pfx -inkey controlcenter.key -in controlcenter.cer
On the host that is running Control Center, double-click the
.pfx
file created by the command above to start the certificate import wizard.Select Local Machine for the certificate Store Location
Click Next
Confirm the Path to the file and click Next
Enter the export password if one was specified above.
Mark the key as exportable
Click Next
Click the radio button Place all certificates in the following store
Click Browse
In the popup window, select Personal
Click Next
Click Finish
An import success message box appears.
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:
Open Manage Computer Certificates from the Start menu.
Open the Personal Store
Open the Certificates Store
Select the certificate that is being used.
Right-click the certificate, select All Tasks → Manage Private Keys
Add the service account to the ACLs with Read permission.
Edit the
appsettings.Production.json
in the Control Center directory to replace the subject entry with the subject of the issued certificate.
Old VersionCODE{ "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
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.
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.
CODEopenssl pkcs12 -export -out <hostname>.pfx -inkey <hostname>.key -in <hostname>.cer
For example:
CODEopenssl pkcs12 -export -out search.pfx -inkey search.key -in search.cer
On the host that is running Control Center, double-click the
.pfx
file created by the command above to start the certificate import wizard.Select Local Machine for the certificate Store Location
Click Next
Confirm the Path to the file and click Next
Enter a password if you specified one above.
Mark the key as exportable
Click Next
Click the radio button Place all certificates in the following store
Click Browse
In the popup window, select Personal
Click Next
Click Finish
You should see an import success message box.
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:
Open Manage Computer Certificates from the Start menu.
Open the Personal Store
Open the Certificates Store
Select the certificate that is being used.
Right click the certificate, select All Tasks → Manage Private Keys
Add the service account to the ACLs with Read permission.
Edit the
appsettings.Production.json
in the Enterprise Search directory to replace the subject entry with the subject of the issued certificate.
Old VersionCODE{ "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 } } } } }