Skip to content

MetaMiner Server SSL

Turn on TLS for the MetaMiner Server port so that every MetaMiner Client, browser and web app connection is encrypted.

How it works

The MetaMiner Server (MMS) listens on one port, 49714 by default. When you turn on SSL, all traffic on that port uses TLS 1.2 or 1.3: MetaMiner Client connections, the Power BI usage dashboards and Meta Query on the web. Users keep the same server name and port. The MetaMiner Client detects SSL by itself; it has no SSL setting.

The MMS presents its own certificate without the rest of the chain. Clients must therefore trust the CA that issued the certificate (the issuing or intermediate CA), not only the root CA.

Before you begin

You need Details
A server certificate Issued by your company CA for the MMS host. List every name users type to connect in the Subject Alternative Name: the full name, any short name, and the IP address if anyone uses it
Its private key An RSA key in a PEM file that begins with -----BEGIN PRIVATE KEY----- (PKCS#8). Step 1 shows how to convert other formats
Your CA certificate The CA that issued the server certificate. Every MetaMiner Client must trust it
An open port TCP 49714, or your chosen port, open inbound to the MMS from your users' networks

Run the MetaMiner Administrator (MMA) on the MMS host as a Windows administrator.

Steps

Step 1: Get the certificate files

You need two files: mms-key.pem (the private key) and mms-cert.pem (the certificate).

To create a certificate request with OpenSSL:

Create a key and certificate request
openssl req -new -newkey rsa:2048 -nodes -keyout mms-key.pem -out mms.csr ^
  -subj "/CN=mms.company.com" -addext "subjectAltName=DNS:mms.company.com,DNS:mms"

Send mms.csr to your CA team and ask for a web server certificate in Base-64 (PEM) format. Save the result as mms-cert.pem.

If you received a .pfx file instead, split it into the two files:

Split a .pfx file
openssl pkcs12 -in mms.pfx -nocerts -nodes | openssl pkcs8 -topk8 -nocrypt -out mms-key.pem
openssl pkcs12 -in mms.pfx -clcerts -nokeys | openssl x509 -out mms-cert.pem

If your key begins with -----BEGIN RSA PRIVATE KEY-----, convert it to PKCS#8:

Convert a key to PKCS#8
openssl pkcs8 -topk8 -nocrypt -in old-key.pem -out mms-key.pem

Key password

We recommend an unencrypted PKCS#8 key protected with folder permissions (step 2). If your policy requires a password-protected key, contact Infolytik Support for the supported key encryption format.

TODO: decide whether to publish the password-protected key format

Product team to confirm a key encryption scheme that meets current customer policy before it is documented here.

Step 2: Copy the files to the server

Copy both files to a folder on the MMS host and limit who can read it to administrators and the MetaMiner service account (SYSTEM, unless the service runs under another account):

Create a protected folder for the certificate files
mkdir "C:\Program Files\Infolytik\MetaMiner\server\config\ssl"
icacls "C:\Program Files\Infolytik\MetaMiner\server\config\ssl" /inheritance:r ^
  /grant:r "Administrators:(OI)(CI)F" "SYSTEM:(OI)(CI)R"

Step 3: Turn on SSL in MMA

  1. In MMA, click Preferences > Settings... and open the General page.
  2. Keep Server Port at 49714 unless you need another port.
  3. Click Configure SSL. The Configure SSL for MetaMiner Server dialog opens.
  4. Tick Use SSL.
  5. In Private key file, browse to mms-key.pem.
  6. In Certificate file, browse to mms-cert.pem.
  7. Leave Private key password blank unless your key has a password.
  8. Click OK. MMA checks that the key and certificate belong together, then saves. The key password is stored encrypted.

Image of the Configure SSL for MetaMiner Server dialog with Use SSL ticked and both files selected

../images/security/mma-configure-ssl.png

Using a different port

Type the port in Server Port and click OK on the Settings window. Open the port in the firewall, tell users the new port, and reserve it so Windows does not assign it to another program. Run as administrator while the MetaMiner service is stopped:

netsh int ipv4 add excludedportrange protocol=tcp startport=<port> numberofports=1 store=persistent

Step 4: Restart the MetaMiner service

The change takes effect when the service restarts:

Restart the MetaMiner Server service
net stop metaminer
net start metaminer

You can also restart from MMA with the Start/Stop button.

Step 5: Trust your CA on each client workstation

Follow Client to Server SSL.

Verify

  1. Open server\logs\server.log and look for SSL enabled: true.
  2. From a workstation, check the port: powershell Test-NetConnection mms.company.com -Port 49714. TcpTestSucceeded : True means the firewall is open.
  3. Open the MetaMiner Client and connect as usual. If you connect without a certificate warning, SSL is working.
  4. Open https://mms.company.com:49714/web/pbiusage/ in a browser. The browser shows a secure connection.

Troubleshooting

Failed to validate private key/certificate! when clicking OK

The key is not an RSA PKCS#8 PEM key, or the password is wrong. Convert the key with the command in step 1 and leave the password blank. If you have an EC key, ask for a new certificate with an RSA key.

Public key of the private key does not match the certificate!

The key and certificate do not belong together. Use the key that created the certificate request.

...file is not found at specified location

Check the path. Run MMA on the MMS host itself.

No client can connect after the restart

The service could not read the certificate files. Check server\logs\server.log and the folder permissions, then restart the service.

Certificate warning in the MetaMiner Client

The workstation does not trust your CA yet. Repeat Client to Server SSL on it, and make sure you added the issuing CA. Do not accept the warning.

Maintain the certificate

  • Renew: replace the two files with the new ones under the same names, then restart the service. If the new certificate comes from a different CA, update the client trust stores first.
  • Expiry: MetaMiner does not warn before the certificate expires. Track the expiry date in your certificate inventory.
  • Turn SSL off: clear Use SSL, click OK, and restart the service. Clients switch back automatically.

Next steps