Amazon Cognito logging in AWS CloudTrail - Amazon Cognito
Information that Amazon Cognito sends to CloudTrailAnalyzing Amazon Cognito CloudTrail events with Amazon CloudWatch Logs Insights

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 pools 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 the hosted UI. API requests have an eventType of AwsApiCall and endpoint requests have an eventType of AwsServiceEvent.

Amazon Cognito logs the following hosted UI requests to your hosted UI as events in CloudTrail.

Hosted UI operations in CloudTrail
Operation Description
Login_GET, CognitoAuthentication A user views or submits credentials to your Login endpoint.
OAuth2_Authorize_GET, Beta_Authorize_GET A user views your Authorize endpoint.
OAuth2Response_GET, OAuth2Response_POST A user submits an IdP token to your /oauth2/idpresponse endpoint.
SAML2Response_POST, Beta_SAML2Response_POST A user submits an IdP SAML assertion to your /saml2/idpresponse endpoint.
Login_OIDC_SAML_POST A user enters a username at your Login endpoint and matches with an IdP identifier.
Token_POST, Beta_Token_POST A user submits an authorization code to your Token endpoint.
Signup_GET, Signup_POST A user submits sign-up information to your /signup endpoint.
Confirm_GET, Confirm_POST A user submits a confirmation code in the hosted UI.
ResendCode_POST A user submits a request to resend a confirmation code in the hosted UI.
ForgotPassword_GET, ForgotPassword_POST A user submits a request to reset their password to your /forgotPassword endpoint.
ConfirmForgotPassword_GET, ConfirmForgotPassword_POST A user submits a code to your /confirmForgotPassword endpoint that confirms their ForgotPassword request.
ResetPassword_GET, ResetPassword_POST A user submits a new password in the hosted UI.
Mfa_GET, Mfa_POST A user submits a multi-factor authentication (MFA) code in the hosted UI.
MfaOption_GET, MfaOption_POST A user chooses their preferred method for MFA in the hosted UI.
MfaRegister_GET, MfaRegister_POST A user submits a multi-factor authentication (MFA) code in the hosted UI when registering the MFA.
Logout A user signs out at your /logout endpoint.
SAML2Logout_POST A user signs out at your /saml2/logout endpoint.
Error_GET A user views an error page in the hosted UI.
UserInfo_GET, UserInfo_POST A user or IdP exchanges information with your userInfo endpoint.
Confirm_With_Link_GET A user submits a confirmation based on a link that Amazon Cognito sent in an email message.
Event_Feedback_GET A user submits feedback to Amazon Cognito about an advanced security features event.
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