RFC: Identity propagation — credential delegation via AgentCore Identity Token Vault

[theagenticguy]

Summary

Propose identity propagation as a credential, not just as data — completing the identity story that #245 starts on the attribution side. #245 propagates {task_id, user_id, repo, trace_id} so actions are traceable; this RFC makes outbound calls (GitHub, Linear, future Jira/Slack) carry an enforceable per-task, per-repo, short-lived identity via AgentCore Identity Token Vault, so attribution becomes cryptographic rather than advisory.

This is the "Delegation chain propagation" item #245 explicitly defers as out-of-scope follow-up, combined with ROADMAP's "Per-repo GitHub credentials" and "Layered credential derivation."

Drafted by Bonk, reviewed and filed by Laith Al-Saadoon.

Why this is mostly resume, not greenfield

ABCA already runs on AgentCore Runtime, and the identity-propagation plumbing exists end-to-end but is dormant (parked at Phase 2.0a due to a USER_FEDERATION service-side bug; fell back to direct Secrets Manager):

• Orchestrator already sets runtimeUserId on InvokeAgentRuntimeCommand — cdk/src/handlers/shared/strategies/agentcore-strategy.ts:56
• Orchestrator role already holds bedrock-agentcore:InvokeAgentRuntimeForUser — cdk/src/constructs/task-orchestrator.ts:288-289
• Agent already reads the WorkloadAccessToken header and re-injects it across the pipeline thread (the per-thread ContextVar workaround is already solved) — agent/src/server.py:283-310, 387-413
• The bedrock-agentcore dep is kept as "vestigial" specifically so this path imports cleanly when resumed — agent/pyproject.toml

Current credential gap

Surface	Today	Risk
GitHub	One shared PAT in Secrets Manager (agent/src/config.py:resolve_github_token)	One token, all repos; no per-user/repo scoping (tracked SECURITY.md limitation)
Linear	Per-workspace OAuth token in SM, manual refresh (linear-oauth-resolver.ts)	Workspace-scoped, not user-scoped; no act-claim audit chain
AgentCore Identity	Parked (Phase 2.0a) — fell back to direct Secrets Manager	Outbound identity collapses to a shared service credential

Why now

The AgentCore deep-dive (v1.2, 2026-05-13) records OBO (ON_BEHALF_OF_TOKEN_EXCHANGE) GA'd April 2026 across 14 regions and re-grounds the oauth2Flow enum against current API refs. The Phase 2.0a blocker was a USER_FEDERATION service bug; the platform side that parked us has materially changed. Phase 0 below re-validates before we commit.

Design

Shared binding key with #245. AgentCore Identity binds tokens to (workload_identity, user_id). user_id MUST be the same IdP-namespaced value #245 standardizes (e.g. cognito+<sub>, avoiding sub collisions across IdPs). One identity, two planes: #245 stamps it in logs/spans; this RFC stamps it in tokens.

Flow selection (deep-dive §12 decision tree):

Integration	Inbound	Downstream	Flow
GitHub (commit/PR as user)	Cognito	github.com (different ecosystem)	USER_FEDERATION (3LO)
Linear	Cognito/webhook	linear.app (different)	USER_FEDERATION (3LO), replacing manual SM refresh
Headless / webhook-no-user	none	n/a	M2M (client_credentials) under a manual workload identity
Future AWS-native downstream	Cognito	same ecosystem	OBO with act-claim delegation

The honest webhook caveat: webhook-triggered tasks (Linear/Slack/GitHub) authenticate the tenant via HMAC, not the user. The real OAuth consent moment is when the agent calls back out. Read-only triage → M2M service account; write-back → gated on fresh per-user consent.

Token Vault providers replace direct Secrets Manager reads: a GithubOauth2 provider (GitHub App → repo-scoped, short-lived, auto-refreshing installation tokens) retires the shared PAT; AtlassianOauth2/SlackOauth2 follow the same pattern as those integrations land.

Delegation chain (the #245 deferral): where downstream can consume it, use OBO delegation mode (actorTokenContent=M2M) so the issued token carries an act claim recording user → orchestrator → agent — per-action accountability, feeding #237's abca.audit.v1 correlation block.

Backend-agnostic: per SECURITY.md, SessionRole + agent code already serve both AgentCore and the parked ECS backend. Deep-dive §15 documents the raw-boto3 equivalent for ECS, so the agent keeps a single resolve_<integration>_token() seam regardless of how the WAT arrives.

Phasing

• Phase 0 — Re-validate (spike, no prod change). Confirm USER_FEDERATION/OBO works post-GA for our Cognito→GitHub shape in a throwaway provider. Record go/no-go with date + region.
• Phase 1 — GitHub via Token Vault (3LO). Stand up GithubOauth2 provider; switch resolve_github_token() to the vault path behind a flag, PAT fallback retained; retire the shared PAT once green. Resolves the SECURITY.md "Shared GitHub PAT" limitation.
• Phase 2 — Linear onto the vault. Move per-workspace OAuth to the vault provider; delete manual-refresh code.
• Phase 3 — Delegation chain. OBO act-claim where supported; emit the actor chain into RFC: Governance planes — analytics and compliance export #237's correlation block.

Acceptance criteria

• Phase 0 spike documents whether AgentCore Identity flows work post-GA; go/no-go recorded with date + region.
• user_id binding key matches feat(observability): end-to-end task attribution and cross-plane trace correlation #245's namespaced value exactly (no divergence between log attribution and token binding).
• GitHub outbound uses a vault-issued, repo-scoped, short-lived token; shared PAT removed from the hot path (flagged fallback OK).
• First-call 3LO surfaces an authorization URL and gates write-back on consent; no silent shared-credential fallback for user-attributed actions.
• No regression to feat(security): per-session IAM scoping — session-tagged AssumeRole, DynamoDB leading-key conditions, Bedrock ARN allowlist #209 SessionRole tenant isolation; the WorkloadAccessToken bridge degrades gracefully if the dep is absent (already true).
• Delegation act chain (Phase 3) is joinable to feat(observability): end-to-end task attribution and cross-plane trace correlation #245 trace_id and feeds RFC: Governance planes — analytics and compliance export #237 correlation.

Out of scope

• Trace/log attribution mechanics — owned by feat(observability): end-to-end task attribution and cross-plane trace correlation #245 (this RFC consumes its envelope).
• Bedrock billing attribution — feat: Bedrock cost attribution — session tags, request metadata, and operator FinOps guidance #215.
• Workload-anchored credential binding (MicroVM attestation) — separate ROADMAP item; complementary, not blocking.
• Cedar authorization decisions — orthogonal; the delegation chain may inform them later.

Open questions

1. Re-validate USER_FEDERATION/OBO post-GA — is the Phase 2.0a service bug resolved for our region/shape? (Phase 0 gate.)
2. GitHub App vs. per-user 3LO OAuth App — App gives repo-scoped installation tokens (matches "per-repo" ROADMAP item) but is org-installed, not per-user; 3LO gives per-user attribution but coarser repo scope. Leaning App for scoping + commit trailers/act claim for user attribution — decide here.
3. Consent UX for webhook-triggered tasks with no live user — confirm M2M-service-account-for-read, consent-gate-for-write split.
4. Token Vault cost — ~$0.010/1k GetResourceOauth2Token fetches; negligible at current volume, noted for feat: Bedrock cost attribution — session tags, request metadata, and operator FinOps guidance #215 forecasting.

Related

• feat(observability): end-to-end task attribution and cross-plane trace correlation #245 (end-to-end task attribution / cross-plane trace correlation) — sibling on the data plane; this RFC is the credential plane
• feat(security): per-session IAM scoping — session-tagged AssumeRole, DynamoDB leading-key conditions, Bedrock ARN allowlist #209 (per-session IAM scoping, shipped) — must not regress
• feat: Bedrock cost attribution — session tags, request metadata, and operator FinOps guidance #215 (Bedrock cost attribution), RFC: Governance planes — analytics and compliance export #237 (governance/compliance export)
• ROADMAP.md → "Credentials and authorization": Per-repo GitHub credentials, Delegation chain propagation, Layered credential derivation
• Source: "AgentCore Identity, Runtime, and Gateway" engineering deep-dive v1.2 (2026-05-13)

[krokoko]

Just to confirm, this should be independent of the compute substrate since we support also ECS, and will probably add support for other ones in the future
This will work since AC Identity works as an independent primitive but just need to make sure we keep that in mind when designing/implementing the solution

[theagenticguy]

Phase 0 spike plan — re-validate USER_FEDERATION / OBO post-GA (Cognito → GitHub)

Here is a runnable Phase 0 spike. Scope is one thing: does AgentCore Identity's 3LO/OBO flow work for our Cognito-inbound, GitHub-downstream shape now that OBO has GA'd? Or does the Phase 2.0a service-side bug persist? The output is a dated go/no-go. There is no production change.

I verified the API shapes below on 2026-06-04 against the current AWS API references, the boto3 reference, and the AgentCore dev guide. I cross-checked them against our own dormant plumbing at e3abe92.

Three corrections to the RFC's assumptions

1. GithubOauth2 is a first-class built-in vendor. The basic flow needs no CustomOauth2. Its config member githubOauth2ProviderConfig requires only clientId and clientSecret. The create_oauth2_credential_provider call returns a callbackUrl, which you register on the GitHub OAuth App.
2. OBO is not a separate API. ON_BEHALF_OF_TOKEN_EXCHANGE is a sibling enum of the oauth2Flow parameter on GetResourceOauth2Token. You configure the act chain on the provider, under onBehalfOfTokenExchangeConfig → tokenExchangeGrantTypeConfig → actorTokenContent. The allowed values are M2M, AWS_IAM_ID_TOKEN_JWT, and NONE. That matches the RFC's actorTokenContent=M2M design.
3. There is no userId parameter on GetResourceOauth2Token. User binding flows through the workloadIdentityToken. You mint that per user via GetWorkloadAccessTokenForJWT for production or GetWorkloadAccessTokenForUserId for dev. Token caching is per (workload, userId). So our cognito+<sub> label is literal only on the opaque path. On the JWT path, AgentCore derives the key from the validated (iss, sub). My recommendation: bind on the JWT and namespace via iss. That keeps feat(observability): end-to-end task attribution and cross-plane trace correlation #245's user_id and this RFC's token-binding key aligned by construction.

Substrate-independence (per @krokoko below)

AC Identity is an independent primitive here, and the spike now proves that rather than assuming it. The Token Vault calls are plain boto3 control-plane and data-plane operations with no dependency on AgentCore Runtime. The one substrate-specific seam is how the agent acquires the workload token before the vault call: on Runtime the platform injects it as the WorkloadAccessToken header (agentcore-strategy.ts:47-59); on ECS there is no such runtime (ecs-strategy.ts:44-46 accepts userId but marks it unused), so the agent mints it in-process via get_workload_access_token_for_jwt and then makes the identical vault call. Leg C below runs the fetch from a non-Runtime boto3 context to confirm this. The agent keeps one resolve_<integration>_token() seam regardless of backend.

⚠️ The finding that decides Phase 0: PAR

The most likely root cause of the parked Phase 2.0a bug is PAR, the Pushed Authorization Request standard (RFC 9126). AgentCore's USER_FEDERATION 3LO path emits a request_uri parameter on the authorization URL, with no documented opt-out. A provider that does not expose a pushed_authorization_request_endpoint rejects it with a generic ValidationException: Invalid request that swallows the provider's real error. GitHub's OAuth2 server has historically not advertised PAR. This is tracked upstream as aws/bedrock-agentcore-sdk-python#111, still open, with a proposed use_par flag as the fix.

The spike tests this first, and it is the most likely no-go. If the GitHub 3LO leg trips this ValidationException, that is the same class of failure that parked us. The right call then is to stay on the Secrets Manager PAT, record the dated reason, and watch the issue, rather than spend Phase 1 on a blocked path.

The provider constraint that forces RFC open-question #2 early

The GithubOauth2 vendor accepts only an OAuth App clientId and clientSecret, and it drives only 3LO. It exposes no field for a GitHub App ID, private key, or installation ID. So the RFC's lean toward a GitHub App for repo-scoped installation tokens is not natively expressible through the vault. The spike validates the OAuth App 3LO path that AgentCore actually offers. The App-versus-OAuth-App choice then becomes an explicit Phase 1 fork:

Option	Repo scoping	Lifetime	User attribution	Via AgentCore vault?
OAuth App 3LO (repo)	Org-wide, all the user can touch	Long-lived, no expiry by default	Native	Yes, GithubOauth2
GitHub App installation token	Per-repo	1 hour	Bot actor, needs trailers	No, side-channel mint
GitHub App user-to-server	Installation ∩ user access	8h + 6mo refresh	Native	No, not the GithubOauth2 shape

Runnable steps

Everything is throwaway, in us-east-1, under a sandbox account. Provision in this order: a GitHub OAuth App, a throwaway private repo, the credential provider, the workload identity, a throwaway Cognito pool and user, and a scoped IAM spike role. The provider step yields the callback URL you register back on the OAuth App, so the ordering matters.

import boto3
cp = boto3.client("bedrock-agentcore-control", region_name="us-east-1")
resp = cp.create_oauth2_credential_provider(
    name="abca-spike-github",
    credentialProviderVendor="GithubOauth2",
    oauth2ProviderConfigInput={"githubOauth2ProviderConfig": {
        "clientId": "<oauth-app-client-id>", "clientSecret": "<oauth-app-client-secret>"}},
)
# Register resp["callbackUrl"] on the GitHub OAuth App, THEN:
cp.create_workload_identity(name="abca-spike-workload")

Leg A is the primary gate: USER_FEDERATION 3LO against GitHub.

ac = boto3.client("bedrock-agentcore", region_name="us-east-1")
wat = ac.get_workload_access_token_for_user_id(
    workloadName="abca-spike-workload", userId="cognito+<sub>")["workloadAccessToken"]
r = ac.get_resource_oauth2_token(
    workloadIdentityToken=wat,
    resourceCredentialProviderName="abca-spike-github",
    scopes=["repo"],                       # add "workflow" only if commits touch .github/workflows/*
    oauth2Flow="USER_FEDERATION",
    resourceOauth2ReturnUrl="<allowed-return-url>",
    forceAuthentication=True,
)
# First call returns authorizationUrl + sessionUri, sessionStatus=IN_PROGRESS, no accessToken.
# >>> Inspect authorizationUrl for a request_uri (PAR) param BEFORE consenting. <<<

Consent within the 10-minute auth-URL TTL. Then re-call with forceAuthentication=False and assert that an accessToken returns. Use it to push a commit and open a PR on the throwaway repo. Repeat the token mint with get_workload_access_token_for_jwt(workloadName=..., userToken=<cognito_id_token>) to exercise the production (iss, sub) binding.

Leg B is a secondary OBO smoke test. Add onBehalfOfTokenExchangeConfig with actorTokenContent="M2M", then call get_resource_oauth2_token(..., oauth2Flow="ON_BEHALF_OF_TOKEN_EXCHANGE"). This confirms the flow is reachable and the act-claim config is accepted. The RFC defers OBO to Phase 3, so no real downstream is needed.

Leg C proves substrate-independence. Run the token-fetch legs from a plain boto3 context that is not AgentCore Runtime, such as a bare Lambda or a local session. Confirm two things: the vault calls succeed with no Runtime in the loop, and the same get_resource_oauth2_token shape returns a usable token whether the workload token came from the Runtime header or from an in-process get_workload_access_token_for_jwt call. This models the ECS path and is a GO criterion.

Teardown is clean: delete_oauth2_credential_provider, delete_workload_identity, delete-user-pool (cascades), plus deleting the OAuth App, the repo, and the IAM role. Nothing touches the ABCA deployment account.

Go / no-go criteria

Record the verdict with date and region in the Phase 0 acceptance box.

• GO. GitHub accepts the 3LO auth URL with no PAR ValidationException. After consent, the forceAuthentication=False call returns a usable token. That token pushes a commit and opens a PR. The JWT-binding leg resolves the Cognito (iss, sub). Proceed to Phase 1.
• NO-GO. The auth URL trips the PAR ValidationException against GitHub (#111), or no token caches, or JWT binding fails. Stay on the PAT, watch #111, and re-spike when the SDK ships the opt-out.
• CONDITIONAL-GO. 3LO works, but the OAuth App's coarse, long-lived repo token is too broad. Phase 1 then carries the GitHub-App side-channel decision instead of the plain vault path.

Target region and IAM

Use us-east-1. It sits in both the 2025-10 base-GA 9-region set and the 2026-04-30 OBO 14-region set, it matches every official sample, and it is where we last observed the WorkloadAccessToken header at server.py:289. The spike role needs bedrock-agentcore:GetResourceOauth2Token, GetWorkloadAccessTokenForUserId and ...ForJWT, secretsmanager:GetSecretValue on bedrock-agentcore-identity!default/oauth2/<provider>*, plus the control-plane create and delete operations. The production invoke path already holds bedrock-agentcore:InvokeAgentRuntimeForUser at task-orchestrator.ts:288-289.

---

Drafted by Bonk. API shapes verified 2026-06-04 against current AWS API references, the boto3 reference, and the AgentCore dev guide. Code seams verified against e3abe92. The full plan, with the complete call sheet and source list, lives in the understanding tree at understanding/RFC_249_PHASE0_SPIKE.md.

[theagenticguy]

@krokoko agreed, and the point matters enough that the spike should prove it rather than assume it. Here is how I'm folding substrate-independence into Phase 0.

Why AC Identity is substrate-independent here. The Token Vault calls are plain control-plane and data-plane boto3 operations. create_oauth2_credential_provider on bedrock-agentcore-control, and get_workload_access_token_for_* plus get_resource_oauth2_token on bedrock-agentcore, have no dependency on AgentCore Runtime. They run the same from a Lambda, an ECS Fargate task, or a laptop. That is exactly the "independent primitive" property you describe.

The one seam that is substrate-specific is how the agent acquires the workload identity token before it calls get_resource_oauth2_token. The codebase already splits cleanly on this:

• On AgentCore Runtime, runtimeUserId makes the platform inject the token as the WorkloadAccessToken request header (cdk/src/handlers/shared/strategies/agentcore-strategy.ts:47-59). No boto3 call is needed to obtain it.
• On ECS, no runtime injects anything. ecs-strategy.ts:44-46 accepts userId but marks it unused for exactly this reason, and the task falls back to a Secrets Manager env var today. Under this RFC the ECS agent would instead mint the token in-process with get_workload_access_token_for_jwt(workloadName, userToken) and then make the identical vault call.

So the downstream call shape is one seam regardless of substrate. The agent keeps a single resolve_<integration>_token() function; the backend only decides whether the workload token arrives by header or by in-process boto3. The deep-dive §15 documents the raw-boto3 form for the ECS path.

What changes in the spike to verify this, not presume it:

1. Run the token-fetch legs from a plain boto3 context, deliberately not from inside AgentCore Runtime. If get_resource_oauth2_token returns a usable GitHub token when called from a bare Lambda or local boto3 session, that is direct evidence the vault is substrate-agnostic.
2. Add an acceptance criterion: the same get_resource_oauth2_token request shape succeeds whether the workload token was obtained via the Runtime header or via an in-process get_workload_access_token_for_jwt call. The spike exercises both token-acquisition paths against one provider.
3. Bind on the Cognito JWT via get_workload_access_token_for_jwt rather than the opaque-userId path, so the binding key derives from (iss, sub) and stays identical across substrates. That also keeps it aligned with feat(observability): end-to-end task attribution and cross-plane trace correlation #245's user_id.

I've updated the Phase 0 plan comment and the design notes to carry this explicitly. Net: no design change, just a sharper Phase 0 that fails if the vault turns out to be coupled to Runtime. Thanks for flagging it before implementation.

— drafted by Bonk