Using adaptive authentication - Amazon Cognito

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 many factors, including whether it detects a new device, user location, or IP address. Adaptive Authentication adds MFA based on risk level for users who don't have an MFA type enabled at the user level. When an MFA type is enabled at the user level, those users will always receive the second factor challenge during authentication regardless of how you configured adaptive authentication.

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 the Advanced security page in 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.

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 AWS 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 app 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 (AWS 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.

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 Users and groups 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 AWS Command Line Interface (AWS 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.

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 AWS CLI command admin-update-auth-event-feedback.

Sending notification messages

With advanced security protections, Amazon Cognito can notify your users of 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 How do you want to use adaptive authentication for sign-in attempts rated as low, medium and high risk? section choose Notify Users for the low, medium, and high-risk cases.


            Notify users

You can customize notification email messages, and provide both plaintext and HTML versions of these messages. Choose Customize from Adaptive authentication notification messages to customize your email notifications. To learn more about email templates, see Message templates.