openwork/docs/external-mcp-oauth.md

# External MCP OAuth administration

OpenWork discovers and authorizes Den-managed external MCP connections without
placing provider credentials in the agent engine. Tokens, refresh tokens,
client secrets, PKCE verifiers, and pending authorization transactions remain
encrypted in Den.

## Required public origin

Set `DEN_API_PUBLIC_URL` to the externally reachable HTTPS base URL for the Den
deployment. OpenWork derives both public OAuth URLs exclusively from this
configured origin; request host headers cannot replace it.

- Shared callback: `<DEN_API_PUBLIC_URL>/v1/mcp-connections/oauth/callback`
- Existing connection callback: `<DEN_API_PUBLIC_URL>/v1/mcp-connections/<connection-id>/connect/callback`
- Client metadata document: `<DEN_API_PUBLIC_URL>/oauth/client-metadata.json`

The client metadata document is public, contains no secrets, and describes
OpenWork as a web OAuth client. Each self-hosted Den deployment has its own
callback and metadata URL.

## OAuth runtime and callback compatibility

Den uses `@openwork/enterprise-mcp-client` for discovery, authorization,
refresh, tool discovery, and tool calls. There is no deployment or workspace
runtime switch.

New OAuth connections use the deployment-wide shared callback. An existing
connection keeps the callback mode already stored on its row, including the
older per-connection callback. Reconnecting therefore uses the exact redirect
URI that was registered with the provider and does not rewrite credentials,
tokens, access grants, or plugin bindings.

## Add a connection

In Cloud → Connections, enter the MCP server URL. OpenWork automatically runs
discovery after the URL settles; there is no separate discovery step. A failed
check shows its error and a retry action. Discovery is side-effect free: it does
not create a connection, register an OAuth client, open a browser, or save credentials. It reports MCP
initialization, RFC 9728 protected-resource metadata, authorization servers,
PKCE and refresh support, registration choices, scopes, visible tools, and any
network or administrator work that standards metadata cannot prove.

When authorization starts, OpenWork uses this registration priority:

1. An administrator-supplied pre-registered client.
2. A client metadata URL (CIMD) when the authorization server advertises it.
3. Dynamic client registration when the server advertises a registration endpoint.
4. A configuration-required result with the missing manual steps.

Required challenge scopes are locked. Administrators may select optional
advertised scopes and edit the saved scope set later. When neither the 401
challenge nor the administrator selects scopes, OpenWork falls back to the
provider's advertised `scopes_supported` set; this preserves compatibility
with providers that reject scope-less authorization requests. A configured
scope set still takes precedence. `offline_access` is requested only when both
that scope and refresh-token support are advertised.

## Callback routing

The callback mode is persisted and bound into signed OAuth state. The shared
route accepts only shared-callback transactions; the per-connection route
accepts only transactions for that connection whose signed mode is
`legacy-v1`. Version-one transactions already in flight remain bound to the
legacy verifier for their original ten-minute lifetime.

The dashboard links to the redirect URL documentation from pre-registered OAuth
app forms instead of repeating callback and client-metadata URLs on every
connection. It does not offer migration or rollback actions. Deleting and
recreating a connection creates a new shared-callback registration and may
remove access grants, per-member authorization state, and plugin or marketplace
bindings.

Changing the MCP server identity or selected issuer clears tokens and pending
authorization state. An issuer change also clears the saved client registration
so a secret can never be sent to a newly selected issuer.

## Troubleshooting

- **Configuration required**: supply a manually registered client when neither
  client metadata nor dynamic registration is advertised.
- **Issuer mismatch**: repeat discovery and select an issuer advertised by the
  protected resource. Metadata must return that exact issuer.
- **Reauthorization required**: the refresh grant is missing, expired, rejected,
  or bound to an older issuer/client registration.
- **Network trust required**: verify Den's proxy, private CA, DNS, firewall, and
  service-mesh egress. Discovery uses the same Den network policy as live MCP calls.
- **Additional permission required**: review and approve the newly challenged
  scope before reconnecting; OpenWork does not silently expand access.
- **Provider identity/verification page after authorize**: leave requested
  scopes empty only when the provider advertises the complete workable set, or
  edit the connection's requested scopes and reconnect.
- **`redirect_uri did not match`**: verify the exact callback derived from
  `DEN_API_PUBLIC_URL` against the provider registration. Some providers take a
  short time to propagate callback changes before authorization succeeds.

OAuth logs and support data use phase/error codes and omit tokens, secrets,
authorization codes, signed state, PKCE verifiers, and URL query strings.