Share via

Enable HTTPS support for Microsoft Connected Cache on Linux

This article provides step-by-step instructions for enabling HTTPS support on Microsoft Connected Cache for Enterprise nodes running on a Linux host machine.

The setup process requires generating a Certificate Signing Request (CSR) on your host machine, signing the CSR using enterprise or public PKI, and then importing back to the host machine.

Prerequisites

Before setting up HTTPS functionality, ensure the following requirements are met:

  • Cache node is on the GA software version

    1. Open Azure portal and navigate to the Connected Cache for Enterprise resource that houses your cache nodes.
    2. Under Cache Node Management, find the cache node you wish to enable HTTPS on.
    3. Verify that the node is on the GA version - should show "Yes" or "N/A" in the Migrated column.
    4. If not on GA version ("No" in the Migrated column), select the cache node, navigate to the Deployment tab, and follow the instructions to redeploy Connected Cache.

  • Access to a Certificate Authority (CA)

    You'll need access to either your enterprise PKI or a public CA. If using enterprise PKI, check your organization's requirements for submitting a CSR to CA.

  • Document client connection methods

    Note the IP address or hostname (FQDN) that your clients use to connect to your Connected Cache server. This value will be used as a Subject Alternative Name (SAN) input during the process of generating a CSR.

  • Ensure port 443 availability

    In order to establish an HTTPS connection with Connected Cache, port 443 needs to be available on your host machine. Run the following command to check:

    sudo ss -tulpn | grep :443
    Output Example Meaning
    tcp LISTEN 0 128 0.0.0.0:443 0.0.0.0:* users:(("nginx",pid=1234,fd=6)) Port 443 is open and listening for incoming connections (in this case by nginx). You need to stop the conflicting service before Connected Cache can use port 443.
    No output Port 443 isn't in use or not listening. Proceed with HTTPS setup.

  • Verify firewall configuration

    If your firewall or corporate proxy intercepts HTTPS traffic to your Connected Cache server (for example, via TLS inspection), certificate validation will always fail regardless of certificate configuration.

For more information on any of the prerequites, see the HTTPS on Linux reference page.

Generate a Certificate Signing Request (CSR)

Important

Each cache node needs its own CSR/certificate (cannot share):

  • Use consistent naming: mcc-node1.company.com, mcc-node2.company.com, etc.
  • Document which certificate belongs to which node
  • Wildcard certificates will not work. The CSR/certificate used for HTTPS connection to Connected Cache is uniquely tied to each cache node for security purposes.

  1. Open a terminal and navigate to the folder containing the extracted deployment package.

  2. Add execute permissions to the CSR generation script:

    sudo chmod +x ./generateCsr.sh

  3. Configure the parameters for generateCsr.sh and run the script with your specified values.

    Basic Syntax

    ./generateCsr.sh [Required Parameters] [Subject Parameters] [SAN Parameters]

    Required Parameters

    Parameter Type Description
    -algo String Certificate algorithm: RSA, EC, ED25519, or ED448
    -keySizeOrCurve String For RSA: key size (2048, 3072, 4096). For EC: curve name (prime256v1, secp384r1)
    -csrName String Name for the generated CSR file

    Subject Parameters

    Parameter Required Description Example
    -subjectCommonName Yes Common name for the certificate "localhost", "example.com"
    -subjectCountry No Two-letter country code "US", "CA", "GB"
    -subjectState No State or province "WA", "TX", "Ontario"
    -subjectOrg No Organization name "MyCompany", "ACME Corp"

    Warning

    The Subject Alternative Name (SAN) configuration is critical for certificate validation. Your certificate must match exactly how clients connect to your Connected Cache, otherwise the clients bypass the cache node.

    For example, if your clients connect via IP address 192.168.1.100 but your certificate only has -sanDns "server.local", certificate validation fails.

    SAN Parameters (at least one required)

    Parameter Description Example
    -sanDns DNS names (comma-separated) "localhost,example.com,api.example.com"
    -sanIp IP addresses (comma-separated) "127.0.0.1,192.168.1.100"
    -sanUri URIs (comma-separated) "https://example.com,http://localhost"
    -sanEmail Email addresses (comma-separated) "admin@example.com,user@domain.com"
    -sanRid Registered IDs (comma-separated)
    -sanDirName Directory names (comma-separated)
    -sanOtherName Other names (comma-separated)

    For more detail and scenario-based examples on CSR script parameters, see the HTTPS on Linux reference page.

  4. Validate that the CSR generation process completed successfully.

    If you encounter errors, locate the timestamped GenerateCsr.log file in the folder specified in the script output. Look for the output line that starts with "You can find logs here: ..."

    • File format: GenerateCsr_YYYYMMDD-HHMMSS.log
    • Example: GenerateCsr_20251201_143022.log is a file created December 1, 2025 at 2:30:22 PM

  5. Locate the generated CSR file in your Certificates folder on your host machine and transfer it if necessary.

    The location of the Certificates folder is specified in the script output, starting with "CSR file created at: ...". The directory ends with (...\Certificates\certs).

Sign the CSR

  1. Select a public or enterprise Certificate Authority (CA) to sign the CSR.

    Important

    The CA signature must match a root certificate in the client's trusted root store.

    Most customers utilize their enterprise PKI infrastructure for signing their CSR. If you need to use a public CA, consider these resources:

  2. Submit the CSR to your chosen CA and save the signed certificate.

    Your signed certificate must be in .crt format with X.509 encoding. If your CA provides other formats, check the HTTPS on Linux reference page on how to convert to .crt format.

    Note

    Connected Cache does not currently support password-protected formats (.pfx, .p12, .p7b). Support for these will be added soon as part of our certificate automation roadmap.

  3. Verify that signed certificate is in the correct format.

    Confirm PEM encoding:

    grep "BEGIN CERTIFICATE" xxxx.crt

    Expected successful output:

    -----BEGIN CERTIFICATE-----

  4. Move your signed certificate to the Certificates folder on your Linux host machine.

    This will be the same folder where you initially found your CSR after it generated.

    Caution

    Do not share private keys, Connected Cache only requires the signed certificate.

Import signed TLS certificate

  1. Open a terminal and navigate to the location of the Connected Cache installer.

  2. Add execute permissions to the certificate import script:

    sudo chmod +x ./importCert.sh

  3. Configure the parameters for importCert.sh and run the script with your specificied values.

    Basic Syntax

    ./importCert.sh [Required Parameters]

    Required Parameters

    Parameter Type Description
    -certName String Complete filename of your signed TLS certificate (with or without .crt extension)

    Example

    ./importCert.sh -certName "myTlsCert.crt"

  4. Validate that the import process completed successfully.

    If you encounter errors, locate the timestamped ImportCert.log file in the folder specified in the script output. Look for the output line that starts with "You can find logs here: ..."

    • File format: ImportCert_YYYYMMDD-HHMMSS.log
    • Example: ImportCert_20251201_143022.log is a file created December 1, 2025 at 2:30:22 PM

For instructions on how to further validate the certificate import, see the HTTPS on Linux validation page.

Disable HTTPS support

If you need to revert your Connected Cache to HTTP-only communication, follow these steps. This process won't delete anything in the Certificates folder - CSR files, certificates, or logs.

  1. On your Linux host, open a terminal and navigate to the folder containing the extracted deployment package.

  2. Add execute permissions to the TLS disable script:

    sudo chmod +x ./disableTls.sh

  3. Run the disable script (no parameters required):

    ./disableTls.sh

  4. Validate that the disable process completed successfully.

  5. After HTTPS is disabled, HTTP requests should work while HTTPS requests should fail. See the HTTPS on Linux validation page for instructions on how to test this.

Next steps

  • Last updated on