{"slug":"connectors/P0_OAUTH_PRODUCTION_DEPLOYMENT","title":"P0: OAuth Production Deployment — Runbook","section":"connectors","sectionLabel":"Connectors","status":"unclassified","type":"document","path":"connectors/P0_OAUTH_PRODUCTION_DEPLOYMENT.mdx","bytes":7476,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Status**: Execute ONLY after test deployment passes all validation checks  \n**Risk Level**: MEDIUM — enables public API for external clients  \n**Rollback Time**: ~5 minutes\n\n---\n\n## Prerequisites\n\nMUST complete before proceeding:\n\n- [ ] Test deployment passed all validation checks (see P0_OAUTH_TEST_DEPLOYMENT_CHECKLIST.md)\n- [ ] Successful test workflow URL captured (e.g., integratewise/integratewise-live/actions/runs/12345)\n- [ ] No critical production incidents in last 24 hours\n- [ ] Release team member on-call for monitoring\n\n---\n\n## Step 1: Configuration Change\n\nUpdate production environment to enable OAuth:\n\n**File**: `services/mcp-connector/wrangler.toml`\n\n**Change**:\n\n```toml\n[env.prod.vars]\n...\nMCP_EXTERNAL_OAUTH_ENABLED = \"false\"  # ← CHANGE THIS\n```\n\nTo:\n\n```toml\n[env.prod.vars]\n...\nMCP_EXTERNAL_OAUTH_ENABLED = \"true\"   # ← Enable for production\n```\n\n**Commit**:\n\n```bash\ngit add services/mcp-connector/wrangler.toml\ngit commit -m \"P0: Enable public OAuth for production connector platform\n\n- Enables MCP_EXTERNAL_OAUTH_ENABLED in production environment\n- User membership binding to Descope auth (removes Customer Zero hard-coding)\n- Test validation: <URL to successful test workflow>\n\nThis enables external clients to access the public MCP connector interface\nwith proper tenant membership authorization.\"\n```\n\n**Push**:\n\n```bash\ngit push origin release/public-connector-go-live\n```\n\n---\n\n## Step 2: Dry-Run Validation\n\nAlways do a dry-run first to catch any configuration issues:\n\n**Command**:\n\n```bash\npnpm release:core \\\n  --env prod \\\n  --service core \\\n  --dry-run true\n```\n\n**Expected Output**:\n\n- ✓ All 10 services validated for production deployment\n- ✓ No secrets missing\n- ✓ All service bindings correct\n- ✓ wrangler.toml [env.prod] correctly configured\n\n**If fails**: Do NOT proceed. Debug and re-run dry-run.\n\n---\n\n## Step 3: Production Deployment\n\nExecute the live deployment with mandatory confirmation:\n\n**Command**:\n\n```bash\npnpm release:core \\\n  --env prod \\\n  --service core \\\n  --dry-run false \\\n  --confirm_production true \\\n  --test_release_evidence \"<URL to successful test workflow>\"\n```\n\n**Replace `<URL>` with**:\nExample: `https://github.com/integratewise/integratewise-live/actions/runs/12345`\n\n**The workflow will**:\n\n1. Verify test workflow URL is valid and successful\n2. Deploy all 10 services to production\n3. Cloudflare DNS switches to new Workers\n4. Existing traffic flows to new version\n\n**Monitor**: Watch GitHub Actions for all services reporting \"✓ Published\"\n\n---\n\n## Step 4: Production Smoke Tests (First 10 Minutes)\n\nImmediately after deployment, verify critical paths:\n\n### Test 1: OAuth Metadata Available\n\n```bash\ncurl https://mcp.integratewise.ai/.well-known/oauth-authorization-server | jq '.integratewise_availability'\n```\n\nExpected: `\"enabled\"`\n\n### Test 2: Connector Catalog Loads\n\n```bash\ncurl https://mcp.integratewise.ai/.well-known/oauth-protected-resource | jq '.resource'\n```\n\nExpected: `\"https://mcp.integratewise.ai\"`\n\n### Test 3: Customer Zero Still Works\n\nVerify existing internal clients are unaffected:\n\n```bash\n# Using test OAuth token with Customer Zero tenant\ncurl -H \"Authorization: Bearer <test-jwt>\" https://mcp.integratewise.ai/tools\n```\n\nExpected: 200 with 19 Continuity Bridge tools\n\n### Test 4: Authorization Flow Renders\n\n```bash\ncurl \"https://mcp.integratewise.ai/oauth/authorize?response_type=code&client_id=test&redirect_uri=https://example.com/callback&scope=mcp:tools\"\n```\n\nExpected: 200 HTML (consent form)\n\n---\n\n## Step 5: Monitoring (First Hour)\n\nWatch these metrics in Cloudflare Workers dashboard:\n\n| Metric                       | Threshold       | Action                        |\n| ---------------------------- | --------------- | ----------------------------- |\n| 5xx errors                   | > 0.5%          | Page on-call + check logs     |\n| 401 responses                | Normal          | OAuth challenge is expected   |\n| OAuth token endpoint latency | < 500ms         | Check JWT signing performance |\n| Request rate to /oauth/\\*    | Expected growth | Normal for new availability   |\n\n**Logs to check**:\n\n```bash\n# MCP-Connector errors\nwrangler tail integratewise-mcp-connector --env prod\n\n# Gateway auth errors (tenant binding)\nwrangler tail integratewise-gateway --env prod\n```\n\n---\n\n## Step 6: External Client Proof-of-Concept (After 1 Hour)\n\nOnce production is stable, test with external client (Task 8):\n\n1. Create blank v0 application\n2. Add IntegrateWise OAuth connector → redirects to `https://mcp.integratewise.ai/oauth/authorize`\n3. User goes through Descope login + consent\n4. v0 app receives code + exchanges for token\n5. v0 app queries `https://mcp.integratewise.ai/tools` with token\n\n**Success**: External client reads workspace + connector catalog without any provider credentials.\n\n---\n\n## Rollback Procedures\n\n### Quick Rollback (< 5 minutes)\n\n**If critical errors detected**:\n\n```bash\n# 1. Revert wrangler.toml\ngit revert <commit-hash>\n\n# 2. Push to prod\ngit push origin release/public-connector-go-live\n\n# 3. Dry-run\npnpm release:core --env prod --service core --dry-run true\n\n# 4. Deploy disabled\npnpm release:core \\\n  --env prod \\\n  --service core \\\n  --dry-run false \\\n  --confirm_production true \\\n  --test_release_evidence \"<URL>\"\n```\n\n**Verification**:\n\n```bash\ncurl https://mcp.integratewise.ai/.well-known/oauth-authorization-server | jq '.integratewise_availability'\n# Should return: \"private_alpha\"\n```\n\n### Full Rollback (if issues persist)\n\n1. Roll back entire release to previous commit\n2. Page on-call for incident review\n3. Do not re-attempt without root cause analysis\n\n---\n\n## Success Criteria\n\nDeployment is successful when:\n\n- [ ] All 10 services report \"✓ Published\" in GitHub Actions\n- [ ] OAuth metadata endpoint shows `availability: \"enabled\"`\n- [ ] Customer Zero clients still work (no regression)\n- [ ] Authorization flow renders correctly\n- [ ] Token exchange succeeds with valid credentials\n- [ ] External client proof-of-concept works (Task 8)\n- [ ] No 5xx errors in first hour\n- [ ] Monitoring metrics normal\n\n---\n\n## Post-Deployment: Marketplace Readiness\n\nAfter 24 hours of successful production operation:\n\n1. **Publish IntegrateWise MCP Connector Package** (P4)\n   - Make MCP connector discoverable in marketplace\n\n2. **Publish AI Surface Connector Package** (P4)\n   - Enable language models to use IntegrateWise tools\n\n3. **Enable Marketplace Catalog** (P4)\n   - 65+ connectors now visible with release states\n   - Mark validated connectors as \"Available\"\n   - Mark tested-but-pending as \"Beta\"\n\n---\n\n## Related Documentation\n\n- **Implementation Spec**: P0_OAUTH_RELEASE_BLOCKER_IMPLEMENTATION.md\n- **Test Validation**: P0_OAUTH_TEST_DEPLOYMENT_CHECKLIST.md\n- **Architecture**: docs/architecture/v2-security.md\n- **OAuth Standard**: RFC 6749, RFC 8252\n\n---\n\n## Contacts\n\n**Release Lead**: [Team Member]  \n**On-Call Monitor**: [Team Member]  \n**Incident Escalation**: [Manager]\n\n---\n\n## Deployment Record\n\n| Phase                | Date/Time | Status | Notes |\n| -------------------- | --------- | ------ | ----- |\n| Test Deployment      |           |        |       |\n| Prod Dry-Run         |           |        |       |\n| Prod Deployment      |           |        |       |\n| Smoke Tests Pass     |           |        |       |\n| 24h Monitoring       |           |        |       |\n| Marketplace P4 Start |           |        |       |\n"}