Unclassified

OAuth Release Quick Start

TL;DR: P0 blocker is implemented. OAuth is now ready for staged deployment: test → production → marketplace.

What's Implemented

✓ User membership binding (Descope auth validation)
✓ Tenant workspace resolution (OAuth flow)
✓ Redirect URI validation (parameter sanitization)
✓ Test environment enabled (flag = true)
✓ Production flag ready (flag = false, manual enable after test)
✓ 8 smoke tests (public OAuth flow coverage)
✓ Deployment checklists (test + prod runbooks)

One-Line Summary

Then: MCP_EXTERNAL_OAUTH_ENABLED = "false" + hard-coded Customer Zero = blocked for external use

Now: Real user binding + tenant validation + enabled flag = ready for external clients

Files to Review

FileLinesPurpose
services/mcp-connector/src/lib/oauth-auth-server.ts+200User binding + tenant validation
services/mcp-connector/src/lib/oauth-clients.ts+26Membership check function
services/mcp-connector/src/index.ts+6Header injection from Gateway
services/mcp-connector/wrangler.toml1 lineTest flag: false → true
services/mcp-connector/src/oauth.test.ts+1048 new smoke tests

Docs (for deployment team):

  • docs/internal/operations/P0_OAUTH_RELEASE_BLOCKER_COMPLETE.md (overview)
  • docs/internal/operations/P0_OAUTH_RELEASE_BLOCKER_IMPLEMENTATION.md (technical spec)
  • docs/internal/operations/P0_OAUTH_TEST_DEPLOYMENT_CHECKLIST.md (test validation)
  • docs/internal/operations/P0_OAUTH_PRODUCTION_DEPLOYMENT.md (prod runbook)

Quick Deployment

Test Environment

# 1. Merge release/public-connector-go-live
git merge release/public-connector-go-live

# 2. Dry-run to test
pnpm release:core --env test --service core --dry-run true

# 3. Deploy to test
pnpm release:core --env test --service core --dry-run false

# 4. Validate (20 checkpoints in checklist)
# Expected: OAuth metadata shows "availability: enabled"

Production Environment

# Prerequisites: Test deployment passed all checks
# Have test workflow URL ready: https://github.com/integratewise/integratewise-live/actions/runs/XXXXX

# 1. Enable flag (wrangler.toml [env.prod])
# MCP_EXTERNAL_OAUTH_ENABLED = "true"

# 2. Dry-run to prod
pnpm release:core --env prod --service core --dry-run true

# 3. Deploy to prod
pnpm release:core --env prod --service core --dry-run false \
  --confirm_production true \
  --test_release_evidence "https://github.com/integratewise/integratewise-live/actions/runs/XXXXX"

# 4. Smoke tests pass → external clients can connect

Test Workflow Validation (First 60 seconds)

# 1. OAuth enabled?
curl https://mcp.integratewise.ai/.well-known/oauth-authorization-server | jq '.integratewise_availability'
# Expected: "enabled"

# 2. Catalog loads?
curl https://mcp.integratewise.ai/.well-known/oauth-protected-resource | jq '.resource'
# Expected: "https://mcp.integratewise.ai"

# 3. Authorize page?
curl "https://mcp.integratewise.ai/oauth/authorize?response_type=code&client_id=test&redirect_uri=https://example.com/callback"
# Expected: 200 (HTML)

# 4. Token endpoint?
curl -X POST https://mcp.integratewise.ai/oauth/token -d "grant_type=..."
# Expected: 200 or 400 (never 403 unless disabled)

If Something Goes Wrong

Rollback (< 5 minutes)

# 1. Disable flag in wrangler.toml
# MCP_EXTERNAL_OAUTH_ENABLED = "false"

# 2. Redeploy
pnpm release:core --env prod --service core --dry-run false --confirm_production true --test_release_evidence "..."

# 3. Verify
curl https://mcp.integratewise.ai/.well-known/oauth-authorization-server | jq '.integratewise_availability'
# Expected: "private_alpha"

Debug

Check logs:

wrangler tail integratewise-mcp-connector --env prod
wrangler tail integratewise-gateway --env prod

Common issues:

  • 403 private_alpha: Flag not set or didn't deploy
  • Missing D1: oauth_clients table not found (should exist)
  • Redirect validation fails: Client D1 record missing or redirect not in whitelist
  • Tenant mismatch: User's x-tenant-id ≠ client's registered tenant_id

After Go-Live (P4 Marketplace)

Once production is stable for 24h:

# 1. Publish IntegrateWise MCP connector package
# 2. Publish AI surface connector package
# 3. Enable marketplace catalog
# 4. Mark connectors as Available/Beta

External users can then:

  1. Add IntegrateWise connector → OAuth flow
  2. Sign in with Descope
  3. Authorize workspace access
  4. Read 65+ connectors without provider credentials
  5. Execute tasks via MCP interface

Key Metrics

Deployment Impact:

  • 0 breaking changes for existing customers
  • 0 database migrations
  • 0 secrets rotation
  • 1 feature flag enabled per environment

Blast Radius:

  • Test: 65+ connectors + new OAuth interface
  • Production: Same, gated by feature flag

Rollback Time: < 5 minutes

Success Criteria:

  • External clients connect via OAuth
  • Tenant membership validated
  • No credential leaks
  • Existing flows unaffected

Documentation Links

  • Full Spec: docs/internal/operations/P0_OAUTH_RELEASE_BLOCKER_IMPLEMENTATION.md
  • Test Checklist: docs/internal/operations/P0_OAUTH_TEST_DEPLOYMENT_CHECKLIST.md
  • Prod Runbook: docs/internal/operations/P0_OAUTH_PRODUCTION_DEPLOYMENT.md
  • Completion Summary: docs/internal/operations/P0_OAUTH_RELEASE_BLOCKER_COMPLETE.md

Status

✓ Implementation: COMPLETE
✓ Tests: PASSING
✓ Documentation: READY
⏳ Deployment: READY (awaiting release team)

Next: Merge to release/public-connector-go-live, deploy to test, validate, promote to production.