Skip to content

Commit eb9853e

Browse files
warwickschroederwarwickschroeder
committed
Update internal auth docs. Fix issue with server-to-server remote instance checks with auth.
1 parent 1b8cb65 commit eb9853e

File tree

8 files changed

+265
-159
lines changed

8 files changed

+265
-159
lines changed

‎docs/authentication-testing.md‎

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,32 @@ This guide explains how to test authentication configuration for ServiceControl
66

77
- ServiceControl built locally (see main README for build instructions)
88
- **HTTPS configured** - Authentication should only be used over HTTPS. Configure HTTPS using one of the methods described in [HTTPS Configuration](https-configuration.md) before testing authentication scenarios.
9+
- **Identity Provider (IdP) configured** - For real authentication testing (Scenarios 7+), you need an OIDC provider configured with:
10+
- An API application registration (for ServiceControl)
11+
- A client application registration (for ServicePulse)
12+
- API scopes configured and permissions granted
13+
- See [Authentication Configuration](authentication.md#configuring-identity-providers) for setup instructions
914
- curl (included with Windows 10/11, Git Bash, or WSL)
1015
- (Optional) For formatted JSON output: `npm install -g json` then pipe curl output through `| json`
11-
- (Optional) An OIDC provider for full end-to-end testing (e.g., Microsoft Entra ID, Auth0, Okta)
16+
17+
## Enabling Debug Logs
18+
19+
To enable detailed logging for troubleshooting, set the `LogLevel` environment variable before starting each instance:
20+
21+
```cmd
22+
rem ServiceControl Primary
23+
set SERVICECONTROL_LOGLEVEL=Debug
24+
25+
rem ServiceControl.Audit
26+
set SERVICECONTROL_AUDIT_LOGLEVEL=Debug
27+
28+
rem ServiceControl.Monitoring
29+
set MONITORING_LOGLEVEL=Debug
30+
```
31+
32+
**Valid log levels:** `Trace`, `Debug`, `Information` (or `Info`), `Warning` (or `Warn`), `Error`, `Critical` (or `Fatal`), `None` (or `Off`)
33+
34+
Debug logs will show detailed authentication flow information including token validation, claims processing, and authorization decisions.
1235

1336
## Instance Reference
1437

@@ -55,6 +78,7 @@ set SERVICECONTROL_AUTHENTICATION_ENABLED=
5578
set SERVICECONTROL_AUTHENTICATION_AUTHORITY=
5679
set SERVICECONTROL_AUTHENTICATION_AUDIENCE=
5780
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_CLIENTID=
81+
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_AUTHORITY=
5882
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_APISCOPES=
5983
set SERVICECONTROL_AUTHENTICATION_REQUIREHTTPSMETADATA=
6084
set SERVICECONTROL_AUTHENTICATION_VALIDATEISSUER=
@@ -110,6 +134,7 @@ set SERVICECONTROL_AUTHENTICATION_ENABLED=true
110134
set SERVICECONTROL_AUTHENTICATION_AUTHORITY=https://login.microsoftonline.com/common/v2.0
111135
set SERVICECONTROL_AUTHENTICATION_AUDIENCE=api://servicecontrol-test
112136
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_CLIENTID=test-client-id
137+
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_AUTHORITY=https://login.microsoftonline.com/common/v2.0
113138
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_APISCOPES=["api://servicecontrol-test/.default"]
114139
set SERVICECONTROL_AUTHENTICATION_REQUIREHTTPSMETADATA=
115140
set SERVICECONTROL_AUTHENTICATION_VALIDATEISSUER=
@@ -165,6 +190,7 @@ set SERVICECONTROL_AUTHENTICATION_ENABLED=true
165190
set SERVICECONTROL_AUTHENTICATION_AUTHORITY=https://login.microsoftonline.com/common/v2.0
166191
set SERVICECONTROL_AUTHENTICATION_AUDIENCE=api://servicecontrol-test
167192
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_CLIENTID=test-client-id
193+
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_AUTHORITY=https://login.microsoftonline.com/common/v2.0
168194
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_APISCOPES=["api://servicecontrol-test/.default"]
169195
set SERVICECONTROL_AUTHENTICATION_REQUIREHTTPSMETADATA=
170196
set SERVICECONTROL_AUTHENTICATION_VALIDATEISSUER=
@@ -240,6 +266,7 @@ set SERVICECONTROL_AUTHENTICATION_ENABLED=true
240266
set SERVICECONTROL_AUTHENTICATION_AUTHORITY=https://login.microsoftonline.com/common/v2.0
241267
set SERVICECONTROL_AUTHENTICATION_AUDIENCE=api://servicecontrol-test
242268
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_CLIENTID=test-client-id
269+
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_AUTHORITY=https://login.microsoftonline.com/common/v2.0
243270
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_APISCOPES=["api://servicecontrol-test/.default"]
244271
set SERVICECONTROL_AUTHENTICATION_REQUIREHTTPSMETADATA=
245272
set SERVICECONTROL_AUTHENTICATION_VALIDATEISSUER=false
@@ -269,6 +296,7 @@ set SERVICECONTROL_AUTHENTICATION_ENABLED=true
269296
set SERVICECONTROL_AUTHENTICATION_AUTHORITY=
270297
set SERVICECONTROL_AUTHENTICATION_AUDIENCE=api://servicecontrol-test
271298
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_CLIENTID=test-client-id
299+
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_AUTHORITY=
272300
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_APISCOPES=["api://servicecontrol-test/.default"]
273301
set SERVICECONTROL_AUTHENTICATION_REQUIREHTTPSMETADATA=
274302
set SERVICECONTROL_AUTHENTICATION_VALIDATEISSUER=
@@ -312,6 +340,7 @@ set SERVICECONTROL_AUTHENTICATION_ENABLED=true
312340
set SERVICECONTROL_AUTHENTICATION_AUTHORITY=https://login.microsoftonline.com/{tenant-id}/v2.0
313341
set SERVICECONTROL_AUTHENTICATION_AUDIENCE=api://servicecontrol
314342
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_CLIENTID={servicepulse-client-id}
343+
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_AUTHORITY=https://login.microsoftonline.com/{tenant-id}/v2.0
315344
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_APISCOPES=["api://servicecontrol/access_as_user"]
316345
set SERVICECONTROL_AUTHENTICATION_REQUIREHTTPSMETADATA=
317346
set SERVICECONTROL_AUTHENTICATION_VALIDATEISSUER=
@@ -375,6 +404,7 @@ set SERVICECONTROL_AUTHENTICATION_ENABLED=true
375404
set SERVICECONTROL_AUTHENTICATION_AUTHORITY=https://login.microsoftonline.com/{tenant-id}/v2.0
376405
set SERVICECONTROL_AUTHENTICATION_AUDIENCE=api://servicecontrol
377406
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_CLIENTID={servicepulse-client-id}
407+
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_AUTHORITY=https://login.microsoftonline.com/{tenant-id}/v2.0
378408
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_APISCOPES=["api://servicecontrol/access_as_user"]
379409
set SERVICECONTROL_REMOTEINSTANCES=[{"api_uri":"https://localhost:44444"}]
380410
@@ -456,6 +486,7 @@ set SERVICECONTROL_AUTHENTICATION_ENABLED=true
456486
set SERVICECONTROL_AUTHENTICATION_AUTHORITY=https://login.microsoftonline.com/{tenant-id}/v2.0
457487
set SERVICECONTROL_AUTHENTICATION_AUDIENCE=api://servicecontrol
458488
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_CLIENTID={servicepulse-client-id}
489+
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_AUTHORITY=https://login.microsoftonline.com/{tenant-id}/v2.0
459490
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_APISCOPES=["api://servicecontrol/access_as_user"]
460491
set SERVICECONTROL_REMOTEINSTANCES=[{"api_uri":"https://localhost:44444"}]
461492
@@ -574,6 +605,7 @@ set SERVICECONTROL_AUTHENTICATION_ENABLED=true
574605
set SERVICECONTROL_AUTHENTICATION_AUTHORITY=https://login.microsoftonline.com/{tenant-id}/v2.0
575606
set SERVICECONTROL_AUTHENTICATION_AUDIENCE=api://servicecontrol
576607
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_CLIENTID={servicepulse-client-id}
608+
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_AUTHORITY=https://login.microsoftonline.com/{tenant-id}/v2.0
577609
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_APISCOPES=["api://servicecontrol/access_as_user"]
578610
set SERVICECONTROL_REMOTEINSTANCES=[{"api_uri":"https://localhost:44444"}]
579611
@@ -799,6 +831,7 @@ set SERVICECONTROL_AUTHENTICATION_ENABLED=
799831
set SERVICECONTROL_AUTHENTICATION_AUTHORITY=
800832
set SERVICECONTROL_AUTHENTICATION_AUDIENCE=
801833
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_CLIENTID=
834+
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_AUTHORITY=
802835
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_APISCOPES=
803836
set SERVICECONTROL_AUTHENTICATION_VALIDATEISSUER=
804837
set SERVICECONTROL_AUTHENTICATION_VALIDATEAUDIENCE=
@@ -814,6 +847,7 @@ $env:SERVICECONTROL_AUTHENTICATION_ENABLED = $null
814847
$env:SERVICECONTROL_AUTHENTICATION_AUTHORITY = $null
815848
$env:SERVICECONTROL_AUTHENTICATION_AUDIENCE = $null
816849
$env:SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_CLIENTID = $null
850+
$env:SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_AUTHORITY = $null
817851
$env:SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_APISCOPES = $null
818852
$env:SERVICECONTROL_AUTHENTICATION_VALIDATEISSUER = $null
819853
$env:SERVICECONTROL_AUTHENTICATION_VALIDATEAUDIENCE = $null

‎docs/authentication.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,10 +66,13 @@ 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.Authority" value="https://login.microsoftonline.com/{tenant-id}/v2.0" />
6970
<add key="ServiceControl/Authentication.ServicePulse.ApiScopes" value="["api://servicecontrol/access_as_user"]" />
7071
</appSettings>
7172
```
7273

74+
> **Note:** The `ServicePulse.Authority` must be set explicitly. The `Audience` for ServicePulse is reused from the main `Authentication.Audience` setting.
75+
7376
## Examples
7477

7578
### Microsoft Entra ID (Azure AD)
@@ -79,13 +82,14 @@ set SERVICECONTROL_AUTHENTICATION_ENABLED=true
7982
set SERVICECONTROL_AUTHENTICATION_AUTHORITY=https://login.microsoftonline.com/{tenant-id}/v2.0
8083
set SERVICECONTROL_AUTHENTICATION_AUDIENCE=api://servicecontrol
8184
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_CLIENTID={servicepulse-client-id}
85+
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_AUTHORITY=https://login.microsoftonline.com/{tenant-id}/v2.0
8286
set SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_APISCOPES=["api://servicecontrol/access_as_user"]
8387
```
8488

8589
### Docker Example
8690

8791
```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/access_as_user"] particular/servicecontrol:latest
92+
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_AUTHORITY=https://login.microsoftonline.com/{tenant-id}/v2.0 -e SERVICECONTROL_AUTHENTICATION_SERVICEPULSE_APISCOPES=["api://servicecontrol/access_as_user"] particular/servicecontrol:latest
8993
```
9094

9195
### Audit and Monitoring Instances
@@ -120,6 +124,9 @@ The following endpoints are accessible without authentication, even when authent
120124
| Endpoint | Purpose |
121125
|-------------------------------------|----------------------------------------------------------------------|
122126
| `/api` | API root/discovery - returns available endpoints and API information |
127+
| `/api/instance-info` | Returns instance configuration information |
128+
| `/api/configuration` | Returns instance configuration information (alias) |
129+
| `/api/configuration/remotes` | Returns remote instance configurations for server-to-server fetching |
123130
| `/api/authentication/configuration` | Returns authentication configuration for clients like ServicePulse |
124131

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

‎docs/forward-headers-testing.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,25 @@ This guide explains how to test forwarded headers configuration for ServiceContr
99
- (Optional) For formatted JSON output: `npm install -g json` then pipe curl output through `| json`
1010
- All commands assume you are in the respective project directory
1111

12+
## Enabling Debug Logs
13+
14+
To enable detailed logging for troubleshooting, set the `LogLevel` environment variable before starting each instance:
15+
16+
```cmd
17+
rem ServiceControl Primary
18+
set SERVICECONTROL_LOGLEVEL=Debug
19+
20+
rem ServiceControl.Audit
21+
set SERVICECONTROL_AUDIT_LOGLEVEL=Debug
22+
23+
rem ServiceControl.Monitoring
24+
set MONITORING_LOGLEVEL=Debug
25+
```
26+
27+
**Valid log levels:** `Trace`, `Debug`, `Information` (or `Info`), `Warning` (or `Warn`), `Error`, `Critical` (or `Fatal`), `None` (or `Off`)
28+
29+
Debug logs will show detailed forwarded headers processing and trust evaluation information.
30+
1231
## Instance Reference
1332

1433
| Instance | Project Directory | Default Port | Environment Variable Prefix |

0 commit comments

Comments
 (0)