Skip to content

Automate browser based workflows with AI

MCP OAuth org selection for multi-org users (#5699)

Marc Kelechavad90237fc1b31
diff --git a/skyvern/cli/core/mcp_http_auth.py b/skyvern/cli/core/mcp_http_auth.py
index 08f963516..b403bfc5b 100644
--- a/skyvern/cli/core/mcp_http_auth.py
+++ b/skyvern/cli/core/mcp_http_auth.py
@@ -7,8 +7,10 @@ import json
import os
import time
from collections import OrderedDict
+from collections.abc import Awaitable, Callable
from dataclasses import dataclass
from threading import RLock
+from typing import Any, cast
from urllib.parse import urlsplit, urlunsplit
import structlog
@@ -56,11 +58,15 @@ _MAX_VALIDATION_RETRIES = 2
_RETRY_DELAY_SECONDS = 0.25
_OAUTH_UNAVAILABLE_MSG = "OAuth authentication requires cloud deployment"
_OAUTH_SERVICE_UNAVAILABLE_MSG = "Authentication service temporarily unavailable"
+_OAUTH_MISSING_ORG_CONTEXT_MSG = "Bearer token missing organization context"
_DEFAULT_REMOTE_BASE_URL = "https://api.skyvern.com"
_MCP_REALM = "mcp"
_RESOURCE_CLAIM_KEYS = ("resource",)
_TOKEN_CLOCK_SKEW_SECONDS = 60.0
+_OrgEntitiesGetter = Callable[[str, str], Awaitable[list[Any]]]
+_OrgAuthTokenGetter = Callable[[str, OrganizationAuthTokenType], Awaitable[Any | None]]
+
@dataclass(frozen=True)
class MCPAPIKeyValidation:
@@ -76,6 +82,13 @@ class _OAuthResolution:
validation: MCPAPIKeyValidation
+class MissingOrgContextError(HTTPException):
+ """Raised when an MCP OAuth bearer token lacks an explicit org claim."""
+
+ def __init__(self) -> None:
+ super().__init__(status_code=401, detail=_OAUTH_MISSING_ORG_CONTEXT_MSG)
+
+
def _canonical_mcp_url(base_url: str | None = None) -> str:
"""Return the canonical MCP resource URI with no trailing slash.
@@ -229,12 +242,48 @@ async def _fetch_oauth_userinfo(bearer_token: str, issuer_url: str) -> dict[str,
return response_body
+def _get_oauth_org_auth_methods(db: object) -> tuple[_OrgEntitiesGetter | None, _OrgAuthTokenGetter | None]:
+ # OSS shape: methods sit directly on the DB instance (or unit-test mock).
+ get_entities = getattr(db, "get_organization_entities", None)
+ get_auth_token = getattr(db, "get_valid_org_auth_token", None)
+ if callable(get_entities) and callable(get_auth_token):
+ return cast(_OrgEntitiesGetter, get_entities), cast(_OrgAuthTokenGetter, get_auth_token)
+
+ # Cloud shape: methods live on a nested ``organizations`` repository.
+ # Delegated to ``AgentFunction.resolve_mcp_oauth_org_lookups`` so this
+ # OSS-synced module doesn't encode knowledge of CloudAgentDB's layout.
+ cloud_lookups = app.AGENT_FUNCTION.resolve_mcp_oauth_org_lookups(db)
+ if cloud_lookups is not None:
+ get_entities, get_auth_token = cloud_lookups
+ return cast(_OrgEntitiesGetter, get_entities), cast(_OrgAuthTokenGetter, get_auth_token)
+
+ return None, None
+
+
+def _extract_explicit_oauth_org_id(payload: dict[str, object]) -> str:
+ """Return the Clerk org id from supported org-scoped JWT claim shapes.
+
+ Our Clerk template uses `org_id`; Clerk's org-scoped session JWTs can also
+ expose the active organization as compact claim `o.id`.
+ """
+ org_id_claim = payload.get("org_id")
+ if isinstance(org_id_claim, str) and org_id_claim:
+ return org_id_claim
+
+ compact_org_claim = payload.get("o")
+ if isinstance(compact_org_claim, dict):
+ compact_org_id = compact_org_claim.get("id")
+ if isinstance(compact_org_id, str) and compact_org_id:
+ return compact_org_id
+
+ raise MissingOrgContextError()
+
+
async def _resolve_oauth_subject_to_org(
payload: dict[str, object],
db: object,
) -> _OAuthResolution:
- get_entities = getattr(db, "get_organization_entities", None)
- get_auth_token = getattr(db, "get_valid_org_auth_token", None)
+ get_entities, get_auth_token = _get_oauth_org_auth_methods(db)
if not callable(get_entities) or not callable(get_auth_token):
LOG.debug(
"MCP OAuth DB object is missing required auth methods",
@@ -244,19 +293,15 @@ async def _resolve_oauth_subject_to_org(
)
raise HTTPException(status_code=401, detail=_OAUTH_UNAVAILABLE_MSG)
- entity_id = payload.get("sub")
- if not isinstance(entity_id, str) or not entity_id:
+ subject = payload.get("sub")
+ if not isinstance(subject, str) or not subject:
raise HTTPException(status_code=401, detail="Bearer token missing subject claim")
- entity_type = "user"
- org_id_claim = payload.get("org_id")
- if isinstance(org_id_claim, str) and org_id_claim:
- entity_type = "organization"
- entity_id = org_id_claim
+ clerk_org_id = _extract_explicit_oauth_org_id(payload)
- org_entities = await get_entities(entity_id, entity_type)
+ org_entities = await get_entities(clerk_org_id, "organization")
if not org_entities:
- LOG.info("MCP OAuth: no org mapping for entity", entity_id=entity_id, entity_type=entity_type)
+ LOG.info("MCP OAuth: no org mapping for entity", entity_id=clerk_org_id, entity_type="organization")
raise HTTPException(status_code=401, detail="No organization found for this user")
org_id = org_entities[0].organization_id
@@ -451,9 +496,22 @@ async def validate_mcp_oauth_token(bearer_token: str) -> _OAuthResolution:
signing_key,
algorithms=["RS256"],
leeway=_TOKEN_CLOCK_SKEW_SECONDS,
+ # PyJWT's built-in `aud` check is intentionally skipped here.
+ # `_validate_oauth_token_contract` below calls
+ # `_validate_token_audience`, which compares the token's
+ # `aud` against the canonical MCP resource URI after
+ # normalizing trailing slashes on both sides — PyJWT does
+ # exact string match and would reject `.../mcp/` tokens
+ # against `.../mcp` (or vice versa). The audience check
+ # is NOT being skipped, only relocated.
+ options={"verify_aud": False},
+ )
+ except (InvalidKeyError, PyJWTError) as exc:
+ LOG.info(
+ "MCP OAuth Bearer token failed JWT verification",
+ error_type=type(exc).__name__,
+ error_message=str(exc),
)
- except (InvalidKeyError, PyJWTError):
- LOG.info("MCP OAuth Bearer token failed JWT verification")
raise HTTPException(status_code=401, detail="Invalid Bearer token")
_validate_oauth_token_contract(
diff --git a/skyvern/forge/agent_functions.py b/skyvern/forge/agent_functions.py
index 0f5798e71..5f6d34d45 100644
--- a/skyvern/forge/agent_functions.py
+++ b/skyvern/forge/agent_functions.py
@@ -464,6 +464,18 @@ class AgentFunction:
"""
return AgentDB(database_string, debug_enabled=debug_enabled)
+ def resolve_mcp_oauth_org_lookups(self, db: object) -> tuple[Any, Any] | None:
+ """Return ``(get_organization_entities, get_valid_org_auth_token)`` callables
+ bound to the cloud DB's nested organizations repository.
+
+ OSS no-op — the OSS path in ``_get_oauth_org_auth_methods`` probes the
+ flat shape directly. Cloud overrides this to expose the
+ ``CloudAgentDB.organizations`` repository's methods so the OSS-synced
+ ``mcp_http_auth`` module doesn't need to know about cloud-specific
+ DB layout.
+ """
+ return None
+
async def validate_step_execution(
self,
task: Task,
diff --git a/tests/unit/force_stub_app.py b/tests/unit/force_stub_app.py
index 40bb9d7ce..dc334f478 100644
--- a/tests/unit/force_stub_app.py
+++ b/tests/unit/force_stub_app.py
@@ -1,4 +1,4 @@
-from unittest.mock import AsyncMock
+from unittest.mock import AsyncMock, MagicMock
from skyvern.forge import set_force_app_instance
from skyvern.forge.forge_app import ForgeApp
@@ -21,6 +21,9 @@ def create_forge_stub_app() -> ForgeApp:
fake_app_module.AGENT_FUNCTION = _LazyNamespace()
fake_app_module.AGENT_FUNCTION.validate_block_execution = AsyncMock()
fake_app_module.AGENT_FUNCTION.validate_code_block = AsyncMock()
+ # Sync method — _LazyNamespace would auto-mock it as AsyncMock and break
+ # callers that unpack the return value. Match the real OSS default (None).
+ fake_app_module.AGENT_FUNCTION.resolve_mcp_oauth_org_lookups = MagicMock(return_value=None)
fake_app_module.agent = _LazyNamespace()
fake_app_module.DATABASE.observer.update_workflow_run_block = AsyncMock()
fake_app_module.DATABASE.observer.create_workflow_run_block = AsyncMock()
diff --git a/tests/unit/test_mcp_http_auth.py b/tests/unit/test_mcp_http_auth.py
index 35bb33af0..8e2e557c7 100644
--- a/tests/unit/test_mcp_http_auth.py
+++ b/tests/unit/test_mcp_http_auth.py
@@ -4,6 +4,7 @@ import asyncio
import base64
import json
from types import SimpleNamespace
+from typing import Any
from unittest.mock import AsyncMock, Mock
import httpx
@@ -441,6 +442,22 @@ def test_validate_oauth_token_contract_rejects_invalid_issuer() -> None:
)
+def test_validate_oauth_token_contract_rejects_wrong_audience() -> None:
+ # Guards the `verify_aud=False` decode path: a token whose `aud` points at a
+ # different resource must still fail _validate_oauth_token_contract, since
+ # PyJWT's built-in audience check is intentionally skipped in favor of the
+ # slash-normalizing comparison here.
+ with pytest.raises(HTTPException, match="Token audience is not valid for this MCP resource"):
+ mcp_http_auth._validate_oauth_token_contract(
+ {
+ "iss": "https://clerk.example.com",
+ "aud": ["https://other-service.example.com"],
+ },
+ expected_resource="https://api.skyvern.com/mcp/",
+ expected_issuer="https://clerk.example.com",
+ )
+
+
def test_validate_oauth_token_contract_rejects_mismatched_resource_claim() -> None:
with pytest.raises(HTTPException, match="Token resource is not valid for this MCP resource"):
mcp_http_auth._validate_oauth_token_contract(
@@ -466,6 +483,52 @@ def test_validate_oauth_token_contract_accepts_valid_jwt_claims() -> None:
)
+async def test_validate_mcp_oauth_token_rejects_wrong_audience_on_full_jwt_path(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ import jwt
+ from cryptography.hazmat.primitives.asymmetric import rsa
+ from jwt.algorithms import RSAAlgorithm
+
+ private_key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+ public_jwk = json.loads(RSAAlgorithm.to_jwk(private_key.public_key()))
+ token = jwt.encode(
+ {
+ "iss": "https://clerk.example.com",
+ "aud": ["https://other-service.example.com"],
+ "resource": "https://api.skyvern.com/mcp/",
+ "sub": "user_123",
+ "org_id": "clerk_org_jwt",
+ },
+ private_key,
+ algorithm="RS256",
+ headers={"typ": "JWT"},
+ )
+ fake_db = SimpleNamespace(
+ get_organization_entities=AsyncMock(),
+ get_valid_org_auth_token=AsyncMock(),
+ )
+ _stub_auth_db(monkeypatch, fake_db)
+ monkeypatch.setattr(mcp_http_auth, "_get_oauth_issuer_url", lambda: "https://clerk.example.com")
+ monkeypatch.setattr(mcp_http_auth.settings, "SKYVERN_BASE_URL", "https://api.skyvern.com")
+ monkeypatch.setattr(
+ mcp_http_auth,
+ "app",
+ SimpleNamespace(
+ AGENT_FUNCTION=SimpleNamespace(
+ get_mcp_oauth_jwt_key=AsyncMock(return_value=public_jwk),
+ )
+ ),
+ )
+
+ with pytest.raises(HTTPException, match="Token audience is not valid for this MCP resource"):
+ await mcp_http_auth.validate_mcp_oauth_token(token)
+
+ fake_db.get_organization_entities.assert_not_awaited()
+ fake_db.get_valid_org_auth_token.assert_not_awaited()
+
+
@pytest.mark.asyncio
async def test_fetch_oauth_userinfo_returns_payload(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setattr(
@@ -639,6 +702,7 @@ async def test_validate_mcp_oauth_token_passes_clock_skew_leeway_to_pyjwt(
"aud": ["https://api.skyvern.com/mcp/"],
"resource": "https://api.skyvern.com/mcp/",
"sub": "user_123",
+ "org_id": "clerk_org_jwt",
}
fake_db = SimpleNamespace(
@@ -665,7 +729,8 @@ async def test_validate_mcp_oauth_token_passes_clock_skew_leeway_to_pyjwt(
assert resolution.api_key == "sk_live_from_jwt"
assert captured["kwargs"]["leeway"] == mcp_http_auth._TOKEN_CLOCK_SKEW_SECONDS
- assert "options" not in captured["kwargs"]
+ assert captured["kwargs"]["options"] == {"verify_aud": False}
+ fake_db.get_organization_entities.assert_awaited_once_with("clerk_org_jwt", "organization")
@pytest.mark.asyncio
@@ -806,6 +871,121 @@ async def test_resolve_oauth_subject_to_org_logs_missing_db_methods(monkeypatch:
debug_log.assert_called_once()
+async def test_resolve_oauth_subject_to_org_uses_explicit_org_id() -> None:
+ fake_db = SimpleNamespace(
+ get_organization_entities=AsyncMock(return_value=[SimpleNamespace(organization_id="skyvern_org_123")]),
+ get_valid_org_auth_token=AsyncMock(return_value=SimpleNamespace(token="sk_live_org_123")),
+ )
+
+ resolution = await mcp_http_auth._resolve_oauth_subject_to_org(
+ {"sub": "user_123", "org_id": "clerk_org_123"},
+ fake_db,
+ )
+
+ assert resolution.api_key == "sk_live_org_123"
+ assert resolution.validation.organization_id == "skyvern_org_123"
+ fake_db.get_organization_entities.assert_awaited_once_with("clerk_org_123", "organization")
+ fake_db.get_valid_org_auth_token.assert_awaited_once_with(
+ "skyvern_org_123", mcp_http_auth.OrganizationAuthTokenType.api
+ )
+
+
+async def test_resolve_oauth_subject_to_org_uses_organizations_repository_shape(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ # Cloud shape: lookups live on db.organizations rather than directly on db.
+ # The OSS code routes that case through AgentFunction.resolve_mcp_oauth_org_lookups,
+ # which the cloud build overrides. Simulate the override here so the test
+ # exercises the same delegation contract without importing cloud modules.
+ organizations_repo = SimpleNamespace(
+ get_organization_entities=AsyncMock(return_value=[SimpleNamespace(organization_id="skyvern_cloud_org")]),
+ get_valid_org_auth_token=AsyncMock(return_value=SimpleNamespace(token="sk_live_cloud_org")),
+ )
+ fake_db = SimpleNamespace(organizations=organizations_repo)
+
+ def fake_resolve(db: object) -> tuple[Any, Any] | None:
+ organizations = getattr(db, "organizations", None)
+ if organizations is None:
+ return None
+ return organizations.get_organization_entities, organizations.get_valid_org_auth_token
+
+ monkeypatch.setattr(
+ mcp_http_auth.app.AGENT_FUNCTION,
+ "resolve_mcp_oauth_org_lookups",
+ fake_resolve,
+ )
+
+ resolution = await mcp_http_auth._resolve_oauth_subject_to_org(
+ {"sub": "user_123", "org_id": "clerk_org_cloud"},
+ fake_db,
+ )
+
+ assert resolution.api_key == "sk_live_cloud_org"
+ assert resolution.validation.organization_id == "skyvern_cloud_org"
+ organizations_repo.get_organization_entities.assert_awaited_once_with("clerk_org_cloud", "organization")
+ organizations_repo.get_valid_org_auth_token.assert_awaited_once_with(
+ "skyvern_cloud_org", mcp_http_auth.OrganizationAuthTokenType.api
+ )
+
+
+async def test_resolve_oauth_subject_to_org_uses_compact_clerk_org_claim() -> None:
+ fake_db = SimpleNamespace(
+ get_organization_entities=AsyncMock(return_value=[SimpleNamespace(organization_id="skyvern_org_compact")]),
+ get_valid_org_auth_token=AsyncMock(return_value=SimpleNamespace(token="sk_live_compact")),
+ )
+
+ resolution = await mcp_http_auth._resolve_oauth_subject_to_org(
+ {"sub": "user_123", "o": {"id": "clerk_org_compact"}},
+ fake_db,
+ )
+
+ assert resolution.api_key == "sk_live_compact"
+ assert resolution.validation.organization_id == "skyvern_org_compact"
+ fake_db.get_organization_entities.assert_awaited_once_with("clerk_org_compact", "organization")
+
+
+async def test_resolve_oauth_subject_to_org_rejects_missing_explicit_org_context() -> None:
+ fake_db = SimpleNamespace(
+ get_organization_entities=AsyncMock(return_value=[SimpleNamespace(organization_id="first_org")]),
+ get_valid_org_auth_token=AsyncMock(return_value=SimpleNamespace(token="sk_live_first")),
+ )
+
+ with pytest.raises(
+ mcp_http_auth.MissingOrgContextError,
+ match="Bearer token missing organization context",
+ ) as exc_info:
+ await mcp_http_auth._resolve_oauth_subject_to_org({"sub": "user_123"}, fake_db)
+
+ assert exc_info.value.status_code == 401
+ fake_db.get_organization_entities.assert_not_awaited()
+
+
+async def test_resolve_oauth_subject_to_org_does_not_choose_first_user_membership() -> None:
+ fake_db = SimpleNamespace(
+ get_organization_entities=AsyncMock(
+ return_value=[
+ SimpleNamespace(organization_id="first_org"),
+ SimpleNamespace(organization_id="second_org"),
+ ]
+ ),
+ get_valid_org_auth_token=AsyncMock(return_value=SimpleNamespace(token="sk_live_first")),
+ )
+
+ with pytest.raises(
+ mcp_http_auth.MissingOrgContextError,
+ match="Bearer token missing organization context",
+ ):
+ await mcp_http_auth._resolve_oauth_subject_to_org({"sub": "user_with_many_orgs"}, fake_db)
+
+ fake_db.get_organization_entities.assert_not_awaited()
+ fake_db.get_valid_org_auth_token.assert_not_awaited()
+
+
def test_get_auth_db_uses_agent_function_builder(monkeypatch: pytest.MonkeyPatch) -> None:
built_db = object()
builder = Mock(return_value=built_db)
diff --git a/tests/unit/test_workflow_service_cancel.py b/tests/unit/test_workflow_service_cancel.py
index a6d1596b7..48a0b29dc 100644
--- a/tests/unit/test_workflow_service_cancel.py
+++ b/tests/unit/test_workflow_service_cancel.py
@@ -17,7 +17,7 @@
from __future__ import annotations
import asyncio
-from datetime import UTC, datetime, timedelta
+from datetime import UTC, datetime, timedelta, tzinfo
from unittest.mock import AsyncMock, MagicMock
import pytest
@@ -49,11 +49,12 @@ async def test_mark_canceled_if_not_final_returns_conditional_result(
)
-def _make_updated_row() -> MagicMock:
+def _make_updated_row(now: datetime | None = None) -> MagicMock:
+ now = now or datetime.now(UTC)
row = MagicMock()
row.status = WorkflowRunStatus.canceled
- row.created_at = datetime.now(UTC) - timedelta(seconds=30)
- row.started_at = datetime.now(UTC) - timedelta(seconds=20)
+ row.created_at = now - timedelta(seconds=30)
+ row.started_at = now - timedelta(seconds=20)
row.workflow_id = "wf_abc"
row.organization_id = "org_abc"
row.run_with = None
@@ -75,7 +76,17 @@ async def test_mark_canceled_if_not_final_logs_duration_metrics(
from skyvern.forge.sdk.workflow import service as service_module
from skyvern.forge.sdk.workflow.service import WorkflowService
- updated_row = _make_updated_row()
+ fixed_now = datetime(2026, 1, 1, tzinfo=UTC)
+ updated_row = _make_updated_row(fixed_now)
+
+ class FrozenDateTime(datetime):
+ @classmethod
+ def now(cls, tz: tzinfo | None = None) -> datetime:
+ if tz is None:
+ return fixed_now.replace(tzinfo=None)
+ return fixed_now.astimezone(tz)
+
+ monkeypatch.setattr(service_module, "datetime", FrozenDateTime)
monkeypatch.setattr(
app.DATABASE.workflow_runs,
"update_workflow_run_if_not_final",