Skip to content

Commit 1b8cb65

Browse files
warwickschroederwarwickschroeder
committed
Clean doc formatting. Update hosting guide.
1 parent 3b33ba5 commit 1b8cb65

9 files changed

+865
-462
lines changed

‎docs/authentication-testing.md‎

Lines changed: 19 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,11 @@ This guide explains how to test authentication configuration for ServiceControl
1212

1313
## Instance Reference
1414

15-
| Instance | Project Directory | Default Port | Environment Variable Prefix |
16-
|----------|-------------------|--------------|----------------------------|
17-
| ServiceControl (Primary) | `src\ServiceControl` | 33333 | `SERVICECONTROL_` |
18-
| ServiceControl.Audit | `src\ServiceControl.Audit` | 44444 | `SERVICECONTROL_AUDIT_` |
19-
| ServiceControl.Monitoring | `src\ServiceControl.Monitoring` | 33633 | `MONITORING_` |
15+
| Instance | Project Directory | Default Port | Environment Variable Prefix |
16+
|---------------------------|---------------------------------|--------------|-----------------------------|
17+
| ServiceControl (Primary) | `src\ServiceControl` | 33333 | `SERVICECONTROL_` |
18+
| ServiceControl.Audit | `src\ServiceControl.Audit` | 44444 | `SERVICECONTROL_AUDIT_` |
19+
| ServiceControl.Monitoring | `src\ServiceControl.Monitoring` | 33633 | `MONITORING_` |
2020

2121
## How Authentication Works
2222

@@ -224,9 +224,9 @@ curl http://localhost:33333/api/authentication/configuration | json
224224

225225
The following endpoints are marked as anonymous and accessible without authentication:
226226

227-
| Endpoint | Purpose |
228-
|----------|---------|
229-
| `/api` | API root/discovery - returns available endpoints |
227+
| Endpoint | Purpose |
228+
|-------------------------------------|---------------------------------------------------|
229+
| `/api` | API root/discovery - returns available endpoints |
230230
| `/api/authentication/configuration` | Returns auth config for clients like ServicePulse |
231231

232232
### Scenario 5: Validation Settings Warnings
@@ -747,12 +747,12 @@ The primary instance rejects the expired token before any remote requests are ma
747747

748748
The following internal API calls from the primary instance to remote instances do **not** forward authentication headers:
749749

750-
| Internal Call | Endpoint | Purpose |
751-
|---------------|----------|---------|
752-
| Health Check | `GET /api` | Verify remote instance availability |
753-
| Configuration | `GET /api/configuration` | Retrieve remote instance configuration |
754-
| Platform Connection | `GET /api/connection` | Aggregate platform connection details |
755-
| License Throughput | `GET /api/endpoints`, `GET /api/endpoints/{name}/audit-count` | Collect audit throughput for licensing |
750+
| Internal Call | Endpoint | Purpose |
751+
|---------------------|---------------------------------------------------------------|----------------------------------------|
752+
| Health Check | `GET /api` | Verify remote instance availability |
753+
| Configuration | `GET /api/configuration` | Retrieve remote instance configuration |
754+
| Platform Connection | `GET /api/connection` | Aggregate platform connection details |
755+
| License Throughput | `GET /api/endpoints`, `GET /api/endpoints/{name}/audit-count` | Collect audit throughput for licensing |
756756

757757
**Implications:**
758758

@@ -782,11 +782,11 @@ The scenarios above use ServiceControl (Primary). To test ServiceControl.Audit o
782782
2. Use the corresponding project directory and port
783783
3. Note: Audit and Monitoring instances don't require ServicePulse settings
784784

