DNS & Certificate Installation

Introduction

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

To access ScaleOut Active Caching deployed across multiple hosts, use a load balancer in front of the hosts and configure a DNS record that points to the load balancer’s front-end public IP address.

You can also configure Active Caching to use a DNS-based URL when running on a single host. This simplifies access to the service from remote machines and allows integration with external AI agents, which require SSL certificates issued by trusted authorities. See the Configuring Claude Desktop section for more information on this topic.

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 2 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 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 ScaleOut Active Caching Web Console service, the default certificate’s folder location is:

On Windows:

C:\Program Files\ScaleOut_Software\StateServer\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

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\StateServer\ActiveCachingWebUI\WebService.Api\certs

  • C:\Program Files\ScaleOut_Software\StateServer\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 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.

While these instructions work for Google Chrome, they might not be sufficient for Mozilla Firefox. If you still see Not Secure in the address bar after following these steps and restarting Firefox, you might need to follow the Firefox certificate exception instructions.

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 the “https://activecaching.mycompany.com” DNS name and the messaging service uses “https://messaging.activecaching.mycompany.com”.

Configuring the ScaleOut Active Caching Web Console service

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

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

    For example:

  • Open the C:\Program Files\ScaleOut_Software\StateServer\ActiveCachingWebUI\WebService.Api\appsettings.windows.json file. - Locate the “Kestrel” → “Endpoints” → “HttpsAC” → “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\StateServer\ActiveCachingWebUI\WebService.Api\wwwroot\env.js file. - Change the values of the WEB_CONSOLE_URL and AUTH_URL properties to use your corresponding DNS and port values. If WEB_API_URL is present, its value should match WEB_CONSOLE_URL. For example:

Configuring the ScaleOut Active Caching Messaging service

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

  • Open the C:\Program Files\ScaleOut_Software\StateServer\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-msg