Enhance JWT authentication for MCP server compatibility

[michaellwest]

Summary

While building the SPE MCP Server, we identified several areas where SPE's SharedSecretAuthenticationProvider could be enhanced to improve interoperability and security for automated clients.

Current Behavior

The SharedSecretAuthenticationProvider in Spe.Core.Settings.Authorization performs manual JWT validation:

• Decodes Base64Url header/payload manually
• Validates alg is HS256
• Validates iss against AllowedIssuers list (default: "SPE Remoting", "Web API")
• Validates aud against request authority or AllowedAudiences
• Verifies HMAC-SHA256 signature using shared secret
• Extracts name claim for Sitecore user context

Recommendations

1. Support standard JWT libraries (HS256 + HS512)

Currently only HS256 is supported. Standard JWT libraries (e.g., System.IdentityModel.Tokens.Jwt) default to HS512 for HMAC signing. Supporting both would make it easier for third-party clients to integrate without implementing manual JWT construction.

2. Improve error diagnostics

When authentication fails, the current implementation returns a generic 401 with no indication of why it failed (wrong algorithm? invalid issuer? expired token? bad signature?). Adding a debug/verbose logging mode would significantly reduce integration debugging time.

3. Add iat (issued-at) and nbf (not-before) claim validation

Standard JWT security practice includes validating iat and nbf claims to prevent token replay. Currently only exp is checked.

4. Consider configurable token lifetime validation

The MCP server uses 30-second token lifetimes for security. SPE could optionally enforce a maximum token lifetime (e.g., reject tokens with exp more than 5 minutes in the future).

5. Support scope claim for fine-grained authorization

A scope claim (e.g., read-only, content-edit, admin) would allow SPE to enforce authorization at the remoting layer. This would complement the MCP server's client-side sandboxing with server-side enforcement. This could map to SPE's existing security roles.

Context

These recommendations emerged from building the MCP server and testing against SPE's remoting API. The MCP server currently works around these limitations by implementing manual HS256 JWT construction that precisely matches SPE's validation logic. See: https://github.com/SitecorePowerShell/mcp-server/blob/main/src/SpeMcpServer/Client/AuthHandler.cs

[michaellwest]

Test Plan

Integration tests added in tests/integration/Remoting.JwtClaims.Tests.ps1 (auto-discovered by Run-RemotingTests.ps1).

Group 1: Backward Compatibility

• Token without iat/nbf claims is accepted (HTTP 200)

Group 2: Valid iat/nbf Claims

• Token with iat set to current time is accepted
• Token with nbf set to current time is accepted
• Token with both iat and nbf set to current time is accepted
• Token with nbf slightly in the past is accepted

Group 3: Invalid iat/nbf Claims

• Token with nbf 10 minutes in the future is rejected (HTTP 401)
• Token with iat 10 minutes in the future is rejected (HTTP 401)
• Token with nbf 60 seconds in the future is rejected (outside 30s clock skew)

Group 4: Clock Skew Tolerance (30 seconds)

• Token with nbf 10 seconds in the future is accepted (within tolerance)
• Token with iat 10 seconds in the future is accepted (within tolerance)

Group 5: New-Jwt Client Module Parameters

• -IncludeIssuedAt switch adds iat claim to payload
• -NotBefore parameter adds nbf claim to payload
• Explicit -IssuedAt value is used verbatim in the iat claim
• Omitting -IncludeIssuedAt and -NotBefore produces no iat/nbf claims

Manual Verification

• PowerShellLog.Warn messages appear in Sitecore log for each rejection reason
• PowerShellLog.Debug entry log shows issuer, audience, and algorithm on token validation
• maxTokenLifetimeSeconds config element (commented out by default) activates lifetime enforcement when uncommented

[michaellwest]

Addendum: Lifetime Enforcement Tests (Phase 2 - Security Enforced)

Added to Remoting.Security.Enforced.Tests.ps1 (runs with maxTokenLifetimeSeconds=300 in test config):

• Token with 30s lifetime + iat accepted (under 300s max)
• Token with 300s lifetime + iat accepted (at the limit)
• Token with 3600s lifetime + iat rejected (exceeds 300s max)
• Token with 3600s lifetime but no iat accepted (lifetime check requires iat)

[michaellwest]

Implementation Complete

Merged to release/9.0 in 605d9d92b.

What was done

Already implemented (no work needed):

• Recommendation 1 (HS256 + HS512) -- ComputeHash already supported HS256/384/512
• Recommendation 5 (scope claim) -- TokenPayload.Scope and TokenValidationResult.Scope already wired through

Implemented in this change:

Recommendation 2 -- Improved error diagnostics

• Added PowerShellLog.Warn with specific failure reason to every IsValid* method
• Added PowerShellLog.Debug entry log with token metadata (issuer, audience, algorithm)

Recommendation 3 -- iat and nbf claim validation

• Added Iat and Nbf properties to TokenPayload
• Added IsValidNotBefore and IsValidIssuedAt validators with 30-second clock skew tolerance
• Optional claims: tokens without iat/nbf are still accepted (backward compatible)

Recommendation 4 -- Configurable maximum token lifetime

• Added MaxTokenLifetimeSeconds property (default 0 = disabled)
• Added IsValidTokenLifetime validator: rejects when exp - iat > MaxTokenLifetimeSeconds
• Requires both MaxTokenLifetimeSeconds > 0 and iat > 0 to enforce
• Commented-out config element added to Spe.config

Client module (New-Jwt):

• Added -IncludeIssuedAt switch, -IssuedAt (explicit value), and -NotBefore parameters

Files changed

• src/Spe/Core/Settings/Authorization/SharedSecretAuthenticationProvider.cs
• src/Spe/App_Config/Include/Spe/Spe.config
• Modules/SPE/New-Jwt.ps1
• tests/integration/Remoting.JwtClaims.Tests.ps1 (new -- 14 test cases)
• tests/integration/Remoting.Security.Enforced.Tests.ps1 (4 lifetime enforcement tests)
• tests/configs/test/z.Spe.Security.Tests.config (maxTokenLifetimeSeconds=300)