7947 editorial review

servicecontrol/audit-instances/configuration.md

@@ -155,7 +155,7 @@ Run [ServiceControl audit instance in maintenance mode](/servicecontrol/ravendb/
 
 ## [Authentication](/servicecontrol/security/configuration/authentication.md)
 
-These settings configure [authentication using OAuth 2.0 and OpenID Connect](/servicecontrol/security/). Refer to the [hosting and security guide](/servicecontrol/security/hosting-guide.md), or [authentication configuration examples](/servicecontrol/security/configuration/authentication.md#identity-provider-setup-configuration-examples) for additional information.
+These settings configure [authentication using OAuth 2.0 and OpenID Connect](/servicecontrol/security/). Refer to the [hosting and security guide](/servicecontrol/security/hosting-guide.md) or [authentication configuration examples](/servicecontrol/security/configuration/authentication.md#identity-provider-setup-configuration-examples) for additional information.
 
 ### ServiceControl.Audit/Authentication.Enabled
 
@@ -290,7 +290,7 @@ Controls whether HTTPS is required when retrieving metadata from the authority.
 
 ## [TLS](/servicecontrol/security/configuration/tls.md)
 
-These settings configure HTTPS. Refer to the [hosting and security guide](/servicecontrol/security/hosting-guide.md), or [TLS configuration examples](/servicecontrol/security/configuration/tls.md#configuration-examples) for additional information.
+These settings configure HTTPS. Refer to the [hosting and security guide](/servicecontrol/security/hosting-guide.md) or [TLS configuration examples](/servicecontrol/security/configuration/tls.md#configuration-examples) for additional information.
 
 ### ServiceControl.Audit/Https.Enabled
 
@@ -469,7 +469,7 @@ Trusts forwarded headers from any source. Set to `false` when using `KnownProxie
 
 _Added in version 6.11.0_
 
-A comma-separated list of trusted proxy IP addresses e.g., `127.0.0.1`
+A comma-separated list of trusted proxy IP addresses, e.g. `127.0.0.1`
 
 | Context | Name |
 | --- | --- |
@@ -485,7 +485,7 @@ A comma-separated list of trusted proxy IP addresses e.g., `127.0.0.1`
 
 _Added in version 6.11.0_
 
-A comma-separated list of trusted CIDR network ranges e.g., `10.0.0.0/8,172.16.0.0/12`
+A comma-separated list of trusted CIDR network ranges, e.g. `10.0.0.0/8,172.16.0.0/12`
 
 | Context | Name |
 | --- | --- |
@@ -499,7 +499,7 @@ A comma-separated list of trusted CIDR network ranges e.g., `10.0.0.0/8,172.16.0
 
 ## [CORS](/servicecontrol/security/configuration/cors.md)
 
-These settings configure Cross-Origin Resource Sharing (CORS). Refer to the [hosting and security guide](/servicecontrol/security/hosting-guide.md), or [cors configuration examples](/servicecontrol/security/configuration/cors.md#configuration-examples) for additional information.
+These settings configure Cross-Origin Resource Sharing (CORS). Refer to the [hosting and security guide](/servicecontrol/security/hosting-guide.md) or [cors configuration examples](/servicecontrol/security/configuration/cors.md#configuration-examples) for additional information.
 
 ### ServiceControl.Audit/Cors.AllowAnyOrigin
 
@@ -524,7 +524,7 @@ Allows requests from any origin.
 
 _Added in version 6.11.0_
 
-A comma-separated list of allowed origins e.g., `https://servicepulse.example.com,https://admin.example.com`
+A comma-separated list of allowed origins, e.g. `https://servicepulse.example.com,https://admin.example.com`
 
 | Context | Name |
 | --- | --- |

servicecontrol/monitoring-instances/configuration.md

@@ -95,7 +95,7 @@ The maximum allowed time for the process to complete the shutdown.
 
 ## [Authentication](/servicecontrol/security/configuration/authentication.md)
 
-These settings configure [authentication using OAuth 2.0 and OpenID Connect](/servicecontrol/security/). Refer to the [hosting and security guide](/servicecontrol/security/hosting-guide.md), or [authentication configuration examples](/servicecontrol/security/configuration/authentication.md#identity-provider-setup-configuration-examples) for additional information.
+These settings configure [authentication using OAuth 2.0 and OpenID Connect](/servicecontrol/security/). Refer to the [hosting and security guide](/servicecontrol/security/hosting-guide.md) or [authentication configuration examples](/servicecontrol/security/configuration/authentication.md#identity-provider-setup-configuration-examples) for additional information.
 
 ### Monitoring/Authentication.Enabled
 
@@ -230,7 +230,7 @@ Controls whether HTTPS is required when retrieving metadata from the authority.
 
 ## [TLS](/servicecontrol/security/configuration/tls.md)
 
-These settings configure HTTPS. Refer to the [hosting and security guide](/servicecontrol/security/hosting-guide.md), or [TLS configuration examples](/servicecontrol/security/configuration/tls.md#configuration-examples) for additional information.
+These settings configure HTTPS. Refer to the [hosting and security guide](/servicecontrol/security/hosting-guide.md) or [TLS configuration examples](/servicecontrol/security/configuration/tls.md#configuration-examples) for additional information.
 
 ### Monitoring/Https.Enabled
 
@@ -368,7 +368,7 @@ Includes subdomains in the HSTS policy.
 
 ## [Forwarded headers](/servicecontrol/security/configuration/forward-headers.md)
 
-These settings configure forwarded headers for reverse proxy scenarios. Refer to the [hosting and security guide](/servicecontrol/security/hosting-guide.md), or [forward headers configuration examples](/servicecontrol/security/configuration/forward-headers.md#configuration-examples) for additional information.
+These settings configure forwarded headers for reverse proxy scenarios. Refer to the [hosting and security guide](/servicecontrol/security/hosting-guide.md) or [forward headers configuration examples](/servicecontrol/security/configuration/forward-headers.md#configuration-examples) for additional information.
 
 ### Monitoring/ForwardedHeaders.Enabled
 
@@ -409,7 +409,7 @@ Trusts forwarded headers from any source. Set to `false` when using `KnownProxie
 
 _Added in version 6.11.0_
 
-A comma-separated list of trusted proxy IP addresses e.g., `127.0.0.1`
+A comma-separated list of trusted proxy IP addresses, e.g. `127.0.0.1`
 
 | Context | Name |
 | --- | --- |
@@ -425,7 +425,7 @@ A comma-separated list of trusted proxy IP addresses e.g., `127.0.0.1`
 
 _Added in version 6.11.0_
 
-A comma-separated list of trusted CIDR network ranges e.g., `10.0.0.0/8,172.16.0.0/12`
+A comma-separated list of trusted CIDR network ranges, e.g. `10.0.0.0/8,172.16.0.0/12`
 
 | Context | Name |
 | --- | --- |
@@ -464,7 +464,7 @@ Allows requests from any origin.
 
 _Added in version 6.11.0_
 
-A comma-separated list of allowed origins e.g., `https://servicepulse.example.com,https://admin.example.com`
+A comma-separated list of allowed origins, e.g. `https://servicepulse.example.com,https://admin.example.com`
 
 | Context | Name |
 | --- | --- |

servicecontrol/security/configuration/authentication.md

@@ -11,7 +11,7 @@ related:
 ServiceControl instances can be configured to require [JWT](https://en.wikipedia.org/wiki/JSON_Web_Token) authentication using [OpenID Connect (OIDC)](https://openid.net/developers/how-connect-works/). This enables integration with identity providers like Microsoft Entra ID (Azure AD), Okta, Auth0, and other OIDC-compliant providers. This guide explains how to configure ServiceControl to enable authentication for both ServiceControl and ServicePulse.
 
 > [!NOTE]
-> Authentication is disabled by default. To enable it, see below.
+> Authentication is disabled by default. To enable it, follow the configuration instructions for each instance type below.
 
 ## Configuration
 
@@ -29,21 +29,21 @@ When registering ServiceControl with your identity provider, you will need the f
 |-------------------------------|------------------------------------------------------------------------------------------------------------------|
 | Application type              | Web application / API (confidential client)                                                                      |
 | Redirect URI                  | Not required for API-only registration                                                                           |
-| Audience                      | A unique identifier for the ServiceControl API (e.g., `api://servicecontrol` or a custom URI)                    |
-| Scopes                        | Define at least one scope that ServicePulse can request (e.g., `api.access`)                                     |
+| Audience                      | A unique identifier for the ServiceControl API (e.g. `api://servicecontrol` or a custom URI)                    |
+| Scopes                        | Define at least one scope that ServicePulse can request (e.g. `api.access`)                                     |
 | Allowed token audiences       | Must include the audience configured in ServiceControl                                                           |
 
 Additionally, a separate application registration is required for ServicePulse. See [ServicePulse Identity Provider Setup](/servicepulse/security/configuration/authentication.md#identity-provider-setup) for those requirements.
 
 ### Identity Provider Guides
 
-For step-by-step instructions on configuring specific identity providers, see:
+Step-by-step instructions on configuring some specific identity providers are provided below. For any other identity providers, read their specific documentation and adapt it to the general guidance covered for [Microsoft Entra ID](../entra-id-authentication.md).
 
 - [Microsoft Entra ID](../entra-id-authentication.md)
 
 ### Configuration examples
 
-The following examples show complete authentication configurations for common identity providers using the primary ServiceControl instance.
+The following examples show complete authentication configurations for some common identity providers using the primary ServiceControl instance.
 
 #### Microsoft Entra ID
 

servicecontrol/security/configuration/cors.md

@@ -7,7 +7,7 @@ related:
 - servicecontrol/security/hosting-guide
 ---
 
-Cross-Origin Resource Sharing (CORS) controls which web applications can make requests to ServiceControl. This is important when ServicePulse is hosted on a different domain than ServiceControl.
+Cross-Origin Resource Sharing (CORS) controls which web applications can make requests to ServiceControl. This is important when ServicePulse is hosted on a different domain or port than ServiceControl.
 
 ## Configuration
 
@@ -58,8 +58,11 @@ To allow multiple origins:
 - Verify the origin in `AllowedOrigins` matches exactly, including:
   - Protocol (`https://` vs `http://`)
   - Domain name (no trailing slash)
-  - Port number if non-standard (e.g., `https://servicepulse.example.com:8080`)
-- For testing, temporarily set `AllowAnyOrigin` to `true` to confirm CORS is the issue
+  - Port number if non-standard (e.g. `https://servicepulse.example.com:8080`)
+- For testing, temporarily set `AllowAnyOrigin` to `true` to confirm CORS is the issue.
+
+> [!CAUTION]
+> Do not leave `AllowAnyOrigin` set to `true` in any production environment. This removes a key browser security feature.
 
 ### CORS preflight requests failing
 

servicecontrol/security/configuration/forward-header-troubleshooting.include.md

@@ -12,7 +12,7 @@
 
 ### Wrong host in generated URLs
 
-**Symptom**: Links or redirects use the internal hostname (e.g., `localhost` or container name) instead of the public hostname.
+**Symptom**: Links or redirects use the internal hostname (e.g. `localhost` or container name) instead of the public hostname.
 
 **Cause**: The `X-Forwarded-Host` header is not being trusted or processed.
 
@@ -42,7 +42,7 @@
 
 **Solutions**:
 
-- Use `KnownNetworks` with the pod/service CIDR range instead of specific IPs (e.g., `10.0.0.0/8`)
+- Use `KnownNetworks` with the pod/service CIDR range instead of specific IPs (e.g. `10.0.0.0/8`)
 - Check what IP the request is actually coming from (ingress controller pod IP, node IP, or load balancer IP)
 - For development/testing, temporarily enable `TrustAllProxies=true` to confirm headers are the issue
 

servicecontrol/security/configuration/forward-headers.md

@@ -20,16 +20,16 @@ ServiceControl instances can be configured via environment variables or App.conf
 
 ## What Headers are Processed
 
-When enabled, ServiceControl instances processes:
+When enabled, ServiceControl instances process:
 
 - `X-Forwarded-For` - Original client IP address
 - `X-Forwarded-Proto` - Original protocol (http/https)
 - `X-Forwarded-Host` - Original host header
 
 When the proxy is trusted:
 
-- `Request.Scheme` will be set from `X-Forwarded-Proto` (e.g., `https`)
-- `Request.Host` will be set from `X-Forwarded-Host` (e.g., `servicecontrol.example.com`)
+- `Request.Scheme` will be set from `X-Forwarded-Proto` (e.g. `https`)
+- `Request.Host` will be set from `X-Forwarded-Host` (e.g. `servicecontrol.example.com`)
 - Client IP will be available from `X-Forwarded-For`
 
 When the proxy is **not** trusted (incorrect `KnownProxies`):
@@ -41,7 +41,7 @@ When the proxy is **not** trusted (incorrect `KnownProxies`):
 
 ## HTTP to HTTPS Redirect
 
-When using a reverse proxy that terminates SSL, you can configure ServiceControl instances to redirect HTTP requests to HTTPS. This works in combination with forwarded headers:
+When using a reverse proxy that terminates SSL, ServiceControl instances can be configured to redirect HTTP requests to HTTPS. This works in combination with forwarded headers:
 
 1. The reverse proxy forwards both HTTP and HTTPS requests to ServiceControl
 2. The proxy sets `X-Forwarded-Proto` to indicate the original protocol
@@ -66,7 +66,7 @@ sequenceDiagram
     SC->>Client: Response (via Proxy)
 ```
 
-To enable HTTP to HTTPS redirect, see [TLS Configuration](tls.md) for details on how to do this.
+To enable HTTP to HTTPS redirect, see [TLS Configuration](tls.md).
 
 ## Proxy Chain Behavior (ForwardLimit)
 
@@ -98,7 +98,7 @@ When running behind a single reverse proxy with a known IP address:
 
 ### Multiple reverse proxies
 
-When running behind multiple proxies (e.g., load balancer and application gateway):
+When running behind multiple proxies (e.g. load balancer and application gateway):
 
 ```xml
 <add key="ServiceControl/ForwardedHeaders.Enabled" value="true" />

servicecontrol/security/configuration/tls-troubleshooting.include.md

@@ -9,7 +9,7 @@
 - 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`)
+- For containers, ensure the volume mount is correct (e.g. `-v certificate.pfx:/usr/share/ParticularSoftware/certificate.pfx`)
 
 ### HTTPS redirect not working
 
@@ -47,21 +47,21 @@
 - 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.,
+- 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.
+**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)
+- 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
@@ -79,7 +79,7 @@
 
 ### Health checks fail with certificate errors
 
-**Symptom**: Container health check reports unhealthy, logs show SSL errors from the health check command.
+**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.
 

servicecontrol/security/configuration/tls.md

@@ -53,7 +53,7 @@ When ServiceControl handles TLS directly using a PFX certificate:
 **Container**:
 
 > [!NOTE]
-> The following is a docker compose snippets. For full examples, see the [Platform Container Examples repository](https://github.com/Particular/PlatformContainerExamples).
+> The following is a docker compose snippet. For full examples, see the [Platform Container Examples repository](https://github.com/Particular/PlatformContainerExamples).
 
 ```bash
 servicecontrol:
@@ -97,7 +97,7 @@ servicecontrol:
 **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).
+> When containers communicate with each other over HTTPS, they use the Docker service names (like `servicecontrol`, `servicecontrol-audit`) as hostnames. TLS validation will fail if the certificate doesn't include these names in its Subject Alternative Names (SANs).
 
 ### Direct HTTPS with HSTS
 

servicecontrol/security/entra-id-authentication.md

@@ -60,7 +60,7 @@ Follow Microsoft's guide to [register an application](https://learn.microsoft.co
 | Name                    | `ServicePulse`                                                                   |
 | Supported account types | Accounts in this organizational directory only (single tenant)                   |
 | Redirect URI - Platform | Single-page application (SPA)                                                    |
-| Redirect URI - URI      | The URL where ServicePulse is hosted (e.g., `https://servicepulse.example.com/`) |
+| Redirect URI - URI      | The URL where ServicePulse is hosted (e.g. `https://servicepulse.example.com/`) |
 
 After registration, collect this value: