feat: add get_profile_and_token_from_id_token for OIDC ID token exchange (4.16.0 backport)

[jonatascastro12]

Summary

Backport onto the 4.x line for customers who need the /sso/token token-exchange grant (native MSAL sign-in: a mobile app gets an Entra ID token and the backend exchanges it for a WorkOS profile) but are still on 4.x and can't move to 10.x yet.

Adds a new, additive SSO method:

sso.get_profile_and_token_from_id_token(id_token, organization_id)

It POSTs the token-exchange grant (grant_type=urn:ietf:params:oauth:grant-type:token-exchange, subject_token, subject_token_type=...:id_token, organization_id) to /sso/token and returns the same WorkOSProfileAndToken as the authorization-code flow. Existing get_profile_and_token is untouched.

Version bumped 4.15.0 → 4.16.0 (additive, non-breaking). Added a unit test mirroring the existing get_profile_and_token test; pytest tests/test_sso.py passes locally.

Why a 4.x backport (and why isolated)

• The feature only exists on the 4.x branch as a hand-written method; the 10.x line is oagen-generated and will get this through codegen separately. This branch does not touch main / 10.x.
• Publishing 4.16.0 will not change pip install workos defaults: PyPI serves the highest version (10.2.0) as latest, so only an explicit workos==4.16.0 pin picks this up.
• Base is a new 4.x branch cut from v4.15.0 so the diff is just this change.

⚠️ Draft — needs a maintainer to own the release

I can't publish to PyPI. Before release, please confirm the 4.x release/CI process still works from this branch, the version bump is where you want it, and whether you want the same method mirrored into the 10.x codegen path so it doesn't regress on upgrade.

🤖 Generated with Claude Code

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

[greptile-apps]

Greptile Summary

The PR adds an SSO helper that exchanges an externally issued OIDC ID token for a WorkOS profile and access token, and bumps the 4.x package version to 4.16.0.

• Adds token-exchange grant and subject-token-type constants.
• Sends the ID token, organization, and existing client credentials to /sso/token.
• Adds response-model coverage for the new method, although the test does not validate its wire payload.
• Updates the package version from 4.15.0 to 4.16.0.

Confidence Score: 4/5

The PR appears safe to merge, with the non-blocking caveat that its new unit test should validate the token-exchange request payload.

The implementation follows the existing SSO request and response paths, and the package version is wired correctly; the remaining concern is that malformed token-exchange fields could pass the added response-only test.

Files Needing Attention: tests/test_sso.py

Important Files Changed

Filename	Overview
workos/sso.py	Adds the OIDC ID-token exchange method using the existing SSO token endpoint and response model; no concrete behavioral defect was established.
tests/test_sso.py	Covers response construction but does not assert the new method's endpoint or token-exchange request payload.
workos/about.py	Bumps the authoritative package version to 4.16.0 consistently with existing release conventions.

Sequence Diagram

sequenceDiagram
    participant App as Backend application
    participant SDK as WorkOS Python SDK
    participant API as WorkOS /sso/token
    App->>SDK: get_profile_and_token_from_id_token(id_token, organization_id)
    SDK->>API: POST token-exchange grant and credentials
    API-->>SDK: profile and access_token
    SDK-->>App: WorkOSProfileAndToken

Loading

Prompt To Fix All With AI

### Issue 1
tests/test_sso.py:452
**Token-exchange payload remains untested**

This mock verifies only response deserialization and never inspects the outgoing request, so incorrect `grant_type`, `subject_token`, `subject_token_type`, or `organization_id` values can pass the test and fail only against the live API. Assert the endpoint, method, and exact JSON body for this new flow.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "Add get_profile_and_token_from_id_token ..." | Re-trigger Greptile}

[greptile-apps]

Token-exchange payload remains untested

This mock verifies only response deserialization and never inspects the outgoing request, so incorrect grant_type, subject_token, subject_token_type, or organization_id values can pass the test and fail only against the live API. Assert the endpoint, method, and exact JSON body for this new flow.

Prompt To Fix With AI

This is a comment left during a code review.
Path: tests/test_sso.py
Line: 452

Comment:
**Token-exchange payload remains untested**

This mock verifies only response deserialization and never inspects the outgoing request, so incorrect `grant_type`, `subject_token`, `subject_token_type`, or `organization_id` values can pass the test and fail only against the live API. Assert the endpoint, method, and exact JSON body for this new flow.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.