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/passkeys.md
View on GitHub# Passkeys (FIDO2 / WebAuthn) in Cognito
## Overview
Cognito supports passkeys — FIDO2/WebAuthn credentials backed by Face ID, Touch
ID, platform authenticators, or hardware security keys — as a **first-factor**
sign-in method. Passkeys can be the only method, or coexist with passwords so
users choose per session.
## Feature-plan gate
Passkeys require the **Essentials** or **Plus** feature plan. NOT available on
Lite. Set at pool creation or via `update-user-pool --user-pool-tier ESSENTIALS`.
## Two integration paths
Passkeys work through **exactly one of these two paths** — the classic hosted
UI (managed login v1) does NOT support passkeys:
- **Managed login v2** — hosted flow. Create the pool domain with
`--managed-login-version 2`; Cognito renders the passkey prompt automatically.
- **`USER_AUTH` runtime auth flow** — custom UI. App client's `ExplicitAuthFlows`
must include `ALLOW_USER_AUTH`; call `InitiateAuth` with `AuthFlow=USER_AUTH`.
## Pool-level configuration
Two settings enable passkeys at the pool:
1. **`Policies.SignInPolicy.AllowedFirstAuthFactors`** — declares which factors
the pool offers as the first step. Include `WEB_AUTHN` to allow passkeys;
add `PASSWORD` too for coexistence.
```
aws cognito-idp update-user-pool \
--user-pool-id <pool-id> \
--policies 'SignInPolicy={AllowedFirstAuthFactors=[PASSWORD, WEB_AUTHN]}' \
... (re-send every other existing field — full-replace API)
```
Accepted values: `PASSWORD | EMAIL_OTP | SMS_OTP | WEB_AUTHN` (the enum also
lists `SOFTWARE_TOKEN` but docs mark it unusable — do not include).
2. **`WebAuthnConfiguration`** — lives on the pool's **MFA configuration**, NOT
on `SignInPolicy`. Set via `set-user-pool-mfa-config`:
```
aws cognito-idp set-user-pool-mfa-config \
--user-pool-id <pool-id> \
--web-authn-configuration RelyingPartyId=auth.example.com,UserVerification=preferred
```
- `RelyingPartyId` — the origin the passkey is bound to. Must match your
app's domain.
- `UserVerification` — `required` or `preferred` only (Cognito does NOT
accept the WebAuthn-spec `discouraged`).
## App client configuration
Include `ALLOW_USER_AUTH` in `ExplicitAuthFlows`:
```
aws cognito-idp update-user-pool-client \
--user-pool-id <pool-id> --client-id <client-id> \
--explicit-auth-flows ALLOW_USER_AUTH ALLOW_USER_SRP_AUTH ALLOW_REFRESH_TOKEN_AUTH \
... (re-send every other existing field — full-replace API)
```
`ALLOW_USER_AUTH` is distinct from `ALLOW_USER_SRP_AUTH`. Add both if you want
passkey users AND password/SRP users on the same client.
## Password + passkey coexistence
Yes — passkeys and passwords coexist on the **same pool and same app client**;
no need to split. Configure both `PASSWORD` and `WEB_AUTHN` in
`AllowedFirstAuthFactors` and `ALLOW_USER_AUTH` in `ExplicitAuthFlows`.
What each user sees depends on which factors THEY have registered:
- Users with an enrolled passkey → managed login v2 offers passkey first, with
password fallback.
- Users without → password sign-in, with a prompt to add a passkey after.
## `USER_AUTH` sign-in flow (custom UI)
**Agent-directed** — client picks the factor up front via `PREFERRED_CHALLENGE`:
```
aws cognito-idp initiate-auth \
--client-id <client-id> \
--auth-flow USER_AUTH \
--auth-parameters USERNAME=alice@example.com,PREFERRED_CHALLENGE=WEB_AUTHN
```
Valid `PREFERRED_CHALLENGE`: `PASSWORD | PASSWORD_SRP | WEB_AUTHN | EMAIL_OTP | SMS_OTP`.
**User-directed** — omit `PREFERRED_CHALLENGE`; server returns
`ChallengeName: SELECT_CHALLENGE` with `AvailableChallenges: [...]` filtered to
what the user has registered. Client then responds via
`respond-to-auth-challenge` with `ANSWER=<picked>`.
## Enrollment (registering a passkey)
Two-call flow, authorized by user access token — user must be signed in first:
```
aws cognito-idp start-web-authn-registration \
--access-token <user-access-token> # returns PublicKeyCreationOptions
aws cognito-idp complete-web-authn-registration \
--access-token <user-access-token> \
--credential file://attestation.json # browser's attestation
```
WebAuthn APIs authorize via the user's access token (scope
`aws.cognito.signin.user.admin`), NOT via IAM. Companion APIs:
`list-web-authn-credentials`, `delete-web-authn-credential`.
## Authoritative sources
- [`SignInPolicyType`](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SignInPolicyType.html) — `AllowedFirstAuthFactors` enum
- [`WebAuthnConfigurationType`](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_WebAuthnConfigurationType.html) — on `SetUserPoolMfaConfig`
- [`InitiateAuth`](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) — `USER_AUTH` flow
- [Sign-in with passkeys](https://docs.aws.amazon.com/cognito/latest/developerguide/authentication.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 |