Amazon Cognito aws-auth Skill: What Agents Can (and Cannot) Configure for You

On Aug 7, 2026, AWS announced that Amazon Cognito is available as a core skill (aws-auth) in the Agent Toolkit for AWS. AI coding agents that already use Cursor, Claude Code, Codex, or Kiro can load curated Cognito workflows—user pools and app clients, managed login and OAuth 2.0, tokens, JWT authorizers, passkeys/WebAuthn, threat protection, Lambda trigger wiring, and identity pools—instead of improvising from stale training data.

That matters because auth is not a greenfield script. When an agent can call Cognito APIs, it is part of your software supply chain: the wrong app-client update can wipe MFA flows; the wrong identity-pool role can open guest access; the wrong authorizer audience can 401 every legitimate user. Skills narrow variance. They do not replace IAM boundaries or human review.

Reproduce this — Install the atomic skill from the official repo: npx skills add https://github.com/aws/agent-toolkit-for-aws --skill aws-auth. Browse the published pack on skills.sh/aws/agent-toolkit-for-aws/aws-auth. Source of truth: skills/core-skills/aws-auth/SKILL.md in aws/agent-toolkit-for-aws.

The shift in one sentence

Cognito configuration becomes a shared runbook agents can load on demand—with progressive disclosure into nine reference files—rather than a one-off chat that invents OAuth grant types and then “fixes” production with a partial update-user-pool-client.

What shipped (and the numbers we can verify)

From the Aug 7, 2026 What’s New post and a checkout of main at commit 171d4fba3bc404da3473f323c3e293b4a989f089:

• aws-auth is a core skill under skills/core-skills/aws-auth/, not a one-off gist.
• Nine reference packs sit beside SKILL.md: user pools, managed login/OAuth, tokens and sessions, identity pools, API authorization, Lambda triggers, passkeys, threat protection, and troubleshooting.
• Skill inventory growth is real: that same commit contains 146 SKILL.md files across the toolkit. Our May 2026 field guide counted 43 at commit 75023075—treat any stale screenshot of “how many skills” as wrong until you re-count.
• Early adoption signal (public registry, not a customer claim): as of this writing, skills.sh lists 603 installs for aws-auth (first seen about nine days before publish). Re-check the registry before you quote the number in an internal decision log—it moves.

When paired with the managed AWS MCP Server, agents execute AWS CLI-shaped operations under IAM guardrails with CloudTrail audit logging. The skill also works standalone via the AWS CLI—no hard MCP dependency.

What the skill covers (and why each cluster matters)

Each bullet in the announcement is a place where silent success on an API call can still break users later. That is why the skill’s own critical warnings matter more than the feature list.

Install path (version context)

Assumes Node with npx available, and an Agent Skills–compatible coding agent. Pin the toolkit commit in your internal runbook after install.

# Agent Skills CLI — atomic install of Cognito aws-auth
npx skills add https://github.com/aws/agent-toolkit-for-aws --skill aws-auth

Prefer the aws-core (or equivalent) plugin path when your org wants MCP wiring + a curated skill set in one install; cherry-pick aws-auth when you want Cognito procedures without dumping the whole tree into every developer’s skill folder. See our Agent Toolkit skills guide for progressive disclosure and plugin vs atomic install trade-offs.

User pool vs identity pool—decide before the agent runs

The skill opens with the decision most teams get wrong:

Recommendation: for API-driven SaaS that only calls your own backend, stop at the user pool and put a Cognito/JWT authorizer on API Gateway (or ALB authenticate-cognito). Add an identity pool only when the client must hit AWS APIs directly. Trade-off: identity pools unlock direct-to-S3 patterns and add IAM role-mapping surface area agents love to over-permission.

Benchmark / rollout pattern (not a cited client) — Mid-market B2B SaaS silhouette: one Cognito user pool, public SPA app client (no secret), authorization code + PKCE via managed login, HTTP API JWT authorizer, optional identity pool only for authenticated browser uploads to a single prefix. Prior pain is usually not “Cognito cannot scale”—it is callback URL drift, token storage in localStorage, and admin APIs run without read-modify-write.

For tenancy and hosted-UI choices beyond agent setup, see AWS Cognito authentication for SaaS and OAuth2 introspection vs JWT validation on Cognito and API Gateway.

Pair aws-auth with MCP when the account is shared

Opinionated default for shared or regulated accounts: load aws-auth + managed AWS MCP Server, with a dedicated agent role per environment.

• Choose MCP + skill when multiple humans and agents will mutate Cognito and you need CloudTrail answers to “who changed this app client?”
• Choose skill + AWS CLI only when MCP is unavailable (lab, air-gap, region constraint)—accept that session audit is thinner and put heavier human gates in front of apply.

Trade-off stated plainly: MCP adds control-plane overhead and region/availability constraints; CLI-only is faster for a solo sandbox and weaker for enterprise evidence. Do not grant the agent AdministratorAccess to “remove the friction.”

What breaks when agents configure Cognito

What broke (skill-documented failure mode) — update-user-pool-client and set-identity-pool-roles are full replace, not partial updates. Omitting fields resets them to defaults: auth flows, token validity, refresh-token rotation, revocation flags, and role mappings can disappear while the API returns success. In an agent session the wipe is invisible until a user cannot sign in. The skill’s fix is mandatory read-modify-write: describe-user-pool-client (or get-identity-pool-roles) first, then resend every existing field plus your change.

Other agent-shaped traps called out in SKILL.md:

• Implicit grant (response_type=token) for new SPAs instead of authorization code + PKCE
• Client secret on a public SPA/mobile client
• Refresh tokens in localStorage on high-value apps (Amplify default) without rotation/revocation
• admin-confirm-sign-up as a bulk fix for UNCONFIRMED users (confirms without proving email ownership)
• Assuming access-token claim customization works on the entry-level Cognito feature plan

Counter-case — If the real problem is workforce SSO into AWS accounts and identity-aware analytics—not customer login—Cognito is the wrong tool. Use IAM Identity Center. If the gap is fine-grained “can this user edit this document?”, Cognito groups alone will not save you—see Amazon Verified Permissions / Cedar.

When not to use aws-auth

From the skill’s own When NOT to use block—treat this as a hard filter before you prompt:

1. Amplify Gen2 backend — defineAuth, amplify/auth.ts, npx ampx (different codegen path).
2. IAM / STS / Identity Center console SSO — different skill and different identity problem.
3. API Gateway routes/integrations and Lambda app code beyond Cognito/JWT authorizer purpose and trigger wiring intent.

If your agent keeps generating Amplify Gen2 auth trees while you asked for a Cognito user pool via CLI/CDK for a non-Amplify app, stop and re-scope the skill—or turn the agent off for that change.

What to Do This Week

1. Install aws-auth with the official npx skills add command above; confirm the agent loads skills/core-skills/aws-auth (not a stale private Markdown cheat sheet).
2. Pin commit 171d4fba3bc404da3473f323c3e293b4a989f089 (or your later audited SHA) in the internal auth runbook so skill drift is intentional.
3. Create a sandbox Cognito exercise: describe an existing app client, then propose a one-field change using read-modify-write—reject any plan that calls update-user-pool-client with a partial payload.
4. Scope the agent IAM role to Cognito describe/update in non-prod only; deny deletes in prod; require MCP where you need CloudTrail session evidence.
5. Review three settings before you celebrate “login works”: authorization code + PKCE (no implicit), no client secret on public clients, threat protection / MFA posture appropriate to the app’s risk.

If You Only Do One Thing

Ban partial update-user-pool-client from agent sessions. Force describe → merge → update. That single rule prevents the most common invisible Cognito outage agents create.

What This Post Doesn’t Cover

• Amplify Gen2 defineAuth codegen and ampx deploy flows
• Full multi-tenant silo-vs-pool Cognito design (covered in our Cognito SaaS guide)
• Amazon Verified Permissions / Cedar policy authoring
• Workforce identity with IAM Identity Center
• Step-by-step MCP JSON for every assistant (those fragments drift—use the toolkit README)

Need a Cognito + agent IAM review before you let coding agents touch prod user pools? FactualMinds is an AWS Select Tier Services Partner—tell us what you are building.

Frequently asked questions