opensite-ai/opensite-skills / aws-auth
aws-auth
VerifiedAdds user authentication to web and mobile apps with Amazon Cognito (user pools and identity pools) and the AWS Amplify client auth libraries. Covers sign-up/sign-in flows and the login page (Cognito-hosted UI / managed login), MFA, password policies, OAuth 2.0 / OIDC flows (auth-code + PKCE, client credentials), social/SAML federation, tokens (ID/access/refresh, rotation, revocation, storage), Cognito Lambda triggers, identity pools (temp AWS creds), and gating API Gateway (or ALB) routes to signed-in users via Cognito/JWT authorizers. Applies when adding a login or sign-up page, configuring a user pool or app client, choosing user pool vs identity pool, wiring social/SAML, refreshing tokens, requiring sign-in on an API Gateway or ALB, or debugging redirect_uri/token/MFA/CORS/federation errors. Does NOT cover Amplify Gen2 backend definitions (defineAuth, npx ampx → aws-amplify), IAM/STS/Identity Center (→ aws-iam), or API Gateway/Lambda resource config beyond the authorizer (→ aws-serverless).
| File | Kind | Size |
|---|---|---|
| .aws-skill-metadata | other | 18 B |
| SKILL.md | skill md | 13.5 KB |
| references/api-authorization.md | markdown | 5.0 KB |
| references/identity-pools.md | markdown | 5.8 KB |
| references/lambda-triggers.md | markdown | 9.9 KB |
| references/managed-login-oauth.md | markdown | 15.4 KB |
| references/passkeys.md | markdown | 4.9 KB |
| references/threat-protection.md | markdown | 5.9 KB |
| references/tokens-and-sessions.md | markdown | 11.2 KB |
| references/troubleshooting.md | markdown | 4.6 KB |
| references/user-pools.md | markdown | 8.5 KB |
references/identity-pools.md
View on GitHub# Identity Pools (Federated Identities)
## Overview
An identity pool exchanges a proof of authentication (a user pool token, a third-party OIDC/SAML
token, or a social access token) for **temporary AWS credentials** from AWS STS. Use it only when
the client must call AWS services (S3, DynamoDB, etc.) **directly**. If the client only calls your
own backend/API, you do not need an identity pool — send the user pool token to your API instead.
## User pool vs identity pool (the core distinction)
- **User pool** = authentication. "Who are you?" Issues JWTs.
- **Identity pool** = authorization to AWS. "What AWS resources can this identity touch?" Vends
temporary AWS credentials via STS.
They compose: the user signs in to the user pool, then the app passes the ID token to the identity
pool, which returns temporary AWS credentials.
## What each provider passes to an identity pool
The token type is **provider-specific** — get it wrong and identity resolution fails at
configuration time.
| Provider | Authentication artifact |
|----------|-------------------------|
| Cognito user pool | ID token |
| Generic OIDC IdP | ID token |
| Google, Apple (OIDC providers) | ID token (`id_token`) |
| Facebook, Login with Amazon | Access token |
| SAML 2.0 IdP | SAML assertion |
Google and Apple are OIDC providers: pass their **`id_token`** (Cognito reads it from the
`accounts.google.com` / `appleid.apple.com` logins key). Only **Facebook** and **Login with
Amazon** hand the identity pool an **access token**. Wiring Google (or Apple) with an access
token fails identity resolution at config time.
## Create and wire an identity pool
```
aws cognito-identity create-identity-pool \
--identity-pool-name my_app_identities \
--no-allow-unauthenticated-identities \
--cognito-identity-providers ProviderName=cognito-idp.<region>.amazonaws.com/<pool-id>,ClientId=<app-client-id>
aws cognito-identity set-identity-pool-roles \
--identity-pool-id <identity-pool-id> \
--roles authenticated=<auth-role-arn>
```
**`set-identity-pool-roles` replaces the entire roles + `RoleMappings` structure — it is a full
replace, not a merge.** To add or change one role mapping on a pool that already has roles or
mappings, first read the current state with `aws cognito-identity get-identity-pool-roles
--identity-pool-id <id>`, then re-send **all** existing roles and `RoleMappings` plus your addition
in a single `set-identity-pool-roles` call. Sending only the new mapping silently drops the
existing default role and every other mapping.
**The authenticated role's trust policy MUST scope to this identity pool** to prevent
confused-deputy attacks where another Cognito identity pool assumes the role. IAM role
authoring itself belongs to the `aws-iam` skill, but this identity-pool-specific condition
is not covered there:
```json
"Condition": {
"StringEquals": { "cognito-identity.amazonaws.com:aud": "<identity-pool-id>" },
"ForAnyValue:StringLike": { "cognito-identity.amazonaws.com:amr": "authenticated" }
}
```
The `:aud` condition binds the trust to your pool id; `:amr` = `authenticated` ensures the
guest (unauthenticated) role can never assume the authenticated role. Mirror the pattern with
`:amr` = `unauthenticated` on the guest role.
Default to `--no-allow-unauthenticated-identities`. Only enable guest access
(`--allow-unauthenticated-identities` plus an `unauthenticated=<guest-role-arn>` role) when guest
access is genuinely required.
## Two credential flows
- **Enhanced (simplified) flow** — the recommended default. `GetCredentialsForIdentity` returns
credentials in one step; the pool decides the role.
- **Basic (classic) flow** — the app calls `GetOpenIdToken` then `sts:AssumeRoleWithWebIdentity`
itself, for full control over the assumed role.
## Role selection
- **Default role** for all authenticated users.
- **Rules-based** — choose a role from claims (e.g. a group claim).
- **Role from token (`cognito:preferred_role`)** — the user pool group's associated role. When a
user is in multiple groups, the group with the **lowest `Precedence`** value wins; see the
"User pool groups" section in [user-pools.md](user-pools.md) for `create-group` /
`admin-add-user-to-group` and the `--precedence` field.
- **Attributes for access control** — map user claims to STS **principal tags**, then gate access
in resource policies with `aws:PrincipalTag/...`. This is app-level ABAC via Cognito.
Scope the authenticated role tightly (least privilege). The IAM policy language and role authoring
itself belong to the `aws-iam` skill.
## Common Errors
| Error | Cause | Fix |
|-------|-------|-----|
| `NotAuthorizedException` / `Token is not from a supported provider` | Provider not registered on the pool, or wrong ClientId | Match `ProviderName` = `cognito-idp.<region>.amazonaws.com/<pool-id>` and the correct app client id |
| `Access denied` after getting credentials | Authenticated role policy too narrow, or trust policy wrong | Fix the role's permissions (see `aws-iam`); ensure the role trusts `cognito-identity.amazonaws.com` with the pool id condition |
| Guests unexpectedly allowed | Unauthenticated identities enabled | Disable guest access; remove the unauthenticated role |
## Related
- [tokens-and-sessions.md](tokens-and-sessions.md) for the token you feed in.
- `aws-iam` skill for authoring the authenticated/guest IAM roles and their trust policies.
- **Authoritative sources** (for guest access details, basic vs enhanced flow, developer-authenticated identities, and multi-provider linking — topics this skill intentionally does not cover): [Amazon Cognito identity pools (developer guide)](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) and [External identity providers](https://docs.aws.amazon.com/cognito/latest/developerguide/external-identity-providers.html).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |