feat(auth): add ADFS SSO authorization provider

[calculus-ask]

🔗 Related Issue

Closes #
#3532

---

📝 Summary

Added ADFS Authorization
Now UI Login page displays one login button "ADFS Login". Two buttons issue resolved
Doc Link
/docs/docs/sso-adfs-testing.md

---

🏷️ Type of Change

• [ YES] Bug fix
• [ YES] Feature / Enhancement
• [YES ] Documentation
• Refactor
• Chore (deps, CI, tooling)
• Other (describe below)

---

✅ Checklist

• [ yes] Code formatted (make black isort pre-commit)
• [ yes] Tests added/updated for changes
• [ yes] Documentation updated (if applicable)
• [yes ] No secrets or credentials committed

---

📓 Notes (optional)

[calculus-ask]

make pylint
🐛 pylint mcpgateway (parallel)...

---

Your code has been rated at 10.00/10 (previous run: 10.00/10, +0.00)

[calculus-ask]

Unit test: pytest tests/unit/mcpgateway/services/test_sso_service.py added

[calculus-ask]

funtional test - after deployment its working

[crivetimihai]

Thanks @calculus-ask. ADFS SSO is useful for enterprise deployments. Please rebase onto main to resolve the merge conflicts.

[rakdutta]

✅ APPROVED - Ready to Merge

---

📊 Overview

Title: feat(auth): add ADFS SSO authorization provider
Author: @calculus-ask (Santhana Krishnan)
Changes: +2,274 / -368 lines across 16 files
Related Issue: #3532
Quality Rating: ⭐⭐⭐⭐⭐ Excellent

---

🎯 What It Does

Adds comprehensive ADFS (Active Directory Federation Services) SSO authentication with:

1. Full ADFS OAuth/OIDC integration - Extracts user info from ID token (ADFS doesn't support GET on userinfo endpoint)
2. Smart email normalization - Handles Windows domain formats: user@domain.com, DOMAIN\username, plain username
3. Enhanced OAuth error handling - RFC 6749 compliant with user-friendly error messages
4. Provider lifecycle management - Optional auto-disable for unconfigured providers (backward compatible)
5. Comprehensive testing - 97% coverage with 49 new test functions

---

✅ Strengths

• Security: SecretStr usage, log sanitization, JWT verification, secrets baseline updated correctly
• Code Quality: Excellent type hints, docstrings, clear separation of concerns, follows all project standards
• Testing: Integration tests (866 lines), unit tests, edge cases covered, doctests included
• Documentation: Complete tutorial with curl examples, configuration guide, troubleshooting section
• Backward Compatibility: Feature flags default to safe values, no breaking changes, no database migrations needed
• UX: Graceful OAuth error handling, clear error messages, resolves "two buttons" UI issue

---

⚠️ Minor Notes (Non-Blocking)

1. Coverage config change (parallel = true) - should mention in PR description
2. Placeholder userinfo_url - ADFS doesn't use it but DB requires it (acceptable, documented)
3. Verbose logging - 27 new log statements (acceptable for new feature debugging)

---

🔍 Technical Assessment

┌─────────────────┬────────────┬───────────────────────────────────────────┐
│ Area │ Rating │ Notes │
├─────────────────┼────────────┼───────────────────────────────────────────┤
│ Code Quality │ ⭐⭐⭐⭐⭐ │ Professional-grade implementation │
├─────────────────┼────────────┼───────────────────────────────────────────┤
│ Security │ ⭐⭐⭐⭐⭐ │ Strong, no vulnerabilities identified │
├─────────────────┼────────────┼───────────────────────────────────────────┤
│ Testing │ ⭐⭐⭐⭐⭐ │ 97% coverage, comprehensive scenarios │
├─────────────────┼────────────┼───────────────────────────────────────────┤
│ Documentation │ ⭐⭐⭐⭐⭐ │ Complete, copy-paste ready examples │
├─────────────────┼────────────┼───────────────────────────────────────────┤
│ Maintainability │ ⭐⭐⭐⭐ │ Well-isolated ADFS logic, clear structure │
└─────────────────┴────────────┴───────────────────────────────────────────┘

---

🚀 Recommendation

✅ APPROVE - Ready for Production

Risk Level: Low
Confidence: High

This PR is exceptionally well-executed with professional-grade implementation, comprehensive testing, and strong security practices. The ADFS email normalization logic is particularly well-designed for handling various Windows domain formats.

Once pre-commit error resolve . Ready to merge

[crivetimihai]

Review: feat(auth): add ADFS SSO authorization provider

Rebased, reviewed, and cleaned up. The original 59 commits (including 9 merge commits with unrelated changes) have been squashed into a single clean commit on top of current main.

Changes made during review

Bug fixes:

• ADFS callback was unreachable in production — The OIDC id_token verification block in handle_oauth_callback_with_tokens hard-failed for all OIDC providers when _verify_oidc_id_token returned None. Since ADFS's provider_type is "oidc", on-prem ADFS without a discoverable JWKS endpoint would fail before the ADFS-specific _get_user_info path was ever reached. Fixed by excluding ADFS from the OIDC verification gate.
• OAuth error callbacks returned 422 — state was a required query parameter, so if a provider returned an error without state, FastAPI rejected the request before the error handler could translate it into a login redirect. Made state optional with explicit validation after error handling.
• Bootstrap allowed incomplete ADFS config — Provider was created when only enabled, client_id, and authorization_url were set, but token_url could be None, leaving a broken login button. Added token_url to the guard condition.

Consistency improvements:

• ADFS normalization now uses the shared _extract_groups_and_roles() utility and _build_normalized_user_info() helper, consistent with all other SSO providers. Previously it had inline manual extraction that didn't handle string-valued groups or the roles claim.
• ADFS path in _get_user_info now prefers already-verified id_token claims when available (e.g., ADFS with discoverable JWKS), falling back to unverified decode only for on-prem ADFS without JWKS.

Documentation fixes (5):

• Wrong admin API path (/admin/sso/providers → /auth/sso/admin/providers)
• Login endpoint returns JSON, not a redirect — rewrote curl examples
• Response format corrected from wrapped object to bare list
• Claim priority order in troubleshooting section corrected to match code (email > preferred_username > upn > unique_name)
• Non-existent log line replaced with actual log messages

Test additions:

• 4 new OAuth error callback tests (access_denied mapping, server_error mapping, unknown error fallback, missing state rejection)
• Fixed 2 test expectations to match corrected behavior (set-based group comparison, string groups handled by shared utility)

Verification

• 327 unit tests pass
• 15 integration tests (skipped without --with-integration)
• flake8, black, isort, ruff all clean
• Coverage: sso_service.py 99%, sso.py 98%, sso_bootstrap.py 97%