Amazon Cognito logging in AWS CloudTrail
Amazon Cognito is integrated with AWS CloudTrail, a service that provides a record of actions taken by a user, role, or an AWS service in Amazon Cognito. CloudTrail captures a subset of API calls for Amazon Cognito as events, including calls from the Amazon Cognito console and from code calls to the Amazon Cognito API operations. If you create a trail, you can choose to deliver CloudTrail events to an Amazon S3 bucket, including events for Amazon Cognito. If you don't configure a trail, you can still view the most recent events in the CloudTrail console in Event history. Using the information collected by CloudTrail, you can determine the request that was made to Amazon Cognito, the IP address from which the request was made, who made the request, when it was made, and additional details.
To learn more about CloudTrail, including how to configure and activate it, see the AWS CloudTrail User Guide.
You can also create Amazon CloudWatch alarms for specific CloudTrail events. For example, you can set up CloudWatch to trigger an alarm if an identity pool configuration is changed. For more information, see Creating CloudWatch alarms for CloudTrail events: Examples.
Topics
Information that Amazon Cognito sends to CloudTrail
CloudTrail is turned on when you create your AWS account. When supported event activity occurs in Amazon Cognito, that activity is recorded in a CloudTrail event along with other AWS service events in Event history. You can view, search, and download recent events in your AWS account. For more information, see Viewing events with CloudTrail event history.
For an ongoing record of events in your AWS account, including events for Amazon Cognito, create a trail. A CloudTrail trail delivers log files to an Amazon S3 bucket. By default, when you create a trail in the console, the trail applies to all Regions. The trail logs events from all Regions in the AWS partition and delivers the log files to the Amazon S3 bucket that you specify. Additionally, you can configure other AWS services to further analyze and act upon the event data collected in CloudTrail logs. For more information, see:
Every event or log entry contains information about who generated the request. The identity information helps you determine the following:
-
Whether the request was made with root or IAM user credentials.
-
Whether the request was made with temporary security credentials for a role or federated user.
-
Whether the request was made by another AWS service.
For more information, see the CloudTrail userIdentity element.
Confidential data in AWS CloudTrail
Because user pools and identity pools process user data, Amazon Cognito obscures some private
fields in your CloudTrail events with the value HIDDEN_FOR_SECURITY_REASONS. For
examples of fields that Amazon Cognito doesn't populate to events, see Example Amazon Cognito events. Amazon Cognito only obscures some fields that
commonly contain user information, like passwords and tokens. Amazon Cognito doesn't perform any
automatic detection or masking of personally-identifying information that you populate to
non-private fields in your API requests.
User pool events
Amazon Cognito supports logging for all of the actions listed on the User pool actions page as events in CloudTrail log files. Amazon Cognito logs user pool events to CloudTrail as management events.
The eventType field in a Amazon Cognito user pools CloudTrail entry tells you whether your app
made the request to the Amazon Cognito user pools API
or to an endpoint that serves
resources for OpenID Connect, SAML 2.0, or managed login pages. API requests have
an eventType of AwsApiCall and endpoint requests have an
eventType of AwsServiceEvent.
Amazon Cognito logs the following requests to your managed login services as events in CloudTrail.
Note
Amazon Cognito records UserSub but not UserName in CloudTrail logs
for requests that are specific to a user. You can find a user for a given
UserSub by calling the ListUsers API, and using a filter for
sub.
Identity pools events
Data events
Amazon Cognito logs the following Amazon Cognito Identity events to CloudTrail as data events. Data events are high-volume data-plane API operations that CloudTrail doesn’t log by default. Additional charges apply for data events.
To generate CloudTrail logs for these API operations, you must activate data events in your trail and choose event selectors for Cognito identity pools. For more information, see Logging data events for trails in the AWS CloudTrail User Guide.
You can also add identity pools event selectors to your trail with the following CLI command.
aws cloudtrail put-event-selectors --trail-name<trail name>--advanced-event-selectors \ "{\ \"Name\": \"Cognito Selector\",\ \"FieldSelectors\": [\ {\ \"Field\": \"eventCategory\",\ \"Equals\": [\ \"Data\"\ ]\ },\ {\ \"Field\": \"resources.type\",\ \"Equals\": [\ \"AWS::Cognito::IdentityPool\"\ ]\ }\ ]\ }"
Management events
Amazon Cognito logs the remainder of Amazon Cognito identity pools API operations as management events. CloudTrail logs management event API operations by default.
For a list of the Amazon Cognito identity pools API operations that Amazon Cognito logs to CloudTrail, see the Amazon Cognito identity pools API Reference.
Amazon Cognito Sync
Amazon Cognito logs all Amazon Cognito Sync API operations as management events. For a list of the Amazon Cognito Sync API operations that Amazon Cognito logs to CloudTrail, see the Amazon Cognito Sync API Reference.
Analyzing Amazon Cognito CloudTrail events with Amazon CloudWatch Logs Insights
You can search and analyze your Amazon Cognito CloudTrail events with Amazon CloudWatch Logs Insights. When you configure your trail to send events to CloudWatch Logs, CloudTrail sends only the events that match your trail settings.
To query or research your Amazon Cognito CloudTrail events, in the CloudTrail console, make sure that you select the Management events option in your trail settings so that you can monitor the management operations performed on your AWS resources. You can optionally select the Insights events option in your trail settings when you want to identify errors, unusual activity, or unusual user behavior in your account.
Sample Amazon Cognito queries
You can use the following queries in the Amazon CloudWatch console.
General queries
Find the 25 most recently added log events.
fields @timestamp, @message | sort @timestamp desc | limit 25 | filter eventSource = "cognito-idp.amazonaws.com"
Get a list of the 25 most recently added log events that include exceptions.
fields @timestamp, @message | sort @timestamp desc | limit 25 | filter eventSource = "cognito-idp.amazonaws.com" and @message like /Exception/
Exception and Error Queries
Find the 25 most recently added log events with error code
NotAuthorizedException along with Amazon Cognito user pool
sub.
fields @timestamp, additionalEventData.sub as user | sort @timestamp desc | limit 25 | filter eventSource = "cognito-idp.amazonaws.com" and errorCode= "NotAuthorizedException"
Find the number of records with sourceIPAddress and corresponding
eventName.
filter eventSource = "cognito-idp.amazonaws.com" | stats count(*) by sourceIPAddress, eventName
Find the top 25 IP addresses that triggered a NotAuthorizedException
error.
filter eventSource = "cognito-idp.amazonaws.com" and errorCode= "NotAuthorizedException" | stats count(*) as count by sourceIPAddress, eventName | sort count desc | limit 25
Find the top 25 IP addresses that called the ForgotPassword API.
filter eventSource = "cognito-idp.amazonaws.com" and eventName = 'ForgotPassword' | stats count(*) as count by sourceIPAddress | sort count desc | limit 25
