Skip to content

docs: plan AgentCore Identity and Gateway integration - #6362

Closed
kyleseaman wants to merge 4 commits into
fix/spec-builder-cxfrom
docs/agentcore-identity-gateway-plan-1b02
Closed

kyleseaman wants to merge 4 commits into
fix/spec-builder-cxfrom
docs/agentcore-identity-gateway-plan-1b02

Conversation

@kyleseaman

@kyleseaman kyleseaman commented Aug 27, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Kiro Crew has no first-class agent identity in Amazon Bedrock AgentCore, and no token-vending path for outbound MCP tools. Operator-local secrets and static MCP Authorization headers are the only options today. A pasted Gateway URL is not an integration: it has no workload identity, no per-session principal, no refresh, and no 3LO consent surface.

The copyable cloud Policy.json pair also cannot express either of the two exclusive fleet shapes we need: a deployed box that can reach Gateway at boot, or a login box whose approved catalog is Gateway (overriding Kiro's default MCP merge).

Why it matters

Without a Crew workload identity, Gateway policy, CloudTrail, and the Identity token vault cannot name the agent. Without Gateway as the vending plane, Crew would have to implement OAuth / RFC 8693 itself — or keep sharing long-lived tool credentials.

Without binding that design to Policy.json, a launcher paste that looks like it grants InvokeGateway still fails: the instance is capped by the immutable kirocrew-ec2-boundary (SSM + source-bucket only). Re-versioning that boundary is forbidden; a leaked launcher credential must not be able to CreatePolicyVersion it permissive.

What changed (motivation → approach → change)

Goal: plan the integration, not implement it.

Approach (over putting boto3 in the public core, hosting Crew on AgentCore Runtime, or extending the reserved IdentityProvider.whoami slot):

  • New default-off CPP slot AgentIdentityProvider for a standalone AgentCore workload (kirocrew-<StackTag>).
  • AgentCore Gateway as the outbound token-vending plane (M2M / 3LO / OBO). Crew never holds the downstream token.
  • Trusted, core-derived SessionPrincipal ({surface}+{id}). Never take userId from the model.
  • Public edition stays byte-identical: no AWS SDK, no Cognito/SSO reintroduction, CONTRACT_VERSION stays 1.

Two exclusive postures in security_policy.json (capabilities.agentcore.posture), each with a matching instance Policy.json:

  • workload — deployed Crew has an IAM identity and can InvokeGateway at boot. No login. Kiro MCP defaults still merge. Instance grant allows GetWorkloadAccessToken / ForUserId and Denies ForJWT.
  • login — only Gateway-approved MCP is vended. rebuild_agent_config() withholds Kiro-global, seam-global, crew-store, and leftover non-managed servers (same emit-time control as kirocrew-computer spec_gate). Managed kirocrew-* stay. Gateway is absent until ensure-login vends a CUSTOM_JWT. Instance grant allows ForJWT only and Denies ForUserId + InvokeGateway.

See-and-configure is on each crew's own gateway. Settings → Security → Agent identity (GET/PUT /api/agentcore/identity) on the dashboard you are connected to. A hub launching another box is a different crew — identity does not live on Settings → Remote Crew. PUT writes only the standalone home security_policy.json; a fleet override or signed document is 409. App tokens are 403. The ceiling is boot-frozen, so a write returns restart_required.

Deploy can still create the AWS identity. The CloudFormation launcher (kirocrew-ec2.yaml) creates AWS::BedrockAgentCore::WorkloadIdentity named kirocrew-<StackTag> when kirocrew cloud launch --agentcore-posture is workload or login, attaches the matching AWS::IAM::Policy to the instance role, and writes KIROCREW_AGENTCORE_POSTURE / KIROCREW_AGENTCORE_WORKLOAD_NAME into systemd. CDK operators create the same resource via aws_bedrockagentcore.WorkloadIdentity (the public wheel does not depend on aws-cdk-lib). Default none is the historical launch and the dashboard launch path. Stack delete removes the identity. The launcher Policy.json grows only control-plane Create/Delete/Get/Tag verbs — never InvokeGateway.

Policy.json split:

  • Launcher iam.policy_json() stays launch-only (CFN, PassRole, SSM, source bucket). It does not grow InvokeGateway.
  • New helper iam.agentcore_instance_policy_document(posture) is the copyable instance fragment.
  • New named boundary kirocrew-ec2-boundary-agentcore is the union ceiling. Original kirocrew-ec2-boundary is never re-versioned. CloudFormation AllowedPattern must accept either name.
  • Posture-vs-IAM mismatch fails closed (no Gateway emit, SEL-audited).

This PR records that design as:

Implementation is a stacked series (seams → Policy.json / boundary / login withhold → principal → CFN identity assignment → per-crew Settings identity → Phase 0 probe → inject → consent/unattended → companion). Phase 0 must answer whether kiro-cli can take per-session headers before the login injection path lands. The workload IAM path does not wait on that probe.

This is the identity/credential plane. It is not the sibling AgentCore sandboxes execution-plane design.

Replaces #6331, which closed when the branch was renamed off the cursor/ prefix.

Tests

N/A — documentation only. scripts/docs-lint.sh passes.

Manual verification

N/A — no runtime or UI change. Docs-lint and git diff --check were run on the branch.

Related Issues

None linked. Companion implementation is out of this repository (plan Task 7).

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • Existing tests pass and new tests added for new functionality (N/A — docs only)
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Record how Crew should take a standalone AgentCore workload identity
and use Gateway for outbound token vending, without importing AWS
into the public core.
A fleet is either a deployed box that can InvokeGateway at boot
(workload) or a login box whose rebuild withholds Kiro MCP defaults
until ensure-login vends a JWT. The launcher Policy.json stays
launch-only; a new instance helper and a successor boundary name
carry the AgentCore ceiling without re-versioning kirocrew-ec2-boundary.
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Aug 27, 2026
@github-actions

github-actions Bot commented Aug 27, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

Reviewed eadeeb7d94536d21e8936ca94e208a1204fcc254 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] eadeeb7

Verdict parsed from the review's SHA-scoped output markers for commit eadeeb7d94536d21e8936ca94e208a1204fcc254.

False positive or not applicable? A repository writer can comment:
/ai-review override fable eadeeb7d94536d21e8936ca94e208a1204fcc254: <one-sentence reason>

@github-actions

github-actions Bot commented Aug 27, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of eadeeb7d94536d21e8936ca94e208a1204fcc254 and found no blocking issues.

This comment is updated in place on each push.

Review details

FINDING -- docs/superpowers/plans/2026-08-27-agentcore-identity-gateway.md:198 -- "posture" is rejected by CapabilityGate.from_dict, aborting policy loading -> Fix: use a supported control shape or include parser changes in Task 2.
FINDING -- docs/superpowers/plans/2026-08-27-agentcore-identity-gateway.md:241 -- "agentcore_instance_policy_document(posture)" scopes access to kirocrew, while CloudFormation creates kirocrew-<StackTag>, denying token vending -> Fix: accept and emit the deployed workload name.
FINDING -- docs/superpowers/plans/2026-08-27-agentcore-identity-gateway.md:510 -- "extra_mcp_servers()" is merged unconditionally, exposing Gateway when the capability is disabled -> Fix: contribute Gateway only through the capability-gated gateway_mcp_spec().
FINDING -- docs/superpowers/plans/2026-08-27-agentcore-identity-gateway.md:75 -- the stack omits the promised /api/agentcore/identity route and cloud launch --agentcore-posture plumbing -> Fix: add explicit route/UI and launcher/CLI tasks.
[GPT-REVIEWED] eadeeb7

False positive or not applicable? A repository writer can comment:
/ai-review override gpt eadeeb7d94536d21e8936ca94e208a1204fcc254: <one-sentence reason>

@github-actions

github-actions Bot commented Aug 27, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — 🟡 CONCERNS

Design-level review of eadeeb7d94536d21e8936ca94e208a1204fcc254 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

Sound, well-grounded RFC stack; the union boundary quietly re-opens the exact leaked-launcher-credential threat the immutable boundary exists to stop.

Watch

  • Union boundary defeats the ceiling's posture enforcement. The launcher policy already carries iam:PutRolePolicy on kirocrew-ec2-* roles (src/kiro_crew/cloud/iam.py:394), with the boundary as the compensating ceiling. The RFC's single successor boundary is "the union ceiling … every AgentCore action either posture's instance grant may use (GetWorkloadAccessToken, ForUserId, ForJWT, InvokeGateway)" — so on a login fleet, a leaked launcher credential can PutRolePolicy the workload-posture grant onto the instance role and the ceiling permits it, granting InvokeGateway with no login. The only remaining guards are the mutable grant's Deny SIDs and Crew's in-process posture-mismatch probe, which an attacker holding the instance role never runs through. Per-posture boundary names (a third name, which the RFC declined for switch-without-relaunch convenience) would keep the posture split at the immutable layer; at minimum, PR 2b should state this trade explicitly in cloud.md.

Suggestions

  • Add AWS::BedrockAgentCore::WorkloadIdentity CloudFormation availability to the Phase 0 probe list — the deploy-time identity creation in PR 2b rests on it, and it is the one product-shape assumption the plan never verifies.

[DESIGN-REVIEWED] eadeeb7

A remote crew deploy creates the standalone WorkloadIdentity in
the same CloudFormation stack. CDK operators use the same
resource via aws_bedrockagentcore.WorkloadIdentity.
See-and-configure is Settings → Security on the crew you are
connected to, not the hub Remote Crew launcher.
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Aug 27, 2026
@kyleseaman

Copy link
Copy Markdown
Contributor Author

Superseded by #6387. The RFC/plan now lives on the implementation branch (rebased onto main).

@kyleseaman kyleseaman closed this Aug 27, 2026
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Aug 27, 2026
@bolichen97
bolichen97 deleted the docs/agentcore-identity-gateway-plan-1b02 branch September 6, 2026 03:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant