Threat protection enforcement concepts Threat protection options Prerequisites Configuring advanced security

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:

A user pool with an app client. For more information, see Getting started with user pools.
Set multi-factor authentication (MFA) to Optional in the Amazon Cognito console to use the risk-based adaptive authentication feature. For more information, see Adding MFA to a user pool.
If you're using email notifications, go to the Amazon SES console to configure and verify an email address or domain to use with your email notifications. For more information about Amazon SES, see Verifying Identities in Amazon SES.

Setting up advanced security features and threat protection

Follow these instructions to set up Amazon Cognito advanced security features.

Note

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.

Amazon Web Services Management Console

To configure advanced security for a user pool

Go to the Amazon Cognito console. If prompted, enter your Amazon 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:
1. Select whether you will take Custom action or use or Cognito defaults to respond to suspected Compromised credentials. Cognito defaults are:
  1. Detect compromised credentials on Sign-in, Sign-up, and Password change.
  2. Respond to compromised credentials with the action Block sign-in.
2. 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.
3. 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.
4. 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:
  1. Allow sign-in - Take no preventative action.
  2. 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.
  3. 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.
  4. Block sign-in - Prevent the user from signing in.
  5. 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.
1. 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.
2. 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.


{
   "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"
}

Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Access token customization

Compromised credentials