Automatically validate and deploy IAM policies and roles in an AWS account by using CodePipeline, IAM Access Analyzer, and AWS CloudFormation macros
Created by Helton Ribeiro (AWS) and Guilherme Simoes (AWS)
Summary
Notice: AWS CodeCommit is no longer available to new customers. Existing customers of AWS CodeCommit can continue to use the service as normal. Learn more
This pattern describes the steps and provides code to create a deployment pipeline that allows your development teams to create AWS Identity and Access Management (IAM) policies and roles in your Amazon Web Services (AWS) accounts. This approach helps your organization reduce overhead for your operational teams and speed up the deployment process. It also helps your developers to create IAM roles and policies that are compatible with your existing governance and security controls.
This pattern’s approach uses AWS Identity and Access Management Access Analyzer to validate the IAM policies that you want to attach to IAM roles and uses AWS CloudFormation to deploy the IAM roles. However, instead of directly editing the AWS CloudFormation template file, your development team creates JSON-formatted IAM policies and roles. An AWS CloudFormation macro transforms these JSON-formatted policy files into AWS CloudFormation IAM resource types before beginning the deployment.
The deployment pipeline (RolesPipeline
) has source, validation, and deployment stages. During the source stage, your development team pushes the JSON files that contain the definition of the IAM roles and policies to an AWS CodeCommit repository. AWS CodeBuild then runs a script to validate those files and copies them to an Amazon Simple Storage Service (Amazon S3) bucket. Because your development teams don’t have direct access to the AWS CloudFormation template file stored in a separate S3 bucket, they must follow the JSON file creation and validation process.
Finally, during the deployment phase, AWS CodeDeploy uses an AWS CloudFormation stack to update or delete the IAM policies and roles in an account.
Important
This pattern’s workflow is a proof of concept (POC) and we recommend that you only use it in a test environment. If you want to use this pattern’s approach in a production environment, see Security best practices in IAM in the IAM documentation and make the required changes to your IAM roles and AWS services.
Prerequisites and limitations
Prerequisites
An active AWS account.
A new or existing S3 bucket for the
RolesPipeline
pipeline. Make sure that the access credentials you’re using have permissions to upload objects to this bucket.AWS Command Line Interface (AWS CLI), installed and configured. For more information about this, see Installing, updating, and uninstalling the AWS CLI in the AWS CLI documentation.
AWS Serverless Application Model (AWS SAM) CLI, installed and configured. For more information about this, see Installing the AWS SAM CLI in the AWS SAM documentation.
Python 3, installed on your local machine. For more information about this, see the Python documentation
. A Git client, installed and configured.
The GitHub
IAM roles pipeline
repository, cloned to your local machine.Existing JSON-formatted IAM policies and roles. For more information about this, see the ReadMe
file in the Github IAM roles pipeline
repository.Your developer team must not have permissions to edit this solution’s AWS CodePipeline, CodeBuild, and CodeDeploy resources.
Limitations
This pattern’s workflow is a proof of concept (POC) and we recommend that you only use it in a test environment. If you want to use this pattern’s approach in a production environment, see Security best practices in IAM in the IAM documentation and make the required changes to your IAM roles and AWS services.
Architecture
The following diagram shows you how to automatically validate and deploy IAM roles and policies to an account by using CodePipeline, IAM Access Analyzer, and AWS CloudFormation macros.

The diagram shows the following workflow:
A developer writes JSON files that contain the definitions for the IAM policies and roles. The developer pushes the code to a CodeCommit repository and CodePipeline then initiates the
RolesPipeline
pipeline.CodeBuild validates the JSON files by using IAM Access Analyzer. If there are any security or error-related findings, the deployment process is stopped.
If there are no security or error-related findings, the JSON files are sent to the
RolesBucket
S3 bucket.An AWS CloudFormation macro implemented as an AWS Lambda function then reads the JSON files from the
RolesBucket
bucket and transforms them into AWS CloudFormation IAM resources types.A predefined AWS CloudFormation stack installs, updates, or deletes the IAM policies and roles in the account.
Automation and scale
AWS CloudFormation templates that automatically deploy this pattern are provided in the GitHub IAM roles pipeline
Tools
AWS Command Line Interface (AWS CLI) is an open-source tool that helps you interact with AWS services through commands in your command-line shell.
AWS Identity and Access Management (IAM) helps you securely manage access to your AWS resources by controlling who is authenticated and authorized to use them.
IAM Access Analyzer helps you identify the resources in your organization and accounts, such as S3 buckets or IAM roles, that are shared with an external entity. This helps you to identify unintended access to your resources and data.
AWS Serverless Application Model (AWS SAM) is an open-source framework that helps you build serverless applications in the AWS Cloud.
Code
The source code and templates for this pattern are available in the GitHub IAM roles pipeline
Epics
Task | Description | Skills required |
---|---|---|
Clone the sample repository. | Clone the GitHub IAM roles pipeline | App developer, General AWS |
Task | Description | Skills required |
---|---|---|
Deploy the pipeline. |
| App developer, General AWS |
Clone the pipeline’s repository. |
| App developer, General AWS |
Task | Description | Skills required |
---|---|---|
Test the RolesPipeline pipeline with valid IAM policies and roles. |
| App developer, General AWS |
Test the RolesPipeline pipeline with invalid IAM policies and roles. |
| App developer, General AWS |
Task | Description | Skills required |
---|---|---|
Prepare for cleanup. | Empty the S3 buckets and then run the | App developer, General AWS |
Delete the RolesStack stack. |
| App developer, General AWS |
Delete the RolesPipeline stack. | To delete the | App developer, General AWS |
Related resources
IAM Access Analyzer - Policy validation
(AWS News Blog) Using AWS CloudFormation macros to perform custom processing on templates (AWS CloudFormation documentation)
Building Lambda functions with Python (AWS Lambda documentation)