Skip to content

Commit a1b043b

Browse files
warwickschroederwarwickschroeder
committed
Update local testing files. Add debug endpoint for dev.
1 parent a5d9d5b commit a1b043b

File tree

8 files changed

+1077
-128
lines changed

8 files changed

+1077
-128
lines changed

‎docs/local-forward-headers-testing.md‎

Lines changed: 726 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/local-https-testing.md‎

Lines changed: 152 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,24 @@
11
# Local Testing with Direct HTTPS
22

3-
This guide explains how to test ServiceControl with direct HTTPS enabled on Kestrel, without using a reverse proxy. This is useful for testing scenarios like:
3+
This guide provides scenario-based tests for ServiceControl's direct HTTPS features. Use this to verify Kestrel HTTPS behavior without a reverse proxy.
44

5-
- Direct TLS termination at ServiceControl
6-
- HTTPS redirection
7-
- HSTS (HTTP Strict Transport Security)
8-
- End-to-end encryption testing
5+
> **Note:** HTTP to HTTPS redirection (`RedirectHttpToHttps`) is designed for reverse proxy scenarios where the proxy forwards HTTP requests to ServiceControl. When running with direct HTTPS, ServiceControl only binds to a single port (HTTPS). To test HTTP to HTTPS redirection, see [Local Reverse Proxy Testing](local-reverseproxy-testing.md).
6+
7+
## Instance Reference
8+
9+
| Instance | Project Directory | Default Port | Environment Variable Prefix | App.config Key Prefix |
10+
|----------|-------------------|--------------|-----------------------------|-----------------------|
11+
| ServiceControl (Primary) | `src\ServiceControl` | 33333 | `SERVICECONTROL_` | `ServiceControl/` |
12+
| ServiceControl.Audit | `src\ServiceControl.Audit` | 44444 | `SERVICECONTROL_AUDIT_` | `ServiceControl.Audit/` |
13+
| ServiceControl.Monitoring | `src\ServiceControl.Monitoring` | 33633 | `MONITORING_` | `Monitoring/` |
14+
15+
> **Note:** Environment variables must include the instance prefix (e.g., `SERVICECONTROL_HTTPS_ENABLED` for the primary instance).
916
1017
## Prerequisites
1118

1219
- [mkcert](https://github.com/FiloSottile/mkcert) for generating local development certificates
1320
- ServiceControl built locally (see main README for build instructions)
21+
- curl (included with Windows 10/11, Git Bash, or WSL)
1422

1523
### Installing mkcert
1624

@@ -45,7 +53,9 @@ sudo pacman -S mkcert
4553

4654
After installing, run `mkcert -install` to install the local CA in your system trust store.
4755

48-
## Step 1: Create the Local Development Folder
56+
## Setup
57+
58+
### Step 1: Create the Local Development Folder
4959

5060
Create a `.local` folder in the repository root (this folder is gitignored):
5161

@@ -54,7 +64,7 @@ mkdir .local
5464
mkdir .local/certs
5565
```
5666

57-
## Step 2: Generate PFX Certificates
67+
### Step 2: Generate PFX Certificates
5868

5969
Kestrel requires certificates in PFX format. Use mkcert to generate them:
6070

@@ -69,107 +79,124 @@ cd .local/certs
6979
mkcert -p12-file localhost.pfx -pkcs12 localhost 127.0.0.1 ::1
7080
```
7181

72-
When prompted for a password, you can use an empty password by pressing Enter, or set a password and note it for the configuration step.
82+
When prompted for a password, you can use an empty password by pressing Enter, or set a password (e.g., `changeit`) and note it for the configuration step.
83+
84+
## Test Scenarios
7385

74-
## Step 3: Configure ServiceControl Instances
86+
All scenarios use environment variables for configuration. Run each scenario from the `src/ServiceControl` directory.
7587

76-
Configure HTTPS in the `App.config` file for each ServiceControl instance. See [HTTPS Settings](hosting-guide.md#https-settings) in the Hosting Guide for all available options.
88+
### Scenario 1: Basic HTTPS Connectivity
7789

78-
| Instance | Config Key Prefix | App.config Location |
79-
|----------|-------------------|---------------------|
80-
| ServiceControl (Primary) | `ServiceControl/` | `src/ServiceControl/App.config` |
81-
| ServiceControl.Audit | `ServiceControl.Audit/` | `src/ServiceControl.Audit/App.config` |
82-
| ServiceControl.Monitoring | `Monitoring/` | `src/ServiceControl.Monitoring/App.config` |
90+
Verify that HTTPS is working with a valid certificate.
8391

84-
Example for ServiceControl (Primary):
92+
**Cleanup and start ServiceControl:**
8593

86-
```xml
87-
<appSettings>
88-
<!-- Enable Kestrel HTTPS -->
89-
<add key="ServiceControl/Https.Enabled" value="true" />
90-
<add key="ServiceControl/Https.CertificatePath" value="C:\path\to\repo\.local\certs\localhost.pfx" />
91-
<add key="ServiceControl/Https.CertificatePassword" value="" />
94+
```cmd
95+
set SERVICECONTROL_HTTPS_ENABLED=true
96+
set SERVICECONTROL_HTTPS_CERTIFICATEPATH=C:\path\to\ServiceControl\.local\certs\localhost.pfx
97+
set SERVICECONTROL_HTTPS_CERTIFICATEPASSWORD=changeit
98+
set SERVICECONTROL_FORWARDEDHEADERS_ENABLED=false
9299
93-
<!-- Optional: Enable HSTS -->
94-
<add key="ServiceControl/Https.EnableHsts" value="true" />
100+
dotnet run
101+
```
95102

96-
<!-- Optional: Redirect HTTP to HTTPS -->
97-
<add key="ServiceControl/Https.RedirectHttpToHttps" value="true" />
103+
**Test with curl:**
98104

99-
<!-- Disable forwarded headers (no reverse proxy) -->
100-
<add key="ServiceControl/ForwardedHeaders.Enabled" value="false" />
101-
</appSettings>
105+
```cmd
106+
curl --ssl-no-revoke -v https://localhost:33333/api 2>&1 | findstr /C:"HTTP/" /C:"SSL"
102107
```
103108

104-
> **Note:** Replace `C:\path\to\repo` with the actual path to your ServiceControl repository. Use the full absolute path to the PFX file.
109+
> **Note:** The `--ssl-no-revoke` flag is required on Windows because mkcert certificates don't have CRL distribution points, causing `CRYPT_E_NO_REVOCATION_CHECK` errors.
105110
106-
## Step 4: Start ServiceControl Instances
111+
**Expected output:**
107112

108-
Start the ServiceControl instances locally using your preferred method:
113+
```text
114+
* schannel: SSL/TLS connection renegotiated
115+
< HTTP/1.1 200 OK
116+
```
109117

110-
### **Option A: Visual Studio**
118+
The request succeeds over HTTPS. The exact SSL output varies by curl version and platform, but you should see `HTTP/1.1 200 OK` confirming success.
111119

112-
1. Open `src/ServiceControl.sln`
113-
2. Run the desired project(s) with the appropriate launch profile
120+
### Scenario 2: HTTP Disabled (HTTPS Only)
114121

115-
### **Option B: Command Line**
122+
Verify that HTTP requests fail when only HTTPS is enabled.
116123

117-
```bash
118-
# Run ServiceControl (Primary)
119-
dotnet run --project src/ServiceControl/ServiceControl.csproj
124+
**Cleanup and start ServiceControl:**
120125

121-
# Run ServiceControl.Audit
122-
dotnet run --project src/ServiceControl.Audit/ServiceControl.Audit.csproj
126+
```cmd
127+
set SERVICECONTROL_HTTPS_ENABLED=true
128+
set SERVICECONTROL_HTTPS_CERTIFICATEPATH=C:\path\to\ServiceControl\.local\certs\localhost.pfx
129+
set SERVICECONTROL_HTTPS_CERTIFICATEPASSWORD=changeit
130+
set SERVICECONTROL_FORWARDEDHEADERS_ENABLED=false
123131
124-
# Run ServiceControl.Monitoring
125-
dotnet run --project src/ServiceControl.Monitoring/ServiceControl.Monitoring.csproj
132+
dotnet run
126133
```
127134

128-
## Step 5: Verify the Setup
129-
130-
Test that HTTPS is working correctly:
135+
**Test with curl (HTTP):**
131136

132-
```bash
133-
# Test ServiceControl (Primary)
134-
curl https://localhost:33333/api
137+
```cmd
138+
curl http://localhost:33333/api
139+
```
135140

136-
# Test ServiceControl.Audit
137-
curl https://localhost:44444/api
141+
**Expected output:**
138142

139-
# Test ServiceControl.Monitoring
140-
curl https://localhost:33633/api
143+
```text
144+
curl: (52) Empty reply from server
141145
```
142146

143-
If you've installed mkcert's root CA, the requests should succeed without certificate warnings.
147+
HTTP requests fail because Kestrel is listening for HTTPS but receives plaintext HTTP, which it cannot process. The server closes the connection without responding.
144148

145-
### Testing HTTPS Redirection
149+
## HTTPS Configuration Reference
146150

147-
If `RedirectHttpToHttps` is enabled, HTTP requests should redirect to HTTPS:
151+
| App.config Key | Environment Variable (Primary) | Default | Description |
152+
|----------------|-------------------------------|---------|-------------|
153+
| `Https.Enabled` | `SERVICECONTROL_HTTPS_ENABLED` | `false` | Enable Kestrel HTTPS |
154+
| `Https.CertificatePath` | `SERVICECONTROL_HTTPS_CERTIFICATEPATH` | - | Path to PFX certificate file |
155+
| `Https.CertificatePassword` | `SERVICECONTROL_HTTPS_CERTIFICATEPASSWORD` | - | Certificate password (empty string for no password) |
156+
| `Https.RedirectHttpToHttps` | `SERVICECONTROL_HTTPS_REDIRECTHTTPTOHTTPS` | `false` | Redirect HTTP requests to HTTPS (reverse proxy only) |
157+
| `Https.EnableHsts` | `SERVICECONTROL_HTTPS_ENABLEHSTS` | `false` | Enable HTTP Strict Transport Security |
158+
| `Https.HstsMaxAgeSeconds` | `SERVICECONTROL_HTTPS_HSTSMAXAGESECONDS` | `31536000` | HSTS max-age (1 year) |
159+
| `Https.HstsIncludeSubDomains` | `SERVICECONTROL_HTTPS_HSTSINCLUDESUBDOMAINS` | `false` | Include subdomains in HSTS |
148160

149-
```bash
150-
# This should redirect to https://localhost:33333/api
151-
curl -v http://localhost:33333/api
152-
```
161+
> **Note:** For other instances, replace the `SERVICECONTROL_` prefix with the appropriate instance prefix (see Instance Reference table).
162+
>
163+
> **Note:** HSTS is not tested locally because ASP.NET Core excludes localhost from HSTS by default (to prevent accidentally caching HSTS during development). HSTS will work correctly in production with non-localhost hostnames.
153164
154-
### Testing HSTS
165+
## Testing Other Instances
155166

156-
If `EnableHsts` is enabled, the response should include the `Strict-Transport-Security` header:
167+
The same scenarios can be run against ServiceControl.Audit and ServiceControl.Monitoring by:
157168

158-
```bash
159-
curl -v https://localhost:33333/api 2>&1 | grep -i strict-transport-security
169+
1. Using the appropriate environment variable prefix
170+
2. Running from the correct project directory
171+
3. Using the correct port
172+
173+
**ServiceControl.Audit:**
174+
175+
```cmd
176+
set SERVICECONTROL_AUDIT_HTTPS_ENABLED=true
177+
set SERVICECONTROL_AUDIT_HTTPS_CERTIFICATEPATH=C:\path\to\ServiceControl\.local\certs\localhost.pfx
178+
set SERVICECONTROL_AUDIT_HTTPS_CERTIFICATEPASSWORD=changeit
179+
180+
dotnet run --project src/ServiceControl.Audit/ServiceControl.Audit.csproj
160181
```
161182

162-
## HTTPS Configuration Reference
183+
```cmd
184+
curl --ssl-no-revoke https://localhost:44444/api
185+
```
163186

164-
| Setting | Default | Description |
165-
|---------|---------|-------------|
166-
| `Https.Enabled` | `false` | Enable Kestrel HTTPS |
167-
| `Https.CertificatePath` | - | Path to PFX certificate file |
168-
| `Https.CertificatePassword` | - | Certificate password (empty string for no password) |
169-
| `Https.RedirectHttpToHttps` | `false` | Redirect HTTP requests to HTTPS |
170-
| `Https.EnableHsts` | `false` | Enable HTTP Strict Transport Security |
171-
| `Https.HstsMaxAgeSeconds` | `31536000` | HSTS max-age (1 year) |
172-
| `Https.HstsIncludeSubDomains` | `false` | Include subdomains in HSTS |
187+
**ServiceControl.Monitoring:**
188+
189+
```cmd
190+
set MONITORING_HTTPS_ENABLED=true
191+
set MONITORING_HTTPS_CERTIFICATEPATH=C:\path\to\ServiceControl\.local\certs\localhost.pfx
192+
set MONITORING_HTTPS_CERTIFICATEPASSWORD=changeit
193+
194+
dotnet run --project src/ServiceControl.Monitoring/ServiceControl.Monitoring.csproj
195+
```
196+
197+
```cmd
198+
curl --ssl-no-revoke https://localhost:33633/api
199+
```
173200

174201
## Troubleshooting
175202

@@ -181,16 +208,65 @@ Ensure the `CertificatePath` is an absolute path and the file exists.
181208

182209
If you set a password when generating the PFX, ensure it matches `CertificatePassword` in the config.
183210

184-
### Certificate errors in browser
211+
### Certificate errors in browser/curl
185212

186213
1. Ensure mkcert's root CA is installed: `mkcert -install`
187214
2. Restart your browser after installing the root CA
188215

216+
### CRYPT_E_NO_REVOCATION_CHECK error in curl
217+
218+
Windows curl fails to check certificate revocation for mkcert certificates because they don't have CRL distribution points. Use the `--ssl-no-revoke` flag:
219+
220+
```cmd
221+
curl --ssl-no-revoke https://localhost:33333/api
222+
```
223+
189224
### Port already in use
190225

191226
Ensure no other process is using the ServiceControl ports (33333, 44444, 33633).
192227

228+
## Cleanup
229+
230+
After testing, clear the environment variables:
231+
232+
**Command Prompt (cmd):**
233+
234+
```cmd
235+
set SERVICECONTROL_HTTPS_ENABLED=
236+
set SERVICECONTROL_HTTPS_CERTIFICATEPATH=
237+
set SERVICECONTROL_HTTPS_CERTIFICATEPASSWORD=
238+
set SERVICECONTROL_HTTPS_ENABLEHSTS=
239+
set SERVICECONTROL_HTTPS_HSTSMAXAGESECONDS=
240+
set SERVICECONTROL_HTTPS_HSTSINCLUDESUBDOMAINS=
241+
set SERVICECONTROL_FORWARDEDHEADERS_ENABLED=
242+
```
243+
244+
**PowerShell:**
245+
246+
```powershell
247+
$env:SERVICECONTROL_HTTPS_ENABLED = $null
248+
$env:SERVICECONTROL_HTTPS_CERTIFICATEPATH = $null
249+
$env:SERVICECONTROL_HTTPS_CERTIFICATEPASSWORD = $null
250+
$env:SERVICECONTROL_HTTPS_ENABLEHSTS = $null
251+
$env:SERVICECONTROL_HTTPS_HSTSMAXAGESECONDS = $null
252+
$env:SERVICECONTROL_HTTPS_HSTSINCLUDESUBDOMAINS = $null
253+
$env:SERVICECONTROL_FORWARDEDHEADERS_ENABLED = $null
254+
```
255+
256+
**Bash (Git Bash, WSL, Linux, macOS):**
257+
258+
```bash
259+
unset SERVICECONTROL_HTTPS_ENABLED
260+
unset SERVICECONTROL_HTTPS_CERTIFICATEPATH
261+
unset SERVICECONTROL_HTTPS_CERTIFICATEPASSWORD
262+
unset SERVICECONTROL_HTTPS_ENABLEHSTS
263+
unset SERVICECONTROL_HTTPS_HSTSMAXAGESECONDS
264+
unset SERVICECONTROL_HTTPS_HSTSINCLUDESUBDOMAINS
265+
unset SERVICECONTROL_FORWARDEDHEADERS_ENABLED
266+
```
267+
193268
## See Also
194269

195270
- [Hosting Guide](hosting-guide.md) - Detailed configuration reference for all deployment scenarios
196-
- [Local NGINX Testing](local-nginx-testing.md) - Testing with a reverse proxy
271+
- [Local Reverse Proxy Testing](local-reverseproxy-testing.md) - Testing with a reverse proxy (NGINX)
272+
- [Local Forwarded Headers Testing](local-forward-headers-testing.md) - Testing forwarded headers without a reverse proxy

0 commit comments

Comments
 (0)