Skip to content

Choose Your Own SAML Adventure: A Self-Directed Journey to AWS Identity Federation Mastery

Traceability of federated user actions in AWS CloudTrail

AWS CloudTrail is a web service that records AWS API calls for your account and delivers log files to you. The recorded information includes the identity of the API caller, the time of the API call, the source IP address of the API caller, the request parameters, and the response elements returned by the AWS service.

With CloudTrail, you can get a history of AWS API calls for your account, including API calls made via the AWS Management Console, AWS SDKs, command line tools, and higher-level AWS services (such as AWS CloudFormation). The AWS API call history produced by CloudTrail enables security analysis, resource change tracking, and compliance auditing.

In this exercise, we will review various aspects of CloudTrail usage for actions taken by SAML federated users, including:

  • How the uniqueness of RoleSessionName is critical to traceability.
  • The key differences between the userIdentity stanza of an event related to federated users vs. non-federated users.
  • How to leverage recently launched CloudTrail features to more easily find events related to federated users.

This exercise is applicable to both variants (Open Source and Microsoft) of the workshop. Just be sure to select the appropriate link at the end of the exercise to properly continue your SAML adventure.


The following list identifies the prerequisites for this exercise. If you have not completed these tasks, please take time to do so now.

  • Successful completion of all steps from either the Open Source or Microsoft version of the first-hour exercise. If you are having trouble with the first-hour exercise, please seek help from one of the AWS workshop facilitators.
  • An active CloudTrail trail logging events in the ap-northeast-1 region of the AWS account you used for the initial workshop exercise. Note that a trail that is configured to log events in all regions (default setting) satisfies this requirement. For instructions on configuring CloudTrail, please see Getting Started within the AWS Documentation.

Create events using federated user

To get started, we'll first start by generating a few interesting events using one of our federated users by using both the AWS Management Console and the AWS CLI.

Create events using the AWS Management Console

In order to generate events using the AWS Management Console, we need to login using our federated identity. Open a new browser window and enter the IdP initiated login URL for your Identity Provider (IdP).

Open Source:

Log in using alice's credentials and select the FederationWorkshop-ReadOnly role.

Note: Recall that alice's password has been set to a random value exposed as an output variable in the 1st hour CloudFormation template.

AWS SAML role chooser page

Based on the IAM policies that we applied to the FederationWorkshop-ReadOnly in our earlier exercises, this role does not have any permissions to make mutating calls (e.g. ec2:CreateVolume, s3:DeleteBucket, etc.). As such, the actions that will be attempted by alice below are expected to fail. Regardless, the denied events in CloudTrail still demonstrate the necessary aspects of CloudTrail for federated users.

Now, navigate to the EC2 service in the Tokyo region and find the instance you created in the 1st hour exercise. Select this instance and choose Launch More Like This from the Action drop-down menu.

Launch More Like This

On the confirmation screen, choose Launch.

Launch Confirmation

Acknowledge your possession of the appropriate key pair and choose Launch Instances.

Launch Confirmation

Because alice does not have the necessary permissions to perform ec2:RunInstance, you will receive a Launch Failed notice. Simply click Cancel to abort the launch process, CloudTrail records both successful and unsuccessful API actions.

Create events using the AWS CLI

Now let's create some additional events using the AWS CLI with our federated user. Start by using the script you implemented during the first-hour exercise to retrieve a new STS token for alice. When prompted, choose the FederationWorkshop-ReadOnly role.

alice@Ubuntu64:/tmp$ ./
Username: alice
Password: ****************

Please choose the role you would like to assume:
[ 0 ]:  arn:aws:iam::012345678987:role/FederationWorkshop-ReadOnly
[ 1 ]:  arn:aws:iam::012345678987:role/FederationWorkshop-PowerUser
Selection:  0

Your new access key pair has been stored in the AWS configuration file /home/alice/.aws/credentials under the saml profile.
Note that it will expire at 2016-10-16T17:16:20Z.
After this time, you may safely rerun this script to refresh your access key pair.
To use this credential, call the AWS CLI with the --profile option (e.g., aws --profile saml ec2 describe-instances).

Simple API example listing all S3 buckets:
[<Bucket: mybucket1>, <Bucket: mybucket2>, <Bucket: mybucket3>, <Bucket: mybucket4>, <Bucket: mybucket5>]

Next, let's execute the following ec2:DescribeVolumes command using AWS CLI and the saml profile. This action is allowed by the IAM policy attached to the FederationWorkshop-ReadOnly role, and allows us to see that everything is working properly for our federated user. In order to make the output more concise, a CLI filter has been added that limits the output to only show the VolumeId of each Volume.

aws --region ap-northeast-1 --profile saml ec2 describe-volumes --query 'Volumes[*].VolumeId'

You will see at least one EBS volume (attached to our IdP) in the output.

CLI Success

Now, let's try to execute a command using the same saml profile that's not allowed by the IAM policy attached to the FederationWorkshop-ReadOnly role.

aws --region ap-northeast-1 --profile saml ec2 create-volume --availability-zone ap-northeast-1a --size 1

Since alice does not have the necessary permissions to perform ec2:CreateVolume you will receive a UnauthorizedOperation notice. As noted above, AWS CloudTrail records both successful and unsuccessful API actions.

CLI Failure

Pause for the delivery AWS CloudTrail events

As documented in the AWS CloudTrail FAQ, CloudTrail typically delivers an event within 15 minutes of the API call. As such, we suggest that you make note of the current time, and begin working on one of the additional advanced uses cases. Once you have completed that exercise, return here to continue.

Select the appropriate link according to your technology stack to return to the index of advanced use cases.

Review AWS CloudTrail events

Once the appropriate time has elapsed, let's continue by inspecting some of the AWS CloudTrail events that were generated based on our actions earlier in the exercise.

View events using the AWS Management Console

Next, we'll inspect CloudTrail using the AWS Management Console. Open a new browser window and enter the IdP initiated login URL for your IdP.

Open Source:

Log in using alice's credentials and select the FederationWorkshop-ReadOnly role.

AWS SAML role chooser page

Make sure that you are in the Tokyo region and navigate to CloudTrail.

AWS Management Console

Depending on the level of ongoing activity that you have in the Tokyo region in your account, you may or may not have event activity beyond what's been generated in this exercise. Regardless, let's make use of a feature that was released in March 2016 to quickly find the events associated with alice. To do so, use the Select attribute filter drop down, and choose User name. Then, type alice as the lookup value.

AWS CloudTrail Federated Search

Next, identify one of the events you generated earlier by inspecting the Event name, and expand it. Then, click on View event to see the entire CloudTrail event.

AWS CloudTrail Event Details

With the full event open, find the userIdentity stanza as shown below. If you study this portion of the event, you will notice several key attributes:

  • The userIdentity type is AssumedRole.
  • The principalId is in the form of RoleId:RoleSessionName.
    • The RoleId is the unique identifier for the FederationWorkshop-ReadOnly IAM role. See the note below for instructions on how to find the Role Id.
    • The RoleSessionName is the value provided to AWS by your SAML IdP. In this workshop, we configured RoleSessionName as the uid of the user in the back end directory.
  • The arn is the Amazon Resource Name of the AWS Security Token Service (STS) token that AWS issued alice in exchange for the valid SAML assertion provided by the IdP.
  • The userName only provides the friendly name of the FederationWorkshop-ReadOnly role and thus is not the appropriate attribute to provide traceability between the event and the federated user (alice).

AWS CloudTrail Event Details

Let's quickly compare this event with the userIdentity stanza taken from an event generated using a nonfederated IAM user.

"userIdentity": {
           "type": "IAMUser",
           "principalId": "EX_PRINCIPAL_ID",
           "arn": "arn:aws:iam::123456789012:user/Alice",
           "accessKeyId": "EXAMPLE_KEY_ID",
           "accountId": "123456789012",
           "userName": "Alice"

Note that the type of userIdentity is different, and the attributes appear in a different structure and contain different information. As such, it is imperative to evaluate the userIdentity type when parsing CloudTrail events. This will be elaborated upon below.

Determine RoleId for an AWS IAM role

To determine the RoleId for an AWS IAM role, use the following command, substituting the RoleName appropriately.

aws --profile saml iam list-roles --query 'Roles[?RoleName==`FederationWorkshop-ReadOnly`]'

Lookup RoleId

Key take-aways

In summary, there are two key take-aways from this use case:

  • The type and structure of the userIdentity portion of the CloudTrail event is different for SAML federated users. In particular, when parsing raw events, you must evaluate the userIdentity type and then parse the second half of the principalId (colon delimited). This will provide traceability from the event back to the federated user.
  • The proper configuration of the RoleSessionName within the SAML assertion to a unique & identifiable attribute (such as uid or email) is critical to ensuring proper traceability of CloudTrail events for federated users. The RoleSessionName is defined within the IdP configuration an merely consumed by AWS. Do not ever set RoleSessionName to a generic value.

Exercise complete

Congratulations! You've successfully completed the traceability of federated user actions in CloudTrail advanced use case.

With this use case complete, you are now ready to continue your journey through more of the advanced use cases. To continue, return to the index of advanced use cases.