785-
| Instance | Project Directory | Port | Env Var Prefix |
786-
|----------|-------------------|------|----------------|
787-
| ServiceControl (Primary) | `src\ServiceControl` | 33333 | `SERVICECONTROL_` |
788-
| ServiceControl.Audit | `src\ServiceControl.Audit` | 44444 | `SERVICECONTROL_AUDIT_` |
789-
| ServiceControl.Monitoring | `src\ServiceControl.Monitoring` | 33633 | `MONITORING_` |
785+
| Instance | Project Directory | Port | Env Var Prefix |
786+
|---------------------------|---------------------------------|-------|-------------------------|
787+
| ServiceControl (Primary) | `src\ServiceControl` | 33333 | `SERVICECONTROL_` |
788+
| ServiceControl.Audit | `src\ServiceControl.Audit` | 44444 | `SERVICECONTROL_AUDIT_` |
789+
| ServiceControl.Monitoring | `src\ServiceControl.Monitoring` | 33633 | `MONITORING_` |
790790

791791
## Cleanup
792792

‎docs/authentication.md‎

Lines changed: 46 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -8,47 +8,47 @@ ServiceControl instances can be configured via environment variables or App.conf
88

99
### Environment Variables
1010

11-
| Instance | Prefix |
12-
|----------|--------|
13-
| ServiceControl (Primary) | `SERVICECONTROL_` |
14-
| ServiceControl.Audit | `SERVICECONTROL_AUDIT_` |
15-
| ServiceControl.Monitoring | `MONITORING_` |
11+
| Instance | Prefix |
12+
|---------------------------|-------------------------|
13+
| ServiceControl (Primary) | `SERVICECONTROL_` |
14+
| ServiceControl.Audit | `SERVICECONTROL_AUDIT_` |
15+
| ServiceControl.Monitoring | `MONITORING_` |
1616

1717
#### Core Settings
1818

19-
| Setting | Default | Description |
20-
|---------|---------|-------------|
21-
| `{PREFIX}AUTHENTICATION_ENABLED` | `false` | Enable JWT authentication |
22-
| `{PREFIX}AUTHENTICATION_AUTHORITY` | (none) | OpenID Connect authority URL (e.g., `https://login.microsoftonline.com/{tenant-id}/v2.0`) |
23-
| `{PREFIX}AUTHENTICATION_AUDIENCE` | (none) | The audience identifier (typically your API identifier or client ID) |
19+
| Setting | Default | Description |
20+
|------------------------------------|---------|-------------------------------------------------------------------------------------------|
21+
| `{PREFIX}AUTHENTICATION_ENABLED` | `false` | Enable JWT authentication |
22+
| `{PREFIX}AUTHENTICATION_AUTHORITY` | (none) | OpenID Connect authority URL (e.g., `https://login.microsoftonline.com/{tenant-id}/v2.0`) |
23+
| `{PREFIX}AUTHENTICATION_AUDIENCE` | (none) | The audience identifier (typically your API identifier or client ID) |
2424

2525
#### Validation Settings
2626

27-
| Setting | Default | Description |
28-
|---------|---------|-------------|
29-
| `{PREFIX}AUTHENTICATION_VALIDATEISSUER` | `true` | Validate the token issuer |
30-
| `{PREFIX}AUTHENTICATION_VALIDATEAUDIENCE` | `true` | Validate the token audience |
31-
| `{PREFIX}AUTHENTICATION_VALIDATELIFETIME` | `true` | Validate token expiration |
32-
| `{PREFIX}AUTHENTICATION_VALIDATEISSUERSIGNINGKEY` | `true` | Validate the signing key |
33-
| `{PREFIX}AUTHENTICATION_REQUIREHTTPSMETADATA` | `true` | Require HTTPS for OIDC metadata endpoint |
27+
| Setting | Default | Description |
28+
|---------------------------------------------------|---------|------------------------------------------|
29+
| `{PREFIX}AUTHENTICATION_VALIDATEISSUER` | `true` | Validate the token issuer |
30+
| `{PREFIX}AUTHENTICATION_VALIDATEAUDIENCE` | `true` | Validate the token audience |
31+
| `{PREFIX}AUTHENTICATION_VALIDATELIFETIME` | `true` | Validate token expiration |
32+
| `{PREFIX}AUTHENTICATION_VALIDATEISSUERSIGNINGKEY` | `true` | Validate the signing key |
33+
| `{PREFIX}AUTHENTICATION_REQUIREHTTPSMETADATA` | `true` | Require HTTPS for OIDC metadata endpoint |
3434

