Add CLM Migration Guide for SPE 9.0

[michaellwest]

Context

SPE 9.0 introduces Constrained Language Mode (CLM) as an opt-in security feature (#1426 in Console repo). A migration guide is needed to help existing installations adopt CLM safely.

Proposed Location

Either security/clm-migration.md as a standalone page, or a section in the release notes. A standalone page is recommended since it will be referenced long-term.

Content to Cover

Key Message: Fully Opt-In, No Breaking Changes

• Existing installations see zero behavior change after upgrading to SPE 9.0
• All services default to unrestricted profile (FullLanguage, no restrictions)
• CLM features activate only when an admin explicitly sets a profile

Recommended Rollout Steps

Step 1: Upgrade and Verify

• Install SPE 9.0 package
• Verify all existing remoting scripts continue to work unchanged
• No configuration changes needed at this stage

Step 2: Audit Mode (Dry Run)

• Set a profile on the remoting service with enforcement="Audit":

  <remoting profile="read-only" enforcement="Audit" />

• Monitor Sitecore logs for SPE.Security [VIOLATION] entries
• Identify which scripts use blocked commands or access restricted paths
• No scripts are actually blocked in audit mode

Step 3: Remediate Scripts

• Review audit log violations
• Update scripts to avoid blocked commands where possible
• Register essential scripts as trusted if they legitimately need CLM bypass
• Create item-based profile overrides if built-in profiles need customization

Step 4: Enforce

• Switch from audit to enforce mode:

  <remoting profile="read-only" enforcement="Enforce" />

• Monitor for 403 responses from remoting clients
• Adjust trusted scripts or profile overrides as needed

Step 5: Per-Consumer API Keys (Optional)

• Create API Key items for different consumers
• Assign appropriate profiles per consumer
• Configure throttling for external consumers
• Migrate clients from shared secret to per-key secrets

What Changes for Existing Scripts

Aspect	Before 9.0	After 9.0 (default)	After 9.0 (with profile)
Language mode	FullLanguage	FullLanguage	Per profile
Command access	All	All	Filtered by profile
.NET types	Unrestricted	Unrestricted	Blocked in ConstrainedLanguage
Item access	All paths	All paths	Filtered by path restrictions
Auth method	Shared secret / JWT	Same (unchanged)	Same + API Keys

Pipeline Scripts

• Pipeline scripts (LoggedIn, LoggingIn, Logout) always run in FullLanguage regardless of profile
• No action needed for pipeline customizations

Troubleshooting Migration Issues

• "403 Forbidden" with X-SPE-BlockedCommand header: command is blocked by profile
• "429 Too Many Requests": API Key throttle limit exceeded
• Scripts failing silently: check audit logs for violations in audit mode
• Hash mismatch on trusted scripts: re-register with updated hash after script changes

Related

• Depends on Console repo feature/clm branch (#1426)
• Links to: Add Restriction Profiles page (security/restriction-profiles.md) #41, Add API Keys page (security/api-keys.md) #42, Add Trusted Scripts page (security/trusted-scripts.md) #43, Add Item Path Restrictions page (security/item-path-restrictions.md) #44, Update web-services.md with restriction profile support #45, Update remoting.md with bearer auth, API keys, and error handling #46