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/threat-protection.md
View on GitHub# Threat Protection & Adaptive Authentication
## Overview
Cognito's threat protection (formerly "advanced security features") detects and
responds to suspicious sign-in activity: compromised (breached) passwords,
risky patterns (new device, unusual IP), and risk-based adaptive MFA.
## Feature-plan gate
Threat protection features require the **Plus** feature plan:
- `AdvancedSecurityMode = AUDIT | ENFORCED` — Plus only.
- Adaptive-auth risk configuration — Plus only.
- Threat-protection log delivery (`userAuthEvents` event source) — Plus only.
Attempting these on a lower tier returns `FeatureUnavailableInTierException`.
Set via `update-user-pool --user-pool-tier PLUS`.
## `AdvancedSecurityMode` — three modes
Lives on `UserPool.UserPoolAddOns.AdvancedSecurityMode` (nested, not top-level):
| Mode | Behavior |
|------|----------|
| `OFF` | Threat protection disabled |
| `AUDIT` | Records risk assessments; takes NO action. Data-gathering mode |
| `ENFORCED` | Records AND applies your configured risk responses |
Toggle via `update-user-pool` (NOT `set-risk-configuration`):
```
aws cognito-idp update-user-pool \
--user-pool-id <pool-id> \
--user-pool-add-ons AdvancedSecurityMode=ENFORCED \
... (re-send every other existing field — full-replace API)
```
## Compromised-credentials protection
Detects passwords on known-breached lists. Configure via `set-risk-configuration`:
```
aws cognito-idp set-risk-configuration \
--user-pool-id <pool-id> \
--compromised-credentials-risk-configuration \
'Actions={EventAction=BLOCK},EventFilter=[SIGN_IN,SIGN_UP,PASSWORD_CHANGE]'
```
- `EventAction`: **`BLOCK`** (reject the auth attempt) or **`NO_ACTION`** (log only).
- `EventFilter`: any subset of `SIGN_IN | SIGN_UP | PASSWORD_CHANGE`. Defaults
to all three when omitted.
- Omit `--client-id` for pool-wide config; include it to scope to one client.
## Adaptive authentication (risk-based MFA)
Cognito classifies each sign-in as **No Risk / Low / Medium / High**. The API
exposes **three configurable action tiers** (`LowAction` / `MediumAction` /
`HighAction`) — `No Risk` proceeds without triggering any Action.
```
aws cognito-idp set-risk-configuration \
--user-pool-id <pool-id> \
--account-takeover-risk-configuration '
NotifyConfiguration={
SourceArn=arn:aws:ses:us-east-1:<account>:identity/no-reply@example.com,
From=no-reply@example.com
},
Actions={
LowAction={EventAction=NO_ACTION,Notify=false},
MediumAction={EventAction=MFA_IF_CONFIGURED,Notify=true},
HighAction={EventAction=MFA_REQUIRED,Notify=true}
}'
```
### `EventAction` — four values per tier
| Value | Behavior |
|-------|----------|
| `NO_ACTION` | Allow the sign-in |
| `MFA_IF_CONFIGURED` | Require MFA if the user has it set up; allow otherwise (**optional MFA**) |
| `MFA_REQUIRED` | Require MFA; block if user has no MFA method (**required MFA**) |
| `BLOCK` | Reject the sign-in outright |
Do NOT collapse `MFA_IF_CONFIGURED` and `MFA_REQUIRED` — they behave differently.
Typical: `Low → NO_ACTION`, `Medium → MFA_IF_CONFIGURED`, `High → MFA_REQUIRED`
or `BLOCK`.
### `NotifyConfiguration`
- **`SourceArn`** is **required** and must be a verified SES identity ARN.
- Optional: `From`, `ReplyTo`, and per-outcome message bodies (`BlockEmail`,
`MfaEmail`, `NoActionEmail`, each with `Subject`/`HtmlBody`/`TextBody`).
## Log delivery to CloudWatch
Route threat-protection events to CloudWatch/S3/Firehose via
`set-log-delivery-configuration`:
```
aws cognito-idp set-log-delivery-configuration \
--user-pool-id <pool-id> \
--log-configurations '[
{
"EventSource": "userAuthEvents",
"LogLevel": "INFO",
"CloudWatchLogsConfiguration": {"LogGroupArn": "arn:aws:logs:<region>:<account>:log-group:<name>"}
}
]'
```
**Enum-pair rules** (Cognito rejects mismatched pairs):
| `EventSource` | `LogLevel` | Purpose | Tier |
|---------------|------------|---------|------|
| `userAuthEvents` | `INFO` | Threat-protection sign-in events | Plus |
| `userNotification` | `ERROR` | Message-delivery errors (SMS, email) | Lite+ |
**Encrypt the target CloudWatch Logs log group with a customer-managed KMS key** —
threat-protection events contain user PII (IP addresses, user identifiers) and sign-in
risk metadata. Either set the KMS key at log-group creation, or associate one after the
fact:
```
aws logs associate-kms-key \
--log-group-name /aws/cognito/<pool-id> \
--kms-key-id arn:aws:kms:<region>:<account>:key/<key-id>
```
The KMS key policy must allow the `logs.<region>.amazonaws.com` service principal
`kms:Encrypt*` / `kms:Decrypt*` / `kms:GenerateDataKey*` / `kms:Describe*` scoped to
the log group ARN via `kms:EncryptionContext:aws:logs:arn`.
## Inspect current state
```
aws cognito-idp describe-user-pool --user-pool-id <pool-id> # AdvancedSecurityMode
aws cognito-idp describe-risk-configuration --user-pool-id <pool-id> # risk config
aws cognito-idp get-log-delivery-configuration --user-pool-id <pool-id>
```
## Gotchas
- `UserPoolAddOns` block may be absent if threat protection never enabled —
inspect defensively: `pool.get("UserPoolAddOns", {}).get("AdvancedSecurityMode")`.
- Downgrading Plus → lower tier fails while `AdvancedSecurityMode` is
`AUDIT`/`ENFORCED`. Set to `OFF` first, then change tier.
- `set-risk-configuration` with only `UserPoolId` clears the config to defaults
— always read-modify-write.
## Authoritative sources
- [Threat protection](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-settings-threat-protection.html)
- [`SetRiskConfiguration`](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SetRiskConfiguration.html)
- [`SetLogDeliveryConfiguration`](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SetLogDeliveryConfiguration.html)
- [Feature plans](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-sign-in-feature-plans.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 |