3535
#### ServicePulse Settings (Primary Instance Only)
3636

3737
These settings are required on the primary ServiceControl instance to provide authentication configuration to ServicePulse clients.
3838

39-
| Setting | Default | Description |
40-
|---------|---------|-------------|
41-
| `{PREFIX}AUTHENTICATION_SERVICEPULSE_CLIENTID` | (none) | Client ID for ServicePulse application |
42-
| `{PREFIX}AUTHENTICATION_SERVICEPULSE_AUTHORITY` | (none) | Authority URL for ServicePulse (defaults to main Authority if not set) |
43-
| `{PREFIX}AUTHENTICATION_SERVICEPULSE_APISCOPES` | (none) | JSON array of API scopes (e.g., `["api://servicecontrol/access_as_user"]`) |
39+
| Setting | Default | Description |
40+
|-------------------------------------------------|---------|--------------------------------------------------------------------------------------------------------|
41+
| `{PREFIX}AUTHENTICATION_SERVICEPULSE_CLIENTID` | (none) | Client ID for ServicePulse application |
42+
| `{PREFIX}AUTHENTICATION_SERVICEPULSE_AUTHORITY` | (none) | Authority URL for ServicePulse (defaults to main Authority if not set) |
43+
| `{PREFIX}AUTHENTICATION_SERVICEPULSE_APISCOPES` | (none) | JSON array of API scopes for ServicePulse to request (e.g., `["api://servicecontrol/access_as_user"]`) |
4444

4545
### App.config
4646

47-
| Instance | Key Prefix |
48-
|----------|------------|
49-
| ServiceControl (Primary) | `ServiceControl/` |
50-
| ServiceControl.Audit | `ServiceControl.Audit/` |
51-
| ServiceControl.Monitoring | `Monitoring/` |
47+
| Instance | Key Prefix |
48+
|---------------------------|-------------------------|
49+
| ServiceControl (Primary) | `ServiceControl/` |
50+
| ServiceControl.Audit | `ServiceControl.Audit/` |
51+
| ServiceControl.Monitoring | `Monitoring/` |
5252

5353
```xml
5454
<appSettings>
@@ -66,7 +66,7 @@ These settings are required on the primary ServiceControl instance to provide au
6666

6767
<!-- ServicePulse Settings (Primary Instance Only) -->
6868
<add key="ServiceControl/Authentication.ServicePulse.ClientId" value="{servicepulse-client-id}" />
69-
<add key="ServiceControl/Authentication.ServicePulse.ApiScopes" value="[&quot;api://servicecontrol/access_as_user&quot;]" />
69+
<add key="ServiceControl/Authentication.ServicePulse.ApiScopes" value="["api://servicecontrol/access_as_user"]" />
7070
</appSettings>
7171
```
7272

