docs: document IAM policy resources and their required permissions (CXH-1152, CXP-785)

[luisina-santos]

Summary

The connector has synced IAM managed policies and inline policies as resources — with their policy documents in the resource profile — since PRs #132, #134 and #145. docs/connector.mdx was never updated to match.

README.md was updated with the new permissions in #147; the customer-facing page was not. Because the document fetch degrades AccessDenied to a warn-and-skip (pkg/connector/iam_policy.go:99-105, pkg/connector/inline_policy.go:313-320), a customer who builds their IAM role from the published policy gets iam_policy resources with no policy_document and no error. The feature is silently inert for anyone onboarding from the docs, which is why this blocks closing CXH-1152 rather than being a cosmetic docs nit.

This PR also folds in the one surviving item from CXP-785 — see below.

Changes

1. SyncIAMPolicyDocuments statement in all three setup paths (CXH-1152)

IAM setup tab, Identity Center setup tab, and the Terraform script. Covers the 12 IAM actions the two policy resource types actually call, verified against the call sites rather than against baton_capabilities.json alone:

Action	Call site
iam:ListPolicies	iam_policy.go:144
iam:GetPolicy / iam:GetPolicyVersion	iam_policy.go:83, :87
iam:ListUserPolicies / ListRolePolicies / ListGroupPolicies	inline_policy.go:221, :231, :241
iam:GetUserPolicy / GetRolePolicy / GetGroupPolicy	inline_policy.go:281, :291, :301
iam:ListAttachedUserPolicies / ...Role... / ...Group...	iam_policy.go:488, :507, :526

Note iam:ListRolePolicies and iam:ListAttachedRolePolicies were previously present only under the resource-scoped AccessToSSOProvisionedRoles statement (arn:aws:iam::*:role/aws-reserved/sso.amazonaws.com/*), while the connector calls them for every role. The new statement grants them at Resource: "*".

2. sso:ListCustomerManagedPolicyReferencesInPermissionSet (CXP-785)

Auditing CXP-785's five claimed missing actions against current main, only one survives:

Action	In this file?	Required by code?	Verdict
sso:GetInlinePolicyForPermissionSet	present	yes	already fixed
sso:ListManagedPoliciesInPermissionSet	present	yes	already fixed
sso:GetPermissionsBoundaryForPermissionSet	absent	not in baton_capabilities.json, not called	not a required permission
sso:DescribePermissionSetProvisioningStatus	absent	not in baton_capabilities.json, not called	not a required permission
sso:ListCustomerManagedPolicyReferencesInPermissionSet	absent	called at permission_set_assignment.go:382	added here

Added to the Identity Center and Terraform read policies. Every sso: action declared in baton_capabilities.json is now present in both.

CXP-785's stated impact is also stale — it says the sync is fail-fast. That call degrades AccessDenied to a warn-and-skip (permission_set_assignment.go:392-397), so the sync completes and customer-managed policy grants on permission sets are silently missing instead: the same failure class as the iam: gaps above.

History of this gap: ConductorOne/docs#398 (merged 2026-07-17) added the two already-present actions to the published baton/aws.mdx, and baton-aws#146 (merged 2026-07-30) added the same two here, so the published page and this file are in sync. Neither added sso:ListCustomerManagedPolicyReferencesInPermissionSet — it is missing from both. This PR fixes it in the source of truth, which is what regenerates the published page.

3. Narrative and capabilities table

• New "IAM policies as resources" section describing both resource types, the policy document attribute, the once-per-ARN handling of AWS-managed policies, and the degrade-on-missing-permission behaviour — so an operator seeing an empty document knows to check permissions.
• Capabilities table: added IAM managed policies and Inline policies rows. Neither resource type appeared anywhere on the page before this.
• Explanation bullets in the IAM setup tab, matching that section's existing per-permission prose style.

Test plan

• All 4 json fences parse as valid JSON after the edits
• Terraform jsonencode inline-policy payload parses; statement order ConductorOneReadAccess → ConductorOneProvisionAccess → AccessToSSOProvisionedRoles → IAMListPermissions → SyncIAMPolicyDocuments
• All 12 iam: actions verified present in each of the three setup paths
• Every sso: action in baton_capabilities.json verified present in the Identity Center and Terraform policies
• No duplicate iam:ListPolicies — the Identity Center and Terraform policies already grant it under IAMListPermissions
• Mintlify preview reviewed for the new section and table rows

Docs-only; no Go changes.

Refs CXH-1152, CXP-785. Related: #132, #134, #145, #147, ConductorOne/docs#398, #146.

🤖 Generated with Claude Code

[linear-code]

CXH-1152

CXP-785

[github-actions]

Connector PR Review: docs: document IAM policy resources and their required permissions (CXH-1152)

Blocking Issues: 0 | Suggestions: 0 | Threads Resolved: 0
Criteria: Criteria status: loaded .claude/skills/ci-review.md from trusted base 2e6735e.
Review mode: incremental since 34322fa
View review run: https://github.com/ConductorOne/baton-aws/actions/runs/30828585614

Review Summary

This is a docs-only PR touching docs/connector.mdx. The full PR diff was scanned for security and correctness; it contains only documentation changes and no code. The new commits add sso:ListCustomerManagedPolicyReferencesInPermissionSet to both the standalone permissions-policy JSON and the Terraform aws_iam_role policy, matching the existing sso action ordering. I verified the three SyncIAMPolicyDocuments blocks are permission-complete: blocks 2 and 3 grant iam:ListPolicies via their preceding IAMListPermissions block, and block 1 includes it inline, so the documented iam:ListPolicies requirement is satisfied in every policy variant. No new issues found.

Security Issues

None found.

Correctness Issues

None found.

Suggestions

None.

[github-actions]

No blocking issues found.

[github-actions]

No blocking issues found.