Document ServiceControl / ServicePulse support for authentication and SSL/TLS

menu/menu.yaml

@@ -1481,6 +1481,16 @@
       Url: servicecontrol/upgrades/2to3
     - Title: Version 1 to 2
       Url: servicecontrol/upgrades/1to2
+  - Title: Security
+    Articles:
+    - Title: ServiceControl security
+      Url: servicecontrol/security
+    - Title: Hosting guide
+      Url: servicecontrol/security/hosting-guide
+    - Title: Configuration
+      Url: servicecontrol/security/configuration
+    - Title: Microsoft Entra ID authentication
+      Url: servicecontrol/security/entra-id-authentication
   - Title: Planning
     Articles:
     - Title: Optimizing for use in different environments

servicecontrol/audit-instances/configuration.md

@@ -153,6 +153,373 @@ Run [ServiceControl audit instance in maintenance mode](/servicecontrol/ravendb/
 | --- | --- |
 | boolean | `False` |
 
+## Authentication
+
+These settings configure [authentication using OAuth 2.0 and OpenID Connect](/servicecontrol/security/).
+
+### ServiceControl.Audit/Authentication.Enabled
+
+_Added in version 6.9.0_
+
+Enables or disables authentication.
+
+| Context | Name |
+| --- | --- |
+| **Environment variable** | `SERVICECONTROL_AUDIT_AUTHENTICATION_ENABLED` |
+| **App config key** | `ServiceControl.Audit/Authentication.Enabled` |
+| **SCMU field** | N/A |
+
+| Type | Default value |
+| --- | --- |
+| bool | `false` |
+
+### ServiceControl.Audit/Authentication.Authority
+
+_Added in version 6.9.0_
+
+The URL of the OpenID Connect authority (identity provider) used to authenticate tokens.
+
+| Context | Name |
+| --- | --- |
+| **Environment variable** | `SERVICECONTROL_AUDIT_AUTHENTICATION_AUTHORITY` |
+| **App config key** | `ServiceControl.Audit/Authentication.Authority` |
+| **SCMU field** | N/A |
+
+| Type | Default value |
+| --- | --- |
+| string | None |
+
+### ServiceControl.Audit/Authentication.Audience
+
+_Added in version 6.9.0_
+
+The expected audience value in the JWT token, typically the application ID or URI of the API.
+
+| Context | Name |
+| --- | --- |
+| **Environment variable** | `SERVICECONTROL_AUDIT_AUTHENTICATION_AUDIENCE` |
+| **App config key** | `ServiceControl.Audit/Authentication.Audience` |
+| **SCMU field** | N/A |
+
+| Type | Default value |
+| --- | --- |
+| string | None |
+
+### ServiceControl.Audit/Authentication.ValidateIssuer
+
+_Added in version 6.9.0_
+
+Controls whether the token issuer is validated against the authority.
+
+| Context | Name |
+| --- | --- |
+| **Environment variable** | `SERVICECONTROL_AUDIT_AUTHENTICATION_VALIDATEISSUER` |
+| **App config key** | `ServiceControl.Audit/Authentication.ValidateIssuer` |
+| **SCMU field** | N/A |
+
+| Type | Default value |
+| --- | --- |
+| bool | `true` |
+
+### ServiceControl.Audit/Authentication.ValidateAudience
+
+_Added in version 6.9.0_
+
+Controls whether the token audience is validated.
+
+| Context | Name |
+| --- | --- |
+| **Environment variable** | `SERVICECONTROL_AUDIT_AUTHENTICATION_VALIDATEAUDIENCE` |
+| **App config key** | `ServiceControl.Audit/Authentication.ValidateAudience` |
+| **SCMU field** | N/A |
+
+| Type | Default value |
+| --- | --- |
+| bool | `true` |
+
+### ServiceControl.Audit/Authentication.ValidateLifetime
+
+_Added in version 6.9.0_
+
+Controls whether the token expiration is validated.
+
+| Context | Name |
+| --- | --- |
+| **Environment variable** | `SERVICECONTROL_AUDIT_AUTHENTICATION_VALIDATELIFETIME` |
+| **App config key** | `ServiceControl.Audit/Authentication.ValidateLifetime` |
+| **SCMU field** | N/A |
+
+| Type | Default value |
+| --- | --- |
+| bool | `true` |
+
+### ServiceControl.Audit/Authentication.ValidateIssuerSigningKey
+
+_Added in version 6.9.0_
+
+Controls whether the token signing key is validated.
+
+| Context | Name |
+| --- | --- |
+| **Environment variable** | `SERVICECONTROL_AUDIT_AUTHENTICATION_VALIDATEISSUERSIGNINGKEY` |
+| **App config key** | `ServiceControl.Audit/Authentication.ValidateIssuerSigningKey` |
+| **SCMU field** | N/A |
+
+| Type | Default value |
+| --- | --- |
+| bool | `true` |
+
+### ServiceControl.Audit/Authentication.RequireHttpsMetadata
+
+_Added in version 6.9.0_
+
+Controls whether HTTPS is required when retrieving metadata from the authority.
+
+| Context | Name |
+| --- | --- |
+| **Environment variable** | `SERVICECONTROL_AUDIT_AUTHENTICATION_REQUIREHTTPSMETADATA` |
+| **App config key** | `ServiceControl.Audit/Authentication.RequireHttpsMetadata` |
+| **SCMU field** | N/A |
+
+| Type | Default value |
+| --- | --- |
+| bool | `true` |
+
+> [!WARNING]
+> Setting this to `false` is not recommended for production environments.
+
+## HTTPS
+
+These settings configure HTTPS. Refer to the [hosting and security guide](/servicecontrol/security/hosting-guide.md) for additional information.
+
+### ServiceControl.Audit/Https.Enabled
+
+_Added in version 6.9.0_
+
+Enables Kestrel HTTPS with a certificate.
+
+| Context | Name |
+| --- | --- |
+| **Environment variable** | `SERVICECONTROL_AUDIT_HTTPS_ENABLED` |
+| **App config key** | `ServiceControl.Audit/Https.Enabled` |
+| **SCMU field** | N/A |
+
+| Type | Default value |
+| --- | --- |
+| bool | `false` |
+
+### ServiceControl.Audit/Https.CertificatePath
+
+_Added in version 6.9.0_
+
+The path to the PFX or PEM certificate file.
+
+| Context | Name |
+| --- | --- |
+| **Environment variable** | `SERVICECONTROL_AUDIT_HTTPS_CERTIFICATEPATH` |
+| **App config key** | `ServiceControl.Audit/Https.CertificatePath` |
+| **SCMU field** | N/A |
+
+| Type | Default value |
+| --- | --- |
+| string | None |
+
+### ServiceControl.Audit/Https.CertificatePassword
+
+_Added in version 6.9.0_
+
+The password for the certificate file, if required.
+
+| Context | Name |
+| --- | --- |
+| **Environment variable** | `SERVICECONTROL_AUDIT_HTTPS_CERTIFICATEPASSWORD` |
+| **App config key** | `ServiceControl.Audit/Https.CertificatePassword` |
+| **SCMU field** | N/A |
+
+| Type | Default value |
+| --- | --- |
+| string | None |
+
+### ServiceControl.Audit/Https.RedirectHttpToHttps
+
+_Added in version 6.9.0_
+
+Redirects HTTP requests to HTTPS.
+
+| Context | Name |
+| --- | --- |
+| **Environment variable** | `SERVICECONTROL_AUDIT_HTTPS_REDIRECTHTTPTOHTTPS` |
+| **App config key** | `ServiceControl.Audit/Https.RedirectHttpToHttps` |
+| **SCMU field** | N/A |
+
+| Type | Default value |
+| --- | --- |
+| bool | `false` |
+
+### ServiceControl.Audit/Https.EnableHsts
+
+_Added in version 6.9.0_
+
+Enables HTTP Strict Transport Security (HSTS).
+
+| Context | Name |
+| --- | --- |
+| **Environment variable** | `SERVICECONTROL_AUDIT_HTTPS_ENABLEHSTS` |
+| **App config key** | `ServiceControl.Audit/Https.EnableHsts` |
+| **SCMU field** | N/A |
+
+| Type | Default value |
+| --- | --- |
+| bool | `false` |
+
+### ServiceControl.Audit/Https.HstsMaxAgeSeconds
+
+_Added in version 6.9.0_
+
+The max-age value in seconds for the HSTS header.
+
+| Context | Name |
+| --- | --- |
+| **Environment variable** | `SERVICECONTROL_AUDIT_HTTPS_HSTSMAXAGESECONDS` |
+| **App config key** | `ServiceControl.Audit/Https.HstsMaxAgeSeconds` |
+| **SCMU field** | N/A |
+
+| Type | Default value |
+| --- | --- |
+| int | `31536000` (1 year) |
+
+### ServiceControl.Audit/Https.HstsIncludeSubDomains
+
+_Added in version 6.9.0_
+
+Includes subdomains in the HSTS policy.
+
+| Context | Name |
+| --- | --- |
+| **Environment variable** | `SERVICECONTROL_AUDIT_HTTPS_HSTSINCLUDESUBDOMAINS` |
+| **App config key** | `ServiceControl.Audit/Https.HstsIncludeSubDomains` |
+| **SCMU field** | N/A |
+
+| Type | Default value |
+| --- | --- |
+| bool | `false` |
+
+## Forwarded headers
+
+These settings configure forwarded headers for reverse proxy scenarios. Refer to the [hosting and security guide](/servicecontrol/security/hosting-guide.md) for additional information.
+
+### ServiceControl.Audit/ForwardedHeaders.Enabled
+
+_Added in version 6.9.0_
+
+Enables processing of forwarded headers (X-Forwarded-For, X-Forwarded-Proto, etc.).
+
+| Context | Name |
+| --- | --- |
+| **Environment variable** | `SERVICECONTROL_AUDIT_FORWARDEDHEADERS_ENABLED` |
+| **App config key** | `ServiceControl.Audit/ForwardedHeaders.Enabled` |
+| **SCMU field** | N/A |
+
+| Type | Default value |
+| --- | --- |
+| bool | `true` |
+
+### ServiceControl.Audit/ForwardedHeaders.TrustAllProxies
+
+_Added in version 6.9.0_
+
+Trusts forwarded headers from any source. Set to `false` when using `KnownProxies` or `KnownNetworks`.
+
+| Context | Name |
+| --- | --- |
+| **Environment variable** | `SERVICECONTROL_AUDIT_FORWARDEDHEADERS_TRUSTALLPROXIES` |
+| **App config key** | `ServiceControl.Audit/ForwardedHeaders.TrustAllProxies` |
+| **SCMU field** | N/A |
+
+| Type | Default value |
+| --- | --- |
+| bool | `true` |
+
+> [!WARNING]
+> For production environments behind a reverse proxy, set this to `false` and configure `KnownProxies` or `KnownNetworks` to restrict which proxies are trusted.
+
+### ServiceControl.Audit/ForwardedHeaders.KnownProxies
+
+_Added in version 6.9.0_
+
+A comma-separated list of trusted proxy IP addresses.
+
+| Context | Name |
+| --- | --- |
+| **Environment variable** | `SERVICECONTROL_AUDIT_FORWARDEDHEADERS_KNOWNPROXIES` |
+| **App config key** | `ServiceControl.Audit/ForwardedHeaders.KnownProxies` |
+| **SCMU field** | N/A |
+
+| Type | Default value |
+| --- | --- |
+| string | None |
+
+Example: `127.0.0.1`
+
+### ServiceControl.Audit/ForwardedHeaders.KnownNetworks
+
+_Added in version 6.9.0_
+
+A comma-separated list of trusted CIDR network ranges.
+
+| Context | Name |
+| --- | --- |
+| **Environment variable** | `SERVICECONTROL_AUDIT_FORWARDEDHEADERS_KNOWNNETWORKS` |
+| **App config key** | `ServiceControl.Audit/ForwardedHeaders.KnownNetworks` |
+| **SCMU field** | N/A |
+
+| Type | Default value |
+| --- | --- |
+| string | None |
+
+Example: `10.0.0.0/8,172.16.0.0/12`
+
+## CORS
+
+These settings configure Cross-Origin Resource Sharing (CORS). Refer to the [hosting and security guide](/servicecontrol/security/hosting-guide.md) for additional information.
+
+### ServiceControl.Audit/Cors.AllowAnyOrigin
+
+_Added in version 6.9.0_
+
+Allows requests from any origin.
+
+| Context | Name |
+| --- | --- |
+| **Environment variable** | `SERVICECONTROL_AUDIT_CORS_ALLOWANYORIGIN` |
+| **App config key** | `ServiceControl.Audit/Cors.AllowAnyOrigin` |
+| **SCMU field** | N/A |
+
+| Type | Default value |
+| --- | --- |
+| bool | `true` |
+
+> [!WARNING]
+> For production environments, set this to `false` and configure `AllowedOrigins` to restrict which origins can access the API.
+
+### ServiceControl.Audit/Cors.AllowedOrigins
+
+_Added in version 6.9.0_
+
+A comma-separated list of allowed origins.
+
+| Context | Name |
+| --- | --- |
+| **Environment variable** | `SERVICECONTROL_AUDIT_CORS_ALLOWEDORIGINS` |
+| **App config key** | `ServiceControl.Audit/Cors.AllowedOrigins` |
+| **SCMU field** | N/A |
+
+| Type | Default value |
+| --- | --- |
+| string | None |
+
+Example: `https://servicepulse.example.com,https://admin.example.com`
+
 ## Embedded database
 
 These settings are not valid for ServiceControl instances hosted in a container.