Certificate Installation

Introduction

By default, ScaleOut Active Caching software is configured to run on a single host by using the ‘localhost’ name, TCP ports 7701, 8801, 9901, and a self-signed ScaleOut certificate. This guide provides a stepwise approach to installing a custom certificate, configuring custom DNS names, and managing TCP ports across both Windows and Linux environments.

Certificates

What is a Certificate?

A certificate is a digital document that authenticates the identity of a website or a service and enables encrypted connections. Certificates follow the X.509 standard and are issued by a Certificate Authority (CA).

Types of Certificates

  • Self-Signed Certificate: generated and signed by you, suitable for internal testing.

  • CA-Signed Certificate: issued by a trusted third-party (e.g., Sectigo, DigiCert, GlobalSign, etc.), essential for production.

Securing ScaleOut Active Caching endpoints

ScaleOut Active Caching installs 3 middleware web services running on Windows as Windows services and on Linux as system daemons.

  • ScaleOut StateServer Active Caching Web Console

  • ScaleOut StateServer Active Caching Identity

  • ScaleOut StateServer Active Caching Messaging REST Service

ScaleOut’s default configuration uses the same self-signed certificate for all these services. By default, it is located in the /certs subfolder of the main installation folder for each of these services. For example, for the Active Caching Web Console service, the default certificate’s folder location is:

On Windows:

C:\Program Files\ScaleOut_Software\ActiveCachingWebUI\WebService.Api\certs

On Linux:

/usr/lib/soss-ac/soss-ac-web/certs

The appsettings.json configuration file for each of these services specifies this subfolder as the certificate location. The certificate’s password is stored in the SOSS_AC_CERT_PASSWORD environment variable. On Windows, it is a part of the system environment variables list; for Linux, it is specified in the following system service configuration files:

  • /usr/lib/systemd/system/soss-ac-web.service

  • /usr/lib/systemd/system/soss-ac-msg.service

  • /usr/lib/systemd/system/soss-ac-identity.service

Use your own self-signed certificate and the ‘localhost’ DNS name.

  1. Copy your self-signed certificate (*.pfx) to the following folders:

  • C:\Program Files\ScaleOut_Software\ActiveCachingWebUI\WebService.Api\certs

  • C:\Program Files\ScaleOut_Software\ActiveCachingWebUI\IdentityServer\certs

  • C:\Program Files\ScaleOut_Software\ActiveCachingWebUI\Messaging.Api\certs

  1. Update the certificate password stored in the SOSS_AC_CERT_PASSWORD system environment variable.

  2. Restart the following ScaleOut Windows services:

  • ScaleOut StateServer Active Caching Web Console

  • ScaleOut StateServer Active Caching Identity

  • ScaleOut StateServer Messaging REST Service

  1. If you want to suppress a browser’s warning that it does not trust this self-signed certificate, you can follow the steps below:

  • Right-click on the public key certificate file (either .crt, .cer, .der, or .pub) and choose Install Certificate. The Certificate Import Wizard will appear.

  • Select the Local Machine store location and click Next.

  • Select Place all certificates in the following store and click on Browse.

  • Select the Trusted Root Certification Authorities store and click Ok.

  • Click Next and then Finish to complete the installation of the public key certificate.

Use a certificate issued by a trusted certificate authority (CA)

  • Install a new certificate in the Windows Local Computer certificate store:

    • Right-click on the .pfx certificate file and choose Install Certificate. The Certificate Import Wizard will appear.

    • Select the Local Machine store location and click Next.

    • Confirm certificate location and click Next.

    • Type the password for the private key and click Next.

    • Leave the Automatically select the certificate store option and click Next.

    • Click Next and then Finish to complete the installation of the certificate.

  • Add Read permission for the Network Service account to the certificate’s private key so ScaleOut Active Caching services can read it. You can do it manually or by running a PowerShell script.

    • Add permission manually:

      • Find the certificate by opening MMC → Certificates (Computer account) → Personal → Certificates.

      • Locate your TLS certificate by subject name or thumbprint.

      • Right-click the certificate → All Tasks → Manage Private Keys…

      • Add the NT AUTHORITY\NETWORK SERVICE account and grant Read permission.

    • Alternatively, you can add permission by running the PowerShell script:

      $thumbprint = "YOUR_CERT_THUMBPRINT"
$cert = Get-ChildItem -Path Cert:\\LocalMachine\\My | Where-Object Thumbprint -eq $thumbprint
$cert | Format-List Subject,HasPrivateKey,Thumbprint

# Get the path to the private key
$keyName = $cert.PrivateKey.CspKeyContainerInfo.UniqueKeyContainerName
$keyPath = "$env:ProgramData\\Microsoft\\Crypto\\RSA\\MachineKeys\\$keyName"

# Add Network Service with Read permission
icacls $keyPath /grant "NT AUTHORITY\\NETWORK SERVICE:R"

  • Change the ScaleOut Active Caching configuration files to use a new certificate, custom DNS, and port values.

Note

As an example, we assume here that the web console service uses port 443, the caching identity service - port 444, and the messaging service - port 446 (the port 443 is not specified in the corresponding URLs below since it is a default SSL port).

Configuring the Active Caching Web Console service

  • Open the C:\Program Files\ScaleOut_Software\ActiveCachingWebUI\WebService.Api\appsettings.json file.

    • Locate the “Kestrel” → “Endpoints” → “Https” section and change the “Url” property value to use your corresponding DNS and port values. For example: “Url”: “https://activecaching.mycompany.com”.

    • Locate the “Security” → “Authentication” section and change the AuthURL and ValidIssuer to use your corresponding DNS and port values.

    For example:

    • Locate the “Security” section and change the CorsOrigins property value to use your corresponding DNS and port values. For example:

  • Open the C:\Program Files\ScaleOut_Software\ActiveCachingWebUI\WebService.Api\appsettings.windows.json file. - Locate the “Kestrel” → “Endpoints” → “Https” → “Certificate” section.

    • Set the CertSource property to “Store”.

    • Set the CertThumbprint property to the thumbprint value of your certificate.

  • Open the C:\Program Files\ScaleOut_Software\ActiveCachingWebUI\WebService.Api\wwwroot\env.js file. - Change the WEB_CONSOLE_URL and AUTH_URL properties’ values to use your corresponding DNS and port values. For example:

Configuring the Active Caching Identity service

  • Open the C:\Program Files\ScaleOut_Software\ActiveCachingWebUI\IdentityServer\appsettings.json file.

  • Open the C:\Program Files\ScaleOut_Software\ActiveCachingWebUI\IdentityServer\appsettings.windows.json file.

    • Locate the “Kestrel”→”Endpoints”→”Https”→”Certificate” section.

    • Set the CertSource property to “Store”.

    • Set the CertThumbprint property to the thumbprint value of your certificate.

Configuring the Active Caching Messaging service

  • Open the C:\Program Files\ScaleOut_Software\ActiveCachingWebUI\Messaging.Api\appsettings.json file. - Locate the “Kestrel”→”Endpoints”→”Https” section and change the “Url” property value to use your corresponding DNS and port values. For example:

    • Locate the “Security” section and change the CorsOrigins property value to use your corresponding DNS and port values. For example:

  • Open the C:\Program Files\ScaleOut_Software\ActiveCachingWebUI\Messaging.Api\appsettings.windows.json file.

    • Locate the “Kestrel”→”Endpoints”→”Https”→”Certificate” section.

    • Set the CertSource property to “Store”.

    • Set the CertThumbprint property to the thumbprint value of your certificate.

Restart ScaleOut Active Caching Windows services

  • Restart-Service -Name soss-ac-web

  • Restart-Service -Name soss-ac-identity

  • Restart-Service -Name soss-ac-msg