Automate IAM credential reports at scale across AWS

Automation is your best friend when it comes to compliance and auditing. Organizations must continually monitor and mitigate security risks to maintain regulatory and compliance requirements that involve AWS Identity and Access Management (IAM) practices.

In this post, we demonstrate how to automate and consolidate IAM credential reports for your AWS accounts using a scalable infrastructure as code (IaC) automation created through AWS CloudFormation. With this process, you can generate and download credential reports that list all of your IAM users and the status of their credentials, including passwords, access keys, and multifactor-authentication devices.

Process overview

The architecture uses AWS Control Tower and consists of multiple AWS Organizations accounts: a management account and at least three member accounts that belong to their respective organizational units. AWS Organizations helps to centrally manage, govern, automate, and scale AWS resources across an organization’s accounts. Figure 1 shows the high-level architecture and AWS resources that are deployed by implementing the steps in this post.

Figure 1. Architecture diagram for automating IAM credentials reports

To assume a role across different AWS accounts that belong to AWS Organizations, the process uses an AWS Lambda function in a management account. The Lambda function generates an IAM user credential report for each account, and it aggregates CSV reports in an S3 bucket deployed in a log-archive account. The S3 bucket in the log archive account is encrypted by an AWS KMS key, which is managed by AWS Key Management Service (AWS KMS) that’s located in a security account. In this blog, we focus on deploying the automation that generates and stores IAM credential reports in Amazon S3.

To analyze your credential reports, ingest it into other services, such as Amazon Athena, Amazon QuickSight, or third-party products from AWS Partners. For more information, see Creating a Dataset Using Amazon S3 Files and Athena SerDe Reference.

Prerequisites

For this walkthrough, you need the following:

• At least four AWS accounts that belong to AWS Organizations. For more information, see Creating and configuring an organization.
• A basic knowledge of Python.
• A basic knowledge of AWS CloudFormation templates.

Walkthrough

The following steps describe how to deploy credential reports:

1. Create a customer managed key in the security account. The key protects data in the S3 bucket using Protecting data using server-side encryption with AWS Key Management Service (SSE-KMS).
2. Create an S3 bucket in the log archive account.
3. Implement the credential report automation consisting of an IAM role, and Lambda function in the management account.
4. Create the IAM roles in the member accounts.

View the GitHub repository.

Step 1: Create a customer managed key in the security account.

1. Navigate to the AWS CloudFormation StackSet console in the management account and AWS Region being used, and create a new stackset using the iam-credential-report-kms-key.yaml template.
2. Enter the StackSet name. In my example, we use iam-cred-report-key. Under Parameters, enter the following values:
   • pIAMCredentialReportKeyAlias: This is the name of the AWS KMS key alias.
   • pManagementAccountId: This is the management account ID.
   • pLoggingAccountId: This is the log archive account ID.
   • pTagKey1: This is the tag key to assign to your resources.
   • pTagValue1: This is the tag value to assign to your resources.
3. Under Permissions, choose Self-service permissions. We use the following settings to deploy our code:
   • IAM role name: AWSControlTowerStackSetRole
   • IAM execution role name: AWSControlTowerExecution
4. On the Set deployment options, choose Deploy stacks in accounts, and provide the security account ID. In the Specify Regions section, choose the AWS Region where you want to deploy the key.
5. On the Review page, validate the parameters and select Submit.
6. On the Stack Instances page, validate the StackSet deployment, and wait for the status to change from OUTDATED to CURRENT.

For more information, see Create a StackSet.

Step 2: Create an S3 bucket in the log archive account.

1. Repeat steps 1–6 from step 1 using the iam-credential-report-s3-bucket.yaml template and deploy the stack to the log archive account.
2. The following are additional parameters required for this step:
   • pIAMCredReportKeyArn: This is the Amazon Resource Name (ARN) of the AWS KMS key. Obtain this from the AWS CloudFormation outputs in step 1.
   • pOrgPrimaryLambdaRoleName: This is the name of the Lambda role name.
   • pIAMCredReportBucketPrefix: This is prefix or name of the S3 bucket.
   • pOrganizationId: This is the AWS Organizations ID. Obtain this from the AWS Organizations console.

Step 3: Implement the credential report automation in the management account.

1. Navigate to the AWS CloudFormation stack console in the management account and repeat steps 2–6 from step 1 using the iam-credential-report-automation.yaml template.
2. The following are additional parameters that are required for this step:
   • pIAMCredReportDeliveryBucketArn: This is the ARN of the S3 bucket. Obtain this from the AWS CloudFormation outputs in step 2.
   • pLogsRetentionInDays: This is number of days you want to retain log events in the Lambda CloudWatch log group.
   • pScheduleExpression: This is the Amazon EventBridge schedule expression to invoke the Lambda function. For example, enter rate(1 day) to invoke the Lambda function daily. This parameter should have a minimum value of four hours using rate(4 hours).
3. On the Review page, validate the parameters and check the box I acknowledge that AWS CloudFormation might create IAM resource with custom names, and choose Submit.

When you implement the credential report automation in this step, IAM first checks whether a report for the AWS account has been generated within the past four hours. If so, the most recent report is downloaded. If the most recent report for the account is older than four hours, or if there are no previous reports for the account, IAM generates a new report.

Step 4: Create IAM roles in the member accounts.

1. Repeat steps 1–6 from step 1 using the iam-credential-report-iam-role.yaml template and deploy the stack to the organizational units where member accounts are located.
2. The following are additional parameters required for this step:
   • pOrgPrimaryLambdaRoleArn: This is the ARN of the Lambda function. Obtain this from the AWS CloudFormation outputs in step 3.

Upon completion, the credential reports are stored in your S3 bucket, located in the log archive account, as shown in figure 2. You can manually invoke the automation by disabling and re-enabling the Amazon EventBridge rule or wait for a scheduled launch.

Figure 2. IAM credential reports

Code overview

It’s important for our customers to understand what the code does in the backend, so we present an overview of the Lambda code in this section.

The process uses an AWS Lambda function to interact with the AWS Organizations API. The function comprises Python code that uses the AWS SDK for Python (Boto3) to acquire a list of all active accounts (that is, not suspended) within the organization. For more information, see the Boto3 documentation.

The Lambda function assumes an IAM role in each account with a permissions boundary limited to GenerateCredentialReport and GetCredentialReport API calls.

PolicyDocument:
 Version: 2012-10-17
 Statement:
 - Effect: Allow
 Action:
 - "iam:GenerateCredentialReport"
 - "iam:GetCredentialReport"

The Lambda code imports the necessary modules to read the environment variables and interact with AWS API endpoints using AWS Security Token Service. The code also handles client errors when the function is invoked and writes the reports to the S3 bucket.

Cleanup

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

1. Navigate to the AWS CloudFormation console in the management account.
2. Delete the stack instances, and then delete the StackSets and stack from the AWS CloudFormation console.

Conclusion

In this post, we walked you through how to automate and consolidate IAM credential reports across your AWS accounts in AWS Organizations. You can use this process to carry out IAM user access reviews, demonstrate your IAM practices are frequently monitored, and mitigate security risks.

Optionally, you can deploy this process using an AWS CodePipeline in Customizations for AWS Control Tower. You can also refactor the code and deploy the S3 bucket and AWS KMS customer managed key to a single AWS account.

If you want to dig deeper into the AWS CloudFormation templates, see the GitHub repository. To provide feedback or ask questions, use this post’s comments section.

About the authors