feat(auth): add AlbertSSOTokenExchange for server-to-server OIDC token exchange

[prasad-albert]

Summary

• Adds AlbertSSOTokenExchange auth manager — exchanges an OIDC ID token for an Albert access token without browser interaction, using POST /api/v3/login/sso/exchange
• Works with any OIDC-compliant IdP that emits preferred_username (Okta, Auth0, Entra ID, Cognito, Keycloak, etc.); uses expires_in from response to schedule refresh (falls back to 55 min until backend ships the field)
• Albert.from_sso_exchange() and AsyncAlbert.from_sso_exchange() factory methods added; AlbertSSOTokenExchange exported from top-level albert package
• Docs: new sso_exchange.md API reference, OIDC Token Exchange section in authentication.md with provider compatibility table, Google claim-mapping warning, SAML exclusion note, and usage examples

[claude]

Code Review

Issues Found

• [plans/sso-token-exchange.md] Planning artifact committed to the repo. The plans/ directory is not part of the project structure defined in AGENTS.md and this document should not be merged into the main branch.

• [src/albert/core/auth/sso_exchange.py:74] response.json() is called outside the handle_http_errors() context manager, deviating from the pattern in AlbertSSOClient._request_access_token() where .json() is inside the with block. If the server returns a 200 with a non-JSON body, this raises a bare JSONDecodeError instead of being wrapped consistently with the rest of the auth layer.

Summary

2 issues found. Neither is runtime-critical, but the plans/ doc should be removed before merge and the response.json() call should be moved inside the handle_http_errors() block to match the existing pattern.

[prasad-albert]

Code Review

Issues Found

• [plans/sso-token-exchange.md] Planning artifact committed to the repo. The plans/ directory is not part of the project structure defined in AGENTS.md and this document should not be merged into the main branch.
• [src/albert/core/auth/sso_exchange.py:74] response.json() is called outside the handle_http_errors() context manager, deviating from the pattern in AlbertSSOClient._request_access_token() where .json() is inside the with block. If the server returns a 200 with a non-JSON body, this raises a bare JSONDecodeError instead of being wrapped consistently with the rest of the auth layer.

Summary

2 issues found. Neither is runtime-critical, but the plans/ doc should be removed before merge and the response.json() call should be moved inside the handle_http_errors() block to match the existing pattern.

@claude all issues have been addressed.

[claude]

Claude finished @prasad-albert's task in 48s —— View job

---

Verification Complete

• Gather context
• Verify plans/sso-token-exchange.md has been removed — confirmed, file no longer exists in the repo
• Verify response.json() is inside handle_http_errors() block — confirmed, line 75 is now inside the with handle_http_errors(): block (lines 68–75 of sso_exchange.py)
• Final review pass of sso_exchange.py

Both previously identified issues are resolved:

1. Planning artifact removed — plans/sso-token-exchange.md is gone from the branch.
2. response.json() placement fixed — response.json() (line 75) is now correctly inside the with handle_http_errors(): context manager alongside raise_for_status(), matching the pattern in the rest of the auth layer. Any non-JSON 200 response will now be handled consistently rather than raising a bare JSONDecodeError.

The code is clean and ready to merge.