docs: architecture diagrams and MDM rollout guidance for Claude Code + Okta JWT auth

[devin-ai-integration]

Summary

The Claude Code + Okta JWT page explained how to configure the pieces but not how the pieces fit together or how to ship them to a fleet, which is the part enterprises ask about once they have validated the flow by hand. Adds two mermaid diagrams (component view of workstation, Okta, proxy, DB, providers; sequence view of first-run device grant, per-request JWKS validation plus user upsert, and silent refresh on later runs) and replaces the three-sentence rollout note with a real rollout section.

Rollout now covers why managed settings rather than ~/.claude/settings.json (they cannot be overridden locally, so they are what pins traffic to the proxy), the per-platform managed-settings paths, helper install location and permissions, and why the per-user token cache at $HOME/.claude/okta_token.json is what makes a shared SSH lab server safe.

Windows was previously unaddressed. Adds Intune/GPO delivery via the Settings value under HKLM\SOFTWARE\Policies\ClaudeCode, a .cmd shim so apiKeyHelper invokes PowerShell without execution-policy or quoting problems, and a PowerShell port of the bash helper with the same cache-then-refresh-then-device-flow shape:

if (cached and not expiring) { print access_token; exit }
if (cached.refresh_token) { POST /v1/token grant_type=refresh_token -> save; exit }
POST /v1/device/authorize -> print verification URL on stderr -> poll /v1/token until approved

Invoke-RestMethod throws on Okta's 400 authorization_pending, so the helper reads the body out of $_.ErrorDetails.Message instead of treating it as fatal, and the cache is locked down with icacls /inheritance:r. The PowerShell logic was exercised against a mock device-grant server across all three paths (device flow, cache hit, expired then refresh); the icacls line is Windows-only and unverified here.

Closes out with operational guidance: pilot first and confirm attribution under Internal Users, upgrade/rollback by redeploying the file, and how to read the two common failure modes (unexpected sign-in prompts mean a revoked or expired refresh token; auth errors usually mean an audience mismatch).

Link to Devin session: https://app.devin.ai/sessions/b49f63ae7081413882a0be7d57eff15f
Requested by: @mateo-berri

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
litellm	Ready	Preview	Aug 18, 2026 8:16am