Document connector auth types and policies

[tgrunnagle]

Visual regression screenshots

Auto-generated by CI from scripts/pr-screenshot-summary.mjs — edits inside this block are overwritten on the next push.

🟡 Changed

Nav Page Connector Gateway 🔀 /connector-gateway
	Before		After
☀️ diff		➡️
🌙 diff		➡️

Description

Documents Connector Gateway connector authentication, connector policies, and connector fields, as described in #1178. Stacked on #1201; retarget to main after it merges.

New: Configure connector authentication (connector-gateway/connector-authentication.mdx)

• All eight outbound auth types, with what each sends and what each needs (secret, identity provider). The five console types use their console labels. awsSts, obo, and xaa are marked API-only, with a link to the Enterprise Manager API.
• Setup order: managed secret, then identity provider, then connector auth, then policy.
• Console steps for the five console types.
• Re-authorization: changing a provider's issuer, endpoints, client ID, scopes, authorization parameters, or redirect URI makes users authorize again. Reverting the change restores their stored credentials.

New: Grant and revoke connector access (connector-gateway/connector-policies.mdx)

• The canonical procedure for granting directory groups access (Add groups, then Grant access) and revoking it (Revoke access). It also covers inheritance and default-deny.
• Cedar-mode connectors are covered only as read-only in the console. This PR doesn't document how to write or use Cedar policies.

connectors.mdx

• New Connector settings section: supported transports (SSE deprecated, unknown transports withheld) and Allow private IPs (HTTPS and private-range rules, the discovery recommendation, the link-local floor).
• The old granting-access and auth sections are now a short pointer to the two new pages.

Cross-links

The sidebar now includes both pages. two-group-models.mdx links to the policy page from its prose and related information. The Connector Gateway index lists auth configuration, and the identity providers page's next steps point to the auth page.

Verification

Checked against stacklok-enterprise-platform origin/main:

• Enterprise Manager spec (ConnectorAuthRequest and arm schemas, ConnectorWriteRequest, policy routes), plus directory/domain/models/connector.go for required fields and constraints
• connector-gateway/internal/infra/vmcp/directory_translate.go (all eight auth types and both transports are servable), docs/architecture.md (SSE deprecation, credential fingerprint), and ADRs 0008, 0012, and 0013
• connector_policy_service.go (mode switch seeding and reset, 16 KiB limit), policycedar/ (schema, claim_ prefix, guard rule), and docs/customer/migrations/connector-policy-directory-evaluation.md
• Console: connector-auth-fields.tsx, create-connector-form-schema.ts, configuration-tab.tsx (locked form), access-tab.tsx, connector-form-fields.tsx, and discovered_server.go / mapper.go (private IP recommendation)
• npm run build passes, and Prettier and ESLint are clean

Follow-up, out of scope

This PR leaves out the issue's API-only connector metadata fields (icon_url, repository_url, support_url, version, draft, origin) and the advertised tool-name format with its rename warning.

The console labels connector states Verified, Draft, Verifying, and Broken. connectors.mdx still says Available and Failure.

Type of change

• Documentation update

Related issues/PRs

Part of #1178 and #1175. Stacked on #1201.

Submitter checklist

Content and formatting

• I have reviewed the content for technical accuracy
• I have reviewed the content for spelling, grammar, and style

Reviewer checklist

Content

• I have reviewed the content for technical accuracy
• I have reviewed the content for spelling, grammar, and style

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docs-website	Ready	Preview	Oct 6, 2026 3:33pm UTC

[danbarr]

Editorial review assessed against the final stack at #1208 (a9c7827), so this excludes issues later PRs already fix.

Two points remain:

• Distinguish current console choices from API-only authentication types. In docs/connector-gateway/connector-authentication.mdx, the authentication table calls all eight entries "Console label", including AWS STS, OBO, and XAA. The console selector at both the cited upstream e3da43246 and freshly fetched a11e15735 contains only the other five types. Please identify the three API-only types explicitly, avoid presenting prospective labels as current UI, and link to the Enterprise Manager API for configuring them.
• Make the policy page an actionable, canonical guide. docs/connector-gateway/connector-policies.mdx advertises both structured and Cedar policies, but only explains structured grants. Please add a direct API reference route for Cedar policy management, or narrow the page's stated scope. Coordinate with #1206 so this page owns the complete grant/revoke procedure and connector management links to it. The assembled stack currently repeats grants, inheritance, and Cedar-mode read-only behavior in both pages, while only the connector page covers revocation.

The authentication prerequisite order is useful and should stay.

[tgrunnagle]

Thanks for the review. Both points are addressed, and the stack is restacked on the updated base:

• API-only authentication types: addressed in b4cdca7. AWS STS, OBO, and XAA are back to "API only" in the table, and the intro links to the Enterprise Manager API for configuring them.
• Canonical policy page: addressed in fff0091. We're not documenting Cedar authoring yet, so the page is narrowed to directory group access and retitled "Grant and revoke connector access." It now owns the full grant and revoke procedure, using the current console labels (Add groups, Grant access, Revoke access), and covers Cedar-mode connectors only as read-only in the console. On Make the connectors page task-based #1206, 8e4e9bc replaces the connectors page's duplicate procedure with a short summary that links here.

[tgrunnagle]

Addressed in ab719eb. The API-only auth types and the narrowed policy-page scope landed earlier (b4cdca7, fff0091). This adds a direct Enterprise Manager API route for switching modes and writing Cedar documents, without bringing back the Cedar how-to.

[tgrunnagle]

/update-snapshots

[github-actions]

📸 Regenerated visual baselines per your /update-snapshots request and pushed a new commit.

[danbarr]

Approved from an editorial and information-architecture perspective. The findings from the stack review are addressed in the assembled result: administrator/owner audience, coherent navigation and credential-guide ownership, canonical access instructions, explicit API-only authentication, qualified usage reporting, and lowercase experience descriptions in prose. This approval does not assert live end-to-end validation of the deployment or examples.