ServicePulse TLS Configuration

ServicePulse can be configured to use HTTPS directly, enabling encrypted connections without relying on a reverse proxy for SSL termination.

Configuration

There are two hosting options for ServiceControl, Container and Windows Service. The container is configured via environment variables, while the Windows Service is configured using command-line arguments. See the Hosting Guide for example usage of these configuration settings, along with Authentication and Forward Headers, in a scenario-based format.

Container

• Container TLS settings

Window Service

Example:

"C:\Program Files (x86)\Particular Software\ServicePulse\ServicePulse.Host.exe" --httpsenabled=true --httpsredirecthttptohttps=false

Security Considerations

Certificate Management

• ServiceControl supports PFX (PKCS#12) certificate files
• Store certificate files securely with appropriate file permissions

HSTS

The HTTP Strict-Transport-Security response header (often abbreviated as HSTS) informs browsers that the host should only be accessed using HTTPS, and that any future attempts to access it using HTTP should automatically be upgraded to HTTPS. Additionally, on future connections to the host, the browser will not allow the user to bypass secure connection errors, such as an invalid certificate. HSTS identifies a host by its domain name only. Its important to read what each of these settings do before enabling them.

HTTP to HTTPS Redirect

The SERVICEPULSE_HTTPS_REDIRECTHTTPTOHTTPS setting is intended for use with a reverse proxy that handles both HTTP and HTTPS traffic. When enabled:

• The redirect uses HTTP 307 (Temporary Redirect) to preserve the request method
• The reverse proxy must forward both HTTP and HTTPS requests to ServicePulse
• ServicePulse will redirect HTTP requests to HTTPS based on the X-Forwarded-Proto header
• Important: You must also set SERVICEPULSE_HTTPS_PORT (or --httpsport= for .NET Framework) to specify the HTTPS port for the redirect URL

Configuration Examples

The following examples show common TLS configurations for different deployment scenarios.

Direct HTTPS with certificate

When ServicePulse handles TLS directly using a PFX certificate:

Container:

servicepulse:
    image: particular/servicepulse:latest
    ports:
      - "9090:9090"
    environment:
      SERVICECONTROL_URL: https://servicecontrol:33333
      MONITORING_URL: https://servicecontrol-monitoring:33633
      SERVICEPULSE_HTTPS_ENABLED: "true"
      SERVICEPULSE_HTTPS_CERTIFICATEPATH: "/usr/share/ParticularSoftware/certificate.pfx"
      SERVICEPULSE_HTTPS_CERTIFICATEPASSWORD: "..."
      SSL_CERT_FILE: "/etc/ssl/certs/ca-bundle.crt"
      ASPNETCORE_URLS: "https://+:9090"
    restart: unless-stopped
    volumes:
      - C:\path\to\servicecontrol\cert.pfx:/usr/share/ParticularSoftware/certificate.pfx
      - C:\path\to\servicecontrol\ca-bundle.crt:/etc/ssl/certs/ca-bundle.crt:ro
    depends_on:
      servicecontrol:
        condition: service_healthy
      servicecontrol-monitoring:
        condition: service_healthy
      rabbitmq:
        condition: service_healthy

SSL_CERT_FILE (CRT): This tells SSL/TLS libraries (including .NET's HttpClient, OpenSSL, and libcurl) the path to a CA (Certificate Authority) certificate bundle file. This bundle contains the public certificates of trusted CAs used to verify the authenticity of SSL/TLS certificates presented by remote servers. This certificate is used to verify HTTPS (trust others).

SERVICEPULSE_HTTPS_CERTIFICATEPATH (PFX): This is a binary archive format that bundles together the private key, public certificate, and certificate chain. This certificate is used to serve HTTPS (prove identity).

Windows Service:

The Windows service uses Windows HttpListener which requires SSL certificate binding at the OS level:

netsh http add sslcert ipport=0.0.0.0:443 certhash={certificate-thumbprint} appid={application-guid}
ServicePulse.Host.exe --httpsenabled=true

Troubleshooting

Certificate not found or access denied

Symptom: The application fails to start with certificate-related errors when using a PFX certificate file.

Cause: The certificate file path is incorrect, the file is not readable, or the password is wrong.

Solutions:

• Verify the certificate path is correct and the file exists
• Check that the certificate file has appropriate permissions
• Confirm the certificate password is correct
• For containers, ensure the volume mount is correct (e.g., -v certificate.pfx:/usr/share/ParticularSoftware/certificate.pfx)

HTTPS redirect not working

Symptom: HTTP requests are not redirected to HTTPS when using a reverse proxy.

Cause: The redirect requires the X-Forwarded-Proto header to detect the original protocol, which may not be processed.

Solutions:

• Verify RedirectHttpToHttps is set to true
• Ensure the HTTPS port setting is configured correctly
• Configure forward headers so the X-Forwarded-Proto header is trusted
• Confirm the reverse proxy is sending the X-Forwarded-Proto header

HSTS header not appearing

Symptom: The Strict-Transport-Security header is not present in responses.

Cause: HSTS headers are only sent over HTTPS connections, or the setting is not enabled.

Solutions:

• Verify EnableHsts is set to true
• Confirm you are accessing via HTTPS (HSTS headers are not sent over HTTP)
• When using a reverse proxy, ensure the request is recognized as HTTPS via X-Forwarded-Proto

Browser shows certificate warning

Symptom: Browser displays "Your connection is not private" or similar certificate warnings.

Cause: The client (browser or another container) doesn't trust the CA that signed the server's certificate.

Solutions:

• Use a certificate from a trusted Certificate Authority for production
• Ensure the certificate's Common Name (CN) or Subject Alternative Name (SAN) matches the hostname
• Check that the certificate has not expired
• Ensure the certificate is in the correct Trusted Root Certificate Authorities store. e.g.,
  • If running in a Windows Service as Local System, the certificate should be in the Local Computer store.
  • If running as yourself, the certificate should be in the Current User store.
• For internal/development use, add the self-signed certificate to the trusted root store
• For containers: Add the CA certificate to the CA bundle and set SSL_CERT_FILE

The remote certificate is invalid according to the validation procedure

Symptom: Service starts but fails when calling other services (e.g., ServiceControl can't reach ServiceControl-Audit) or when validating tokens with Azure AD.

Cause: The CA bundle doesn't contain the CA certificate that signed the remote server's certificate.

Solutions:

• Ensure the CA bundle includes your local CA certificate (e.g., mkcert's rootCA.pem)
• For Azure AD authentication, append the Mozilla CA bundle: curl https://curl.se/ca/cacert.pem >> ca-bundle.crt
• Verify SSL_CERT_FILE environment variable points to the correct path inside the container
• Check the CA bundle is mounted correctly

The certificate doesn't match the hostname

Symptom: Browser or client rejects the certificate with a hostname mismatch error

Cause: The certificate's Subject Alternative Names (SANs) don't include the hostname being used to connect.

Solutions:

• Regenerate the certificate with all required hostnames
• Include both the Docker service name (for container-to-container) and localhost (for host access)

Health checks fail with certificate errors

Symptom: Container health check reports unhealthy, logs show SSL errors from the health check command.

Cause: The health check binary inside the container doesn't trust the certificate.

Solutions:

• Ensure SSL_CERT_FILE is set so the health check process can find the CA bundle
• Check the health check URL uses the correct protocol: https:// not http://
• Verify the certificate includes localhost in its SANs (health checks run inside the container)

SSL certificate binding fails (Windows Service)

Symptom: ServicePulse fails to start with HTTPS enabled, or netsh http add sslcert returns an error.

Cause: The certificate is not properly bound to the port, the certificate is missing from the certificate store, or the thumbprint/appid is incorrect.

Solutions:

• Verify the certificate is installed in the Windows certificate store (Local Computer > Personal)
• Check the certificate thumbprint is correct (no spaces, lowercase)
• Ensure the port is not already bound to another certificate: netsh http show sslcert
• Remove existing binding before adding a new one: netsh http delete sslcert ipport=0.0.0.0:443
• Run the command prompt as Administrator