Automate IAM credential reports for large AWS Organizations

Manage AWS Identity and Access Management (IAM) credentials to properly secure AWS Organizations. With a large number of accounts in your organization, it is less practical to generate IAM credential reports within each account.

This post provides a solution to automate IAM credential reports in AWS Organizations with many accounts. The results are consolidated into a centralized Amazon Simple Storage Service (Amazon S3) bucket to simplify auditing and review. These credential reports list all AWS IAM users in your accounts and the status of their credentials, including passwords, access keys, and MFA devices.

The primary benefits of this solution are the ability to run IAM credential reports in parallel across your accounts. We’ll also use AWS Step Functions to wait for reports to process, which will reduce AWS Lambda costs.

Overview

This solution uses an Amazon EventBridge rule to invoke the Step Functions state machine. The state machine then invokes a Lambda function to retrieve the account IDs from AWS Organizations. Finally, the function passes them to a second Lambda function that generates the IAM credential report. The process that creates the report must assume an IAM role within each account. To facilitate the role creation, an AWS CloudFormation stack set deploys the role for the Lambda function into all the accounts linked to the management account.

The Lambda function that generates the reports invokes report generation and checks for report completion status. If report generation is still in progress, the Lambda function exits and the state machine waits for 1 minute. This cycle continues until the report completes, or it reaches 45 total wait cycles and exits with an error. When the report generates, the output file is copied to the defined Amazon S3 bucket and secured with the default encryption setting of the bucket. If the error condition invokes (45 wait cycles/45 minutes), Amazon Simple Notification Service (SNS) sends a message to the email address provided during deployment.

Figure 1 shows the architecture to demonstrate automating IAM credential reports.

Figure 1. Automating IAM credential reports architecture diagram

Figure 2 shows a detailed workflow of a state machine.

Figure 2. Detailed state machine workflow

Prerequisites

For this walkthrough, you need the following:

• An AWS account
• AWS Organizations with multiple accounts
• The AWS Serverless Application Model (AWS SAM) CLI
• (Optional) AWS Command Line Interface (AWS CLI)

Walkthrough

AWS SAM is an open framework that provides syntax for deploying serverless applications. During the deployment, the AWS SAM CLI packages the code and translates the YAML template into a CloudFormation template. AWS SAM moves the code and templates to Amazon S3 for resource deployment.

In this blog post, we focus on one solution. However, the GitHub repository provides an alternative deployment option to store reports in a separate logging/security account.

Deploy the solution using AWS SAM

This deployment option uses the core AWS SAM template. A single command starts deployment in Step 4 later. The S3 bucket that contains the IAM credential reports is created in the management account.

Step 1: Get root ID

Find the value of the root ID in the management account in the AWS Management Console, or use the following command (if you have the AWS CLI installed):

aws organizations list-roots

The root ID is in the format r-XXXX. You need this value in Step 4 later, so write it down.

Step 2: Get AWS Organizations ID

Find the value of the AWS Organizations ID in the management account in the AWS Management Console, or use the following command (if you have the AWS CLI installed):

aws organizations describe-organization

The Organizations ID is in the format o-xxxxxxxxxxxx. You need this value in Step 4 later, so write it down.

Step 3: Clone the solution repository

Use the following command to clone the solution repository from GitHub.

git clone https://github.com/aws-samples/automating-iam-credential-reports-for-large-aws-organizations.git

Step 4: Deploy the solution

To create all resources necessary for the solution, use the AWS SAM CLI to deploy the core template. If you prefer, use an existing S3 bucket in the management account.

Navigate to the root of the solution, and run the following commands while authenticated as the management account:

cd src/

sam deploy --stack-name iam-cred-report-core --template iam-cred-report-core-template.yml --config-file iam-cred-report-core-config.toml --guided --capabilities CAPABILITY_NAMED_IAM

The previous command transforms the AWS SAM template into a CloudFormation stack template, and then creates the stack. The configuration file referenced provides initial values and storage for your responses to the guided questions for later jobs.

Provide the following details:

• Stack Name [iam-cred-report-core]: Provide a custom name or press Enter to use the default.
• AWS Region [us-east-1]: Provide the Region in which to deploy this solution.
• Parameters:
  • pS3BucketStatus [New]: Keep blank to accept the default setting to create a new Amazon S3 bucket, or enter Existing to use an existing bucket.
  • pS3BucketTargetName []: Provide the name for the new or existing S3 bucket.
  • pKMSKeyStatus [None]: Enter New to create a new KMS key.
  • pKMSKeyArn [None]: Keep blank to accept the default setting of None.
  • pSNSSubEmail []: Provide an email address for the SNS topic to send account-level errors, or keep blank to opt out.
  • pIAMCredentialGenRoleName [iam-credential-report-generation-role]: Provide a custom name for the role or keep blank to use the default.
  • pOrganizationRootId []: Enter the Organizations root ID (r-xxxx).
  • pOrganizationId []: Enter the Organizations ID (o-xxxxxxxxxxxx).
  • pLogsRetentionInDays [90]: Enter the number of days to retain the Amazon CloudWatch log groups logs, or keep the default setting of 90 days. Allowed values are: 1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, 1827, 3653.
  • pEventBridgeTriggerHour [08]: Enter the two-digit hour (00-23) in UTC time used to trigger the EventBridge rule each day, or keep the default to trigger at 08:00:00 UTC.
  • pTagKey1 [tagkey]: Enter a tag key name to add to the resources.
  • pTagValue1 [tagvalue]: Enter a tag value to associate with the tag key.
• Confirm changes before deploy [Y/n]: Verify your inputs, and enter Y to proceed.
• Allow AWS SAM CLI IAM role creation [Y/n]: Enter Y to allow for role creation.
• Disable rollback [Y/n]: Enter Y to disable rollback.
• Save arguments to configuration file [Y/n]: Enter Y to save your configuration settings, if desired.

CloudFormation Outputs from deployed stack

The Outputs section of the AWS SAM CLI process includes the Lambda function execution role ARN and the S3 bucket name. For this deployment option, the Output is only for reference.

Figure 3 shows the Outputs details of the AWS SAM CLI process.

Figure 3. Outputs section of the AWS SAM CLI

Accept the Amazon SNS email confirmation

If you provided an email address, you’ll get an email to confirm for the SNS subscription to send notifications about nonprocess fatal errors for a single account.

Figure 4 shows the email confirmation of the SNS subscription.

Figure 4. AWS Notification Subscription Confirmation email

Invoking the state machine

The EventBridge rule invokes the state machine at the hour specified in the deployment. However, you can invoke the state machine manually from the AWS Management Console. Select the state machine details panel, and choose Start execution. No values are needed for the input JSON.

Figure 5 shows how to manually invoke the state machine.

Figure 5. Manually invoking the state machine.

Accessing the IAM credential reports

The Lambda function stores the IAM credential reports in the S3 bucket with a prefix that represents the date. Invoking the process multiple times in a single day overwrites the prior contents. Each IAM credential report includes the account number in the name.

Figure 6 shows the IAM credential reports stored in the S3 bucket.

Figure 6. S3 bucket where IAM credential reports are stored

Cleanup

To avoid incurring future changes, complete the following steps to delete the resources created by this solution:

1. If you created a new S3 bucket, navigate to the Amazon S3 console. Select the bucket where the IAM credential reports are stored, and empty the bucket to remove all the contents.
2. Navigate to the CloudFormation console. Select the stack named iam-cred-report-core, or the custom name you provided during deployment, and delete the stack.

Conclusion

In this post, we demonstrated a method of consolidating IAM credential reports for AWS Organizations into an S3 bucket using Step Functions and Lambda. Having an organizational view of security data allows you to take a more holistic approach to managing security and compliance needs. When you automate the collection of that data, it reduces the effort and likelihood of errors and omissions.

About the authors