PSA/docs/plans/2026-06-07-mcp-agent-idp-easy-path/PRD.md

# PRD — MCP Agent IdP "Easy Path" (Google / Microsoft presets)

**Date:** 2026-06-07 · **Branch:** `feature/alga-mcp-server`
**Builds on:** Phase-2 IdP delegation (`docs/plans/2026-06-06-alga-mcp-server/design.md §10`) + the MVP admin UI (`docs/plans/2026-06-07-alga-mcp-mvp-release/`).

## Problem statement & value

The remote MCP server authenticates agents by **delegating to the tenant's IdP** (it validates JWTs via JWKS and maps a subject claim to a provisioned agent). It works, but setup is **raw and technical**: an admin must hand-enter the `issuer`, `jwks_uri`, `audience`, and `subject_claim`. Alga's **SSO** already solves the equivalent problem elegantly — Nine Minds runs **shared Google + multi-tenant Entra apps**, so hosted customers get "Sign in with Google/Microsoft" with near-zero config, and enterprises can bring their own. This plan brings that same **"pick Google or Microsoft and go"** ergonomics to MCP agent auth.

## Goals

- **Provider presets**: choose **Microsoft Entra** or **Google** (instead of raw issuer/JWKS). Auto-derive `issuer` and discover `jwks_uri` via OIDC discovery. Google needs nothing; Microsoft needs only the Entra tenant id.
- **Reuse existing connections**: if the tenant already connected Microsoft (SSO / `microsoft_profiles` / `entra_managed_tenants`), pre-fill the agent IdP — *"you're already connected to Microsoft, enable agent access?"*.
- **Hosted near-zero-config (Tier 2)**: on SaaS, pre-trust Google + Microsoft via the **Nine Minds shared apps**; the MCP client's interactive `auth-code+PKCE` flows through them, so the customer configures nothing in their own directory.
- **Honest guidance** for the case the SSO analogy can't fully cover (below).

## Non-goals

- Alga acting as its **own OAuth authorization server** (we delegate — decided in §10).
- Changing the **core agent dispatch / RBAC / audit** (already built + verified).
- SAML; per-agent ABAC/approval/quotas (Phase 3).

## The key distinction (why this is tiered, not one-size)

SSO is **human** login; the shared app is just the OAuth client and the user's identity (`tid`/email) rides in the token. Agents are **governed machine principals**, so two cases differ:

- **Interactive / human-delegated agents** (the MCP spec's `auth-code+PKCE` — a human authorizes the MCP client in a browser): **fully "like SSO"** → Tier 2 zero-config on hosted.
- **Unattended machine agents** (no human, `client-credentials`): the agent needs **its own identity in the customer's directory** (an Entra **app registration** / a Google **service account**). This step is **irreducible** — the shared app can't *be* the customer's agent. Presets + discovery + connection-reuse make it easy, and a guided wizard gives copy-paste values, but it can't be zero-config like human SSO.

## Target users / personas

- **MSP admin (hosted)** — wants to enable agent access by picking Microsoft/Google, ideally reusing an existing connection.
- **MSP admin (self-hosted/enterprise)** — brings their own Entra tenant / Google project; presets + discovery still remove the manual JWKS step.

## Primary flows

1. **Microsoft preset:** MCP Server settings → "Add trusted IdP" → choose **Microsoft Entra** → enter (or auto-fill from an existing connection) the **Entra tenant id** → Alga derives `issuer = https://login.microsoftonline.com/{tid}/v2.0` and discovers `jwks_uri` → save. Provision an agent; its **subject** = the agent's Entra app id (`azp`/`appid`) for app tokens, or `oid`/`sub` for user tokens.
2. **Google preset:** choose **Google** → nothing to enter (issuer `https://accounts.google.com`, well-known JWKS). Agent subject = the service account's `sub` (or email).
3. **Hosted zero-config:** the tenant doesn't register anything; built-in Google/Microsoft issuers (shared app) are trusted; the agent connects via interactive OAuth and binds to the authorizing identity.
4. **Custom (unchanged):** raw issuer/jwks/audience/claim still available.

## Data model / integration notes

- `agent_idp_providers` gains `kind` (`google`|`microsoft`|`custom`, default `custom`) and `entra_tenant_id` (nullable). Existing rows = `custom`.
- **OIDC discovery helper** (new, ~30 lines, reuses `jose`/`fetch`): `discover(issuerOrConfigUrl) → { issuer, jwks_uri }`, cached.
- **Presets module**: Google = fixed issuer + well-known JWKS, default `subject_claim='sub'`; Microsoft = issuer from tenant id, discover JWKS, default `subject_claim='azp'` (app tokens) with a user-token hint (`oid`).
- **Connection reuse**: read `microsoft_profiles` / `entra_managed_tenants` / known `tid` to suggest the Entra tenant id.
- **Hosted built-ins**: `getAppSecret('MICROSOFT_OAUTH_CLIENT_ID')` / `GOOGLE_OAUTH_CLIENT_ID` present + a hosted flag → built-in trusted issuers (validated in `idpToken` alongside `agent_idp_providers`); PRM advertises them.
- Validation lives in `ee/server/src/lib/mcp/idpToken.ts` (jose); provisioning in `agents.ts`; admin UI in `server/src/components/settings/mcp/McpServerSettings.tsx`; routes under `/api/v1/mcp/*`.

## Risks & mitigations

- **OIDC discovery network dependency** — cache discovery results; fail with a clear message; allow manual `jwks_uri` override (custom).
- **Microsoft subject-claim ambiguity** (`azp`/`appid` for app tokens vs `oid`/`sub` for user tokens) — make `subject_claim` an explicit, preset-defaulted, editable field with inline guidance.
- **Hosted shared-app trust** — only enable built-in issuers when hosted + shared secrets present; bind agents per `(issuer, subject)` to keep them distinct/attributable.
- **Over-promising zero-config** — the UI + docs must be explicit that unattended machine agents still need their own directory identity.

## Acceptance criteria / DoD

- An admin can add a working trusted IdP by picking **Microsoft** (just a tenant id) or **Google** (nothing) — issuer + JWKS auto-resolved; an agent then authenticates against it (verified with a mock IdP whose discovery doc the preset path consumes).
- A tenant with an existing Microsoft connection sees a **pre-filled** suggestion.
- On a hosted build, Google + Microsoft are trusted with **no** per-tenant IdP registration, and PRM advertises them.
- `custom` raw entry still works. Docs spell out the easy path **and** the unattended-agent caveat.

## Testing (80/20)

Favor **live/E2E over mocked units**: OIDC discovery against the **real** Google + Microsoft well-known docs, a mock-IdP **preset** round-trip (register via the Microsoft preset pointed at a mock discovery doc → agent token validates + dispatches), and the admin-UI preset happy path. Keep the list lean.