@@ -85,7 +85,7 @@ set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_APISCOPES=["api://servicecontrol/
8585
### Docker Example
8686

8787
```cmd
88-
docker run -p 33333:33333 -e SERVICECONTROL_AUTHENTICATION_ENABLED=true -e SERVICECONTROL_AUTHENTICATION_AUTHORITY=https://login.microsoftonline.com/{tenant-id}/v2.0 -e SERVICECONTROL_AUTHENTICATION_AUDIENCE=api://servicecontrol -e SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_CLIENTID={servicepulse-client-id} -e "SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_APISCOPES=[\"api://servicecontrol/.default\"]" particular/servicecontrol:latest
88+
docker run -p 33333:33333 -e SERVICECONTROL_AUTHENTICATION_ENABLED=true -e SERVICECONTROL_AUTHENTICATION_AUTHORITY=https://login.microsoftonline.com/{tenant-id}/v2.0 -e SERVICECONTROL_AUTHENTICATION_AUDIENCE=api://servicecontrol -e SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_CLIENTID={servicepulse-client-id} -e SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_APISCOPES=["api://servicecontrol/access_as_user"] particular/servicecontrol:latest
8989
```
9090

9191
### Audit and Monitoring Instances
@@ -117,10 +117,10 @@ When authentication is enabled:
117117

118118
The following endpoints are accessible without authentication, even when authentication is enabled:
119119

120-
| Endpoint | Purpose |
121-
|----------|---------|
122-
| `/api` | API root/discovery - returns available endpoints and API information |
123-
| `/api/authentication/configuration` | Returns authentication configuration for clients like ServicePulse |
120+
| Endpoint | Purpose |
121+
|-------------------------------------|----------------------------------------------------------------------|
122+
| `/api` | API root/discovery - returns available endpoints and API information |
123+
| `/api/authentication/configuration` | Returns authentication configuration for clients like ServicePulse |
124124

125125
These endpoints must remain accessible so clients can discover API capabilities and obtain the authentication configuration needed to acquire tokens.
126126

@@ -157,13 +157,13 @@ When authentication is enabled, HTTPS is strongly recommended for production dep
157157

158158
The default validation settings are recommended for production:
159159

160-
| Setting | Recommendation |
161-
|---------|----------------|
162-
| `ValidateIssuer` | `true` - Prevents tokens from untrusted issuers |
163-
| `ValidateAudience` | `true` - Prevents tokens intended for other applications |
164-
| `ValidateLifetime` | `true` - Prevents expired tokens |
165-
| `ValidateIssuerSigningKey` | `true` - Ensures token signature is valid |
166-
| `RequireHttpsMetadata` | `true` - Ensures OIDC metadata is fetched securely |
160+
| Setting | Recommendation |
161+
|----------------------------|----------------------------------------------------------|
162+
| `ValidateIssuer` | `true` - Prevents tokens from untrusted issuers |
163+
| `ValidateAudience` | `true` - Prevents tokens intended for other applications |
164+
| `ValidateLifetime` | `true` - Prevents expired tokens |
165+
| `ValidateIssuerSigningKey` | `true` - Ensures token signature is valid |
166+
| `RequireHttpsMetadata` | `true` - Ensures OIDC metadata is fetched securely |
167167

168168
### Development Settings
169169

@@ -181,7 +181,7 @@ When `RequireHttpsMetadata` is `true` (the default), the Authority URL must use
181181

182182
## Configuring Identity Providers
183183

184-
### Microsoft Entra ID (Azure AD)
184+
### Microsoft Entra ID Setup
185185

186186
1. Register an application in Azure AD for ServiceControl API
187187
2. Register a separate application for ServicePulse (SPA)
@@ -200,11 +200,11 @@ ServiceControl works with any OIDC-compliant provider. Configure:
200200

201201
The primary ServiceControl instance requires ServicePulse settings because it serves the `/api/auth/config` endpoint that ServicePulse uses to configure its authentication. Audit and Monitoring instances only need the core authentication settings.
202202

203-
| Instance | Requires ServicePulse Settings |
204-
|----------|-------------------------------|
205-
| ServiceControl (Primary) | Yes |
206-
| ServiceControl.Audit | No |
207-
| ServiceControl.Monitoring | No |
203+
| Instance | Requires ServicePulse Settings |
204+
|---------------------------|--------------------------------|
205+
| ServiceControl (Primary) | Yes |
206+
| ServiceControl.Audit | No |
207+
| ServiceControl.Monitoring | No |
208208

209209
## See Also
210210

0 commit comments

Comments
 (0)