[vgunjic]

🔗 Epic / Issue

Closes #5306

---

🚀 Summary

JIT-provisions missing users during OAuth-enabled virtual-server MCP authentication by reusing ContextForge's trusted SSO provider path. The provider's existing email_claim mapping now selects the same local principal for browser SSO and MCP OAuth flows.

---

📏 Reviewability

• This PR has one clear purpose
• The linked issue is not labeled triage
• Unrelated behavior, including customized permission-error responses, is excluded
• Tests are included with the code they validate

---

🧪 Checks

• Affected unit suites pass for OAuth authentication, SSO provisioning, claim normalization, and external IdP authentication
• Changed-line coverage is 100% (diff-cover, 79 executable lines)
• Pinned Black, Ruff, Pylint, Bandit, and Interrogate checks pass for changed production code
• git diff --check passes
• Full parallel suite: one pre-existing Hypothesis 200 ms deadline check was timing-sensitive (261 ms initially, 172 ms on replay); it passed when rerun in isolation
• CHANGELOG not updated; release changelog entries are maintained with release preparation

---

🔄 Rebuilt on main (663938b, 2026-10-30)

Upstream rewrote main's history on 22 Oct (secret purge), which left this PR's base commit unreachable and the diff unreadable. The branch is rebuilt from current main with the same single commit (cherry-pick, no conflicts; auto-merges in .env.example and the transport import block after #7254). One file added since the last revision: .secrets.baseline, refreshed by the detect-secrets hook because the new lines in docs/docs/manage/sso.md move two existing entries (line numbers only, no new entries).

On the rebuilt branch: the auth, SSO and streamable-transport unit suites pass (1659 passed, 1 skipped); all pre-commit hooks pass (ruff 0.15.16 check and format, bandit, interrogate, detect-secrets).

Relation to the SSO user provisioning API (#7180, #7219, #7183). That API lets an administrator create accounts before the first login. This PR covers the case without that step: a headless MCP client whose user has never logged in, presenting a valid OAuth token to an OAuth-enabled virtual server. Both use the same trusted-provider rules.

---

📓 Notes

Provisioning remains disabled unless SSO_API_TOKEN_AUTH_ENABLED=true. It also requires an enabled provider matched by verified issuer with both trusted_for_api_auth=true and auto_create_users=true.

The shared SSO path continues to enforce email verification, trusted domains, admin approval, account linking, role mapping, and team mapping. A configured email_claim is authoritative and fails closed when missing or invalid rather than falling back to a contact-email claim. Existing and disabled local-user behavior is unchanged.

This also persists email_verified_at after the shared SSO verification gate accepts a newly created or linked user.

[vgunjic]

Rebased onto current main (86af292); the two conflicts are resolved and described above. The PR still covers the gap from #5306: a first-time headless MCP user whose valid OAuth token reaches an OAuth-enabled virtual server. The new SSO provisioning API (#7180, #7219, #7183) covers accounts that an admin creates beforehand; this PR covers first use without that step, under the same trusted-provider rules. Unit suites pass except one test that fails the same way on main. Could a maintainer take a look?

[vgunjic]

Rebased onto current main; the only conflict was an import line in the transport.

[vgunjic]

Rebuilt on current main after the 22 Oct history rewrite; one commit again, pre-commit and the auth/SSO/transport suites pass locally. The workflow runs are waiting for approval (fork). @msureshkumar88, could you approve the runs and take a look when you have a moment? Thanks.