Using adaptive authentication - Amazon Cognito
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Using adaptive authentication

With adaptive authentication, you can configure your user pool to block suspicious sign-ins or add second factor authentication in response to an increased risk level. For each sign-in attempt, Amazon Cognito generates a risk score for how likely the sign-in request is to be from a compromised source. This risk score is based on factors that include device and user information. Adaptive authentication can turn on or require multi-factor authentication (MFA) for a user in your user pool when Amazon Cognito detects risk in a user's session, and the user hasn't yet chosen an MFA method. When you activate MFA for a user, they always receive a challenge to provide or set up a second factor during authentication, regardless of how you configured adaptive authentication. From your user's perspective, your app offers to help them set up MFA, and optionally Amazon Cognito prevents them from signing in again until they have configured an additional factor.

Amazon Cognito publishes sign-in attempts, their risk levels, and failed challenges to Amazon CloudWatch. For more information, see Viewing advanced security metrics.

To add adaptive authentication to your user pool, see Adding advanced security to a user pool.

Adaptive authentication overview

From Advanced security in the App integration tab of the Amazon Cognito console, you can choose settings for adaptive authentication, including what actions to take at different risk levels and customization of notification messages to users. You can assign a global advanced security configuration to all of your app clients, but apply a client-level configuration to individual app clients.

Amazon Cognito adaptive authentication assigns one of the following risk levels to each user session: High, Medium, Low, or No Risk.

Consider your options carefully when you change your Enforcement method from Audit-only to Full-function. The automatic responses that you apply to risk levels influence the risk level that Amazon Cognito assigns to subsequent user sessions with the same characteristics. For example, after you choose to take no action, or Allow, user sessions that Amazon Cognito initially evaluates to be high-risk, Amazon Cognito considers similar sessions to have a lower risk.

For each risk level, you can choose from the following options:

Option

Action

Allow Users can sign in without an additional factor.
Optional MFA Users who have a second factor configured must complete a second factor challenge to sign in. A phone number for SMS and a TOTP software token are the available second factors. Users without a second factor configured can sign in with only one set of credentials.
Require MFA Users who have a second factor configured must complete a second factor challenge to sign in. Amazon Cognito blocks sign-in for users who don't have a second factor configured.
Block Amazon Cognito blocks all sign-in attempts at the designated risk level.
Note

You don't have to verify phone numbers to use them for SMS as a second authentication factor.

Adding user device and session data to API requests

You can collect and pass information about your user's session to Amazon Cognito advanced security when you use the API to sign them up, sign them in, and reset their password. This information includes your user's IP address and a unique device identifier.

You might have a intermediate network device between your users and Amazon Cognito, like a proxy service or an application server. You can collect users' context data and pass it to Amazon Cognito so that adaptive authentication calculates your risk based on the characteristics of the user endpoint, instead of your server or proxy. If your client-side app calls Amazon Cognito API operations directly, adaptive authentication automatically records the source IP address. However, it does not record other device information like the user-agent unless you also collect a device fingerprint.

Generate this data with the Amazon Cognito context data collection library and submit it to Amazon Cognito advanced security with the ContextData and UserContextData parameters. The context data collection library is included in the Amazon SDKs. For more information, see Integrating Amazon Cognito with web and mobile apps. You can submit ContextData if you have activated advanced security features in your user pool. For more information, see Configuring advanced security features.

When you call the following Amazon Cognito authenticated API operations from your application server, pass the IP of the user’s device in the ContextData parameter. In addition, pass your server name, server path, and encoded device-fingerprinting data.

When you call Amazon Cognito unauthenticated API operations, you can submit UserContextData to Amazon Cognito advanced security features. This data includes a device fingerprint in the EncodedData parameter. You can also submit an IpAddress parameter in your UserContextData if you meet the following conditions:

Your app can populate the UserContextData parameter with encoded device-fingerprinting data and the IP address of the user's device in the following Amazon Cognito unauthenticated API operations.

Accepting additional user context data (Amazon Web Services Management Console)

Your user pool accepts an IP address in a UserContextData parameter after you activate the Accept additional user context data feature. You don’t need to activate this feature if:

  • Your users only sign in with authenticated API operations like AdminInitiateAuth , and you use the ContextData parameter.

  • You only want your unauthenticated API operations to send a device fingerprint, but not an IP address, to Amazon Cognito advanced security features.

Update your app client as follows in the Amazon Cognito console to add support for additional user context data.

  1. Sign in to the Amazon Cognito console .

  2. In the navigation pane, choose Manage your User Pools, and choose the user pool you want to edit.

  3. Choose the App integration tab.

  4. Under App clients and analytics, choose or create an app client. For more information, see Configuring a user pool app client.

  5. Choose Edit from the App client information container.

  6. In the Advanced authentication settings for your app client, choose Accept additional user context data.

  7. Choose Save changes.

To configure your app client to accept user context data in the Amazon Cognito API, set EnablePropagateAdditionalUserContextData to true in a CreateUserPoolClient or UpdateUserPoolClient request. For information about how to activate advanced security from your web or mobile app, see Activating user pool advanced security from your app. When your app calls Amazon Cognito from your server, collect user context data from the client side. The following is an example that uses the JavaScript SDK method getData.

var encodedData = AmazonCognitoAdvancedSecurityData.getData(username, userPoolId, clientId);

When you design your app to use adaptive authentication, we recommend that you incorporate the latest Amazon Cognito SDK into your app.. The latest version of the SDK collects device fingerprinting information like device ID, model, and time zone. For more information about Amazon Cognito SDKs, see Install a user pool SDK. Amazon Cognito advanced security only saves and assigns a risk score to events that your app submits in the correct format. If Amazon Cognito returns an error response, check that your request includes a valid secret hash and that the IPaddress parameter is a valid IPv4 or IPv6 address.

ContextData and UserContextData resources

Viewing user event history

Note

In the new Amazon Cognito console, you can view user event history in the Users tab.

To see the sign-in history for a user, you can choose the user from the Users tab in the Amazon Cognito console. Amazon Cognito retains user event history for two years.

User event history

Each sign-in event has an event ID. The event also has corresponding context data, such as location, device details, and risk detection results. You can query user event history with the Amazon Cognito API operation AdminListUserAuthEvents or with the Amazon Command Line Interface (Amazon CLI) with admin-list-user-auth-events.

You can also correlate the event ID with the token that Amazon Cognito issued at the time that it recorded the event. The ID and access tokens include this event ID in their payload. Amazon Cognito also correlates refresh token use to the original event ID. You can trace the original event ID back to the event ID of the sign-in event that resulted in issuing the Amazon Cognito tokens. You can trace token usage within your system to a particular authentication event. For more information, see Using tokens with user pools.

Providing event feedback

Event feedback affects risk evaluation in real time and improves the risk evaluation algorithm over time. You can provide feedback on the validity of sign-in attempts through the Amazon Cognito console and API operations.

Note

Your event feedback influences the risk level that Amazon Cognito assigns to subsequent user sessions with the same characteristics.

In the Amazon Cognito console, choose a user from the Users tab and select Provide event feedback. You can review the event details and Set as valid or Set as invalid.

The console lists the sign-in history on the Users and groups tab. If you select an entry, you can mark the event as valid or not valid. You can also provide feedback through the user pool API operation AdminUpdateAuthEventFeedback, and through the Amazon CLI command admin-update-auth-event-feedback.

When you select Set as valid in the Amazon Cognito console or provide a FeedbackValue value of valid in the API, you tell Amazon Cognito that you trust a user session where Amazon Cognito has evaluated some level of risk. When you select Set as invalid in the Amazon Cognito console or provide a FeedbackValue value of invalid in the API, you tell Amazon Cognito that you don't trust a user session, or you don't believe that Amazon Cognito evaluated a high-enough risk level.

Sending notification messages

With advanced security protections, Amazon Cognito can notify your users of risky sign-in attempts. Amazon Cognito can also prompt users to select links to indicate if the sign-in was valid or not valid. Amazon Cognito uses this feedback to improve the risk detection accuracy for your user pool.

In the Automatic risk response section choose Notify Users for low, medium, or high-risk cases.

Notify users

Amazon Cognito sends email notifications to your users regardless of whether they have verified their email address.

You can customize notification email messages, and provide both plaintext and HTML versions of these messages. To customize your email notifications, open Email templates from Adaptive authentication messages in your advanced security configuration. To learn more about email templates, see Message templates.