Threat
protection
Threat protection is the collective term for the features that monitor user operations
for signs of account takeover and automatically respond to secure affected user accounts.
You can apply threat protection settings to users when they sign in with
standard
and custom authentication
flows.
Threat protection generates
logs that detail users' sign-in, sign-out, and other activity. You can export these
logs to a third-party system. For more information, see Viewing
and exporting user event history.
Threat protection enforcement concepts
Threat protection starts out in an audit-only mode
where your user pool monitors user activity, assigns risk levels, and generates logs. As a
best practice, run in audit-only mode for two weeks or more before you enable full-function mode. Full-function mode includes a set of
automatic reactions to detected risky activity and compromised passwords. With audit-only
mode, you can monitor the threat assessments that Amazon Cognito is performing. You can also provide feedback
that trains the feature on false positives and negatives.
You can configure threat protection enforcement at the user pool level to cover all
app clients in the user pool, and at the level of individual app clients. App client
threat-protection configurations override the user pool configuration. To configure threat
protection for an app client, navigate to the app client settings from the App
integration tab of your user pool in the Amazon Cognito console. There, you can
Use client-level settings and configure enforcement exclusive to
the app client.
Additionally, you can configure threat protection separately for
standard
and custom authentication types.
Threat protection for standard authentication and custom
authentication
The ways that you can configure threat protection depend on the type of authentication
you're doing in your user pool and app clients. Each of the following types of
authentication can have their own enforcement mode and automated responses.
- Standard authentication
-
Standard authentication is user sign-in,
sign-out and password management with username-password flows and in the hosted UI.
Amazon Cognito threat protection monitors operations for indicators of risk when they sign in
with the hosted UI or use the following API AuthFlow parameters:
- InitiateAuth
-
USER_PASSWORD_AUTH, USER_SRP_AUTH. The
compromised credentials feature doesn't have access to passwords in
USER_SRP_AUTH sign-in, and doesn't monitor or act on events
with this flow.
- AdminInitiateAuth
-
ADMIN_USER_PASSWORD_AUTH, USER_SRP_AUTH. The
compromised credentials feature doesn't have access to passwords in
USER_SRP_AUTH sign-in, and doesn't monitor or act on events
with this flow.
You can set the Enforcement mode for standard
authentication to Audit only or Full
function. To disable threat monitoring for standard authentication,
disable advanced security features.
- Custom authentication
-
Custom authentication is user sign-in with
custom challenge Lambda triggers.
You can't do custom authentication in the hosted UI. Amazon Cognito threat protection
monitors operations for indicators of risk when they sign in with the API
AuthFlow parameter CUSTOM_AUTH of
InitiateAuth and AdminInitiateAuth.
You can set the Enforcement mode for custom authentication
to Audit only, Full function, or
No enforcement. The No enforcement
option disables threat monitoring for custom authentication without affecting other
advanced security features.
Threat protection
prerequisites
Before you begin, you need the following:
Follow these instructions to set up Amazon Cognito advanced security features.
To set up a different threat protection configuration for an app client in the
Amazon Cognito user pools console, select the app client from the App integration tab
and choose Use client-level settings.
- AWS Management Console
-
To configure advanced security for a user pool
-
Go to the Amazon Cognito
console. If prompted, enter your AWS credentials.
-
Choose User Pools.
-
Choose an existing user pool from the list, or create a user
pool.
-
Choose the Advanced security tab and select
Activate.
-
Choose the threat protection method that you want to configure:
Standard and custom
authentication.
You can set different enforcement modes for custom and standard authentication,
but they share the configuration of automated responses in Full
function mode.
-
Select Edit.
-
Choose an Enforcement mode. To start responding to
detected risks immediately, select Full function and
configure the automated responses for compromised credentials and adaptive
authentication. To gather information in user-level logs and in CloudWatch, select
Audit only .
Advanced security pricing applies in both Audit only
and Full function mode. For more information, see Amazon Cognito Pricing.
We recommend that you keep advanced security features in audit mode for two
weeks before enabling actions. During this time, Amazon Cognito can learn the usage
patterns of your app users and you can provide event feedback to adjust
responses.
-
If you selected Audit only, choose Save
changes. If you selected Full function:
-
Select whether you will take Custom action or use
or Cognito defaults to respond to suspected
Compromised credentials. Cognito
defaults are:
-
Detect compromised credentials on Sign-in,
Sign-up, and Password
change.
-
Respond to compromised credentials with the action Block
sign-in.
-
If you selected Custom actions for
Compromised credentials, choose the user pool actions
that Amazon Cognito will use for Event detection and the
Compromised credentials responses that you would like
Amazon Cognito to take. You can Block sign-in or Allow
sign-in with suspected compromised credentials.
-
Choose how to respond to malicious sign-in attempts under
Adaptive authentication. Select whether you will take
Custom action or use or Cognito
defaults to respond to suspected malicious activity. When you
select Cognito defaults, Amazon Cognito blocks sign-in at all
risk levels and does not notify the user.
-
If you selected Custom actions for
Adaptive authentication, choose the
Automatic risk response actions that Amazon Cognito will take
in response to detected risks based on severity level. When you assign a
response to a level of risk, you can't assign a less-restrictive response to
a higher level of risk. You can assign the following responses to risk
levels:
-
Allow sign-in - Take no preventative
action.
-
Optional MFA - If the user has MFA configured,
Amazon Cognito will always require the user to provide an additional SMS or
time-based one-time password (TOTP) factor when they sign in. If the
user does not have MFA configured, they can continue signing in
normally.
-
Require MFA - If the user has MFA
configured, Amazon Cognito will always require the user to provide an additional
SMS or TOTP factor when they sign in. If the user does not have MFA
configured, Amazon Cognito will prompt them to set up MFA. Before you
automatically require MFA for your users, configure a mechanism in your
app to capture phone numbers for SMS MFA, or to register authenticator
apps for TOTP MFA.
-
Block sign-in - Prevent the user
from signing in.
-
Notify user - Send an email message
to the user with information about the risk that Amazon Cognito detected and the
response you have taken. You can customize email message templates for
the messages you send.
-
If you chose Notify user in the previous step, you can
customize your email delivery settings and email message templates for adaptive
authentication.
-
Under Email configuration, choose the SES
Region, FROM email address, FROM
sender name, and REPLY-TO email address
that you want to use with adaptive authentication. For more information
about integrating your user pool email messages with Amazon Simple Email Service, see Email settings for Amazon Cognito user pools.
-
Expand Email templates to customize adaptive
authentication notifications with both HTML and plaintext versions of email
messages. To learn more about email message templates, see Message templates.
-
Expand IP address exceptions to create an
Always-allow or an Always-block list
of IPv4 or IPv6 address ranges that will always be allowed or blocked,
regardless of the advanced security risk assessment. Specify the IP address
ranges in CIDR notation (such as 192.168.100.0/24).
-
Choose Save changes.
- API (user pool)
-
To set the advanced security configuration for a user pool, send a SetRiskConfiguration API request that includes a UserPoolId
parameter, but not a ClientId parameter. The following is an example
request body for a user pool. This risk configuration takes an escalating series of
actions based on the severity of risk and notifies users at all risk levels. It
applies a compromised-credentials block to sign-up operations.
To enforce this configuration, you must set AdvancedSecurityMode to
ENFORCED in a separate CreateUserPool or UpdateUserPool API request. For more information about the placeholder
templates like {username} in this example, see Configuring verification and
invitation messages.
{
"AccountTakeoverRiskConfiguration": {
"Actions": {
"HighAction": {
"EventAction": "MFA_REQUIRED",
"Notify": true
},
"LowAction": {
"EventAction": "NO_ACTION",
"Notify": true
},
"MediumAction": {
"EventAction": "MFA_IF_CONFIGURED",
"Notify": true
}
},
"NotifyConfiguration": {
"BlockEmail": {
"Subject": "You have been blocked for suspicious activity",
"TextBody": "We blocked {username} at {login-time} from {ip-address}."
},
"From": "admin@example.com",
"MfaEmail": {
"Subject": "Suspicious activity detected, MFA required",
"TextBody": "Unexpected sign-in from {username} on device {device-name}. You must use MFA."
},
"NoActionEmail": {
"Subject": "Suspicious activity detected, secure your user account",
"TextBody": "We noticed suspicious sign-in activity by {username} from {city}, {country} at {login-time}. If this was not you, reset your password."
},
"ReplyTo": "admin@example.com",
"SourceArn": "arn:aws:ses:us-west-2:123456789012:identity/admin@example.com"
}
},
"CompromisedCredentialsRiskConfiguration": {
"Actions": {
"EventAction": "BLOCK"
},
"EventFilter": [ "SIGN_UP" ]
},
"RiskExceptionConfiguration": {
"BlockedIPRangeList": [ "192.0.2.0/24","198.51.100.0/24" ],
"SkippedIPRangeList": [ "203.0.113.0/24" ]
},
"UserPoolId": "us-west-2_EXAMPLE"
}
- API (app client)
-
To set the advanced security configuration for an app client, send a SetRiskConfiguration API request that includes a UserPoolId
parameter and a ClientId parameter. The following is an example request
body for an app client. This risk configuration is more severe than the user pool
configuration, blocking high-risk entries. It also applies compromised-credentials
blocks to sign-up, sign-in, and password-reset operations.
To enforce this configuration, you must set AdvancedSecurityMode to
ENFORCED in a separate CreateUserPool or UpdateUserPool API request. For more information about the placeholder
templates like {username} in this example, see Configuring verification and
invitation messages.
{
"AccountTakeoverRiskConfiguration": {
"Actions": {
"HighAction": {
"EventAction": "BLOCK",
"Notify": true
},
"LowAction": {
"EventAction": "NO_ACTION",
"Notify": true
},
"MediumAction": {
"EventAction": "MFA_REQUIRED",
"Notify": true
}
},
"NotifyConfiguration": {
"BlockEmail": {
"Subject": "You have been blocked for suspicious activity",
"TextBody": "We blocked {username} at {login-time} from {ip-address}."
},
"From": "admin@example.com",
"MfaEmail": {
"Subject": "Suspicious activity detected, MFA required",
"TextBody": "Unexpected sign-in from {username} on device {device-name}. You must use MFA."
},
"NoActionEmail": {
"Subject": "Suspicious activity detected, secure your user account",
"TextBody": "We noticed suspicious sign-in activity by {username} from {city}, {country} at {login-time}. If this was not you, reset your password."
},
"ReplyTo": "admin@example.com",
"SourceArn": "arn:aws:ses:us-west-2:123456789012:identity/admin@example.com"
}
},
"ClientId": "1example23456789",
"CompromisedCredentialsRiskConfiguration": {
"Actions": {
"EventAction": "BLOCK"
},
"EventFilter": [ "SIGN_UP", "SIGN_IN", "PASSWORD_CHANGE" ]
},
"RiskExceptionConfiguration": {
"BlockedIPRangeList": [ "192.0.2.1/32","192.0.2.2/32" ],
"SkippedIPRangeList": [ "192.0.2.3/32","192.0.2.4/32" ]
},
"UserPoolId": "us-west-2_EXAMPLE"
}
