Enrich CloudTrail events by adding resource tag keys and IAM global condition keys

You can enrich CloudTrail management events and data events by adding resource tag keys, principal tag keys, and IAM global condition keys when you create or update an event data store. This allows you to categorize, search, and analyze CloudTrail events based on the business context, such as cost allocation and financial management, operations, and data security requirements. You can analyze events by running queries in CloudTrail Lake. You can also choose to federate your event data store and run queries in Amazon Athena. You can add resource tag keys and IAM global condition keys to an event data store using the CloudTrail console, Amazon CLI, and SDKs.

When you add resource tag keys to enriched events, CloudTrail includes the selected tag keys associated with the resources that were involved in the API call.

When you add IAM global condition keys to an event data store, CloudTrail includes information about the selected condition keys that were evaluated during the authorization process, including additional details about the principal, session, and the request itself.

After you add resource tag keys or IAM condition keys, CloudTrail includes a eventContext field in CloudTrail events that provides the selected contextual information for the API action.

There are some exceptions when the event will not include the eventContext field, including the following:

Amazon Web Services services supporting resource tags

All Amazon Web Services services support resource tags. For more information, see Services that support the Amazon Resource Groups Tagging API .

Resource tag updates in CloudTrail for enriched events

When configured to do so, CloudTrail captures information about resource tags and uses them to provide information in enriched events. When working with resource tags, there are certain conditions in which a resource tag might not be accurately reflected at the time of the system request for events. During standard operation, tags applied at resource creation time are always present and will experience minimal or no delays. However, the following services are expected to have delays in resource tag changes appearing in CloudTrail events:

Service outages can also cause delays in updates to resource tag information. In the event of a service outage delay, subsequent CloudTrail events will include an addendum field that includes information about the resource tag change. This additional information will be used as specified to provide enriched CloudTrailevents.

Amazon Web Services services supporting IAM global condition keys

The following Amazon Web Services services support IAM global condition keys for enriched events:

Supported IAM global condition keys for enriched events

The following table lists the supported IAM global condition keys for CloudTrail enriched events, with example values:

Event examples

In the following example, the eventContext field includes IAM global condition key aws:ViaAWSService with a value of false, which indicates the API call was not made by an Amazon Web Services service.

{
    "eventVersion": "1.11",
    "userIdentity": {
        "type": "AssumedRole",
        "principalId": "ASIAIOSFODNN7EXAMPLE",
        "arn": "arn:aws:sts::123456789012:assumed-role/admin",
        "accountId": "123456789012",
        "accessKeyId": "ASIAIOSFODNN7EXAMPLE",
        "sessionContext": {
            "sessionIssuer": {
                "type": "Role",
                "principalId": "ASIAIOSFODNN7EXAMPLE",
                "arn": "arn:aws:iam::123456789012:role/admin",
                "accountId": "123456789012",
                "userName": "admin"
            },
            "attributes": {
                "creationDate": "2025-01-22T22:05:56Z",
                "mfaAuthenticated": "false"
            }
        }
    },
    "eventTime": "2025-01-22T22:06:16Z",
    "eventSource": "cloudtrail.amazonaws.com",
    "eventName": "GetTrailStatus",
    "awsRegion": "us-east-1",
    "sourceIPAddress": "192.168.0.0",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:133.0) Gecko/20100101 Firefox/133.0",
    "requestParameters": {
        "name": "arn:aws:cloudtrail:us-east-1:123456789012:trail/myTrail"
    },
    "responseElements": null,
    "requestID": "d09c4dd2-5698-412b-be7a-example1a23",
    "eventID": "9cb5f426-7806-46e5-9729-exampled135d",
    "readOnly": true,
    "eventType": "AwsApiCall",
    "managementEvent": true,
    "recipientAccountId": "123456789012",
    "eventCategory": "Management",
    "tlsDetails": {
        "tlsVersion": "TLSv1.3",
        "cipherSuite": "TLS_AES_128_GCM_SHA256",
        "clientProvidedHostHeader": "cloudtrail.us-east-1.amazonaws.com"
    },
    "sessionCredentialFromConsole": "true",
    "eventContext": {
        "requestContext": {
            "aws:ViaAWSService": "false"
        },
        "tagContext": {}
    }
}