# ServicePulse TLS Configuration


> [!NOTE]
> This page is **not** relevant if:
> - [integrated ServicePulse](/servicecontrol/servicecontrol-instances/integrated-servicepulse.md) is used. Integrated ServicePulse will use [the TLS configuration of the ServiceControl Error instance](/servicecontrol/security/configuration/tls.md) that hosts it.
> - the [ServicePulse static files have been extracted](/servicepulse/install-servicepulse-in-iis.md), and is being hosted in anything other than the [Container](/servicepulse/containerization/index.md) or [Windows Service](/servicepulse/installation.md) hosting options provided. If using [authentication](/servicepulse/security/configuration/authentication.md), it is recommended to use TLS encryption.

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 ServicePulse: [Container](/servicepulse/containerization/index.md) and [Windows Service](/servicepulse/installation.md). The container is configured via environment variables, while the Windows Service is configured using command-line arguments. See the [Hosting Guide](../hosting-guide.md) for example usage of these configuration settings, along with [Authentication](authentication.md) and [Forward Headers](forward-headers.md), in a scenario-based format.

### Container

- [Container TLS settings](/servicepulse/containerization/index.md#settings-tls)

### Window Service

| Command-Line Argument           | Default    | Description                                                    |
|---------------------------------|------------|----------------------------------------------------------------|
| `--httpsenabled=`               | `false`    | Enable HTTPS with Kestrel                                      |
| `--httpsredirecthttptohttps=`   | `false`    | Redirect HTTP requests to HTTPS                                |
| `--httpsport=`                  | (none)     | HTTPS port for redirect (required for reverse proxy scenarios) |
| `--httpsenablehsts=`            | `false`    | Enable HTTP Strict Transport Security                          |
| `--httpshstsmaxageseconds=`     | `31536000` | HSTS max-age in seconds (default: 1 year)                      |
| `--httpshstsincludesubdomains=` | `false`    | Include subdomains in HSTS policy                              |

> [!NOTE]
> The windows service uses Windows HttpListener which requires [SSL certificate binding at the OS level using `netsh`](https://learn.microsoft.com/en-us/dotnet/framework/wcf/feature-details/how-to-configure-a-port-with-an-ssl-certificate). The certificate is not configured in the application itself.

Example:

```cmd
"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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/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

> [!NOTE]
> When running ServicePulse directly without a reverse proxy, the application only listens on a single protocol (HTTP or HTTPS).

## 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:**

> [!NOTE]
> The following is a docker compose snippet. For full examples, see the [Platform Container Examples repository](https://github.com/Particular/PlatformContainerExamples).

```bash
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).

> [!NOTE]
> When containers communicate with each other over HTTPS, they use the Docker service names (like `servicecontrol`, `servicecontrol-audit`) as hostnames, and TLS validation will fail if the certificate doesn't include these names in its Subject Alternative Names (SANs).

**Windows Service:**

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

```cmd
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](forward-headers.md) 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