Automatically validate and deploy IAM policies and roles in an AWS account by using CodePipeline, IAM Access Analyzer, and AWS CloudFormation macros - AWS Prescriptive Guidance
SummaryPrerequisites and limitationsArchitectureToolsEpicsRelated resources

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)

Code repository: IAM roles pipeline

Environment: PoC or pilot

Technologies: Security, identity, compliance; DevOps

AWS services: AWS CloudFormation; AWS CodeBuild; AWS CodeCommit; AWS CodePipeline; AWS Lambda; AWS SAM

Summary

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.

Steps for validating and deploying IAM policies and roles in an AWS account.

The diagram shows the following workflow:

  1. 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.

  2. CodeBuild validates the JSON files by using IAM Access Analyzer. If there are any security or error-related findings, the deployment process is stopped.

  3. If there are no security or error-related findings, the JSON files are sent to the RolesBucket S3 bucket.

  4. 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.

  5. 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 repository.

Tools

Code 

The source code and templates for this pattern are available in the GitHub IAM roles pipeline repository.

Epics

TaskDescriptionSkills required

Clone the sample repository.

Clone the GitHub IAM roles pipeline repository to your local machine.

App developer, General AWS
TaskDescriptionSkills required

Deploy the pipeline.

  1. Navigate to the directory that contains the cloned repository.

  2. Run the make deploy bucket=<bucket_name> command. Important: you must replace <bucket_name> with the bucket name for your existing S3 bucket.

  3. Run the aws codepipeline get-pipeline –name RolesPipeline command to check if your deployment is successful.

App developer, General AWS

Clone the pipeline’s repository.

  1. The RolesPipeline AWS CloudFormation stack creates the roles-pipeline-repo CodeCommit repository.

  2. Sign in to the AWS Management Console, open the AWS CodeCommit console, and then copy the CodeCommit repository’s URL to clone it to your local machine. For more information about this, see Connect to an AWS CodeCommit repository in the AWS CodeCommit documentation.

App developer, General AWS
TaskDescriptionSkills required

Test the RolesPipeline pipeline with valid IAM policies and roles.

  1. Create JSON files for your IAM policies and roles. You can use the samples in the role-example directory from the GitHub IAM roles pipeline repository.

  2. Define your IAM policies and roles with the required configurations. Important: Make sure that you follow the format described in the ReadMe file from the GitHub IAM roles pipeline repository.

  3. Push the modifications into the roles-pipeline-repo CodeCommit repository.

  4. Verify the implementation of the RolesPipeline pipeline.

  5. Make sure that the IAM policies and roles are correctly deployed in the account.

  6. Validate if there is a permissions boundary associated to the IAM policies or roles. For more information about this, see Permissions boundaries for IAM entities in the IAM documentation.

App developer, General AWS

Test the RolesPipeline pipeline with invalid IAM policies and roles.

  1. Modify the roles-pipeline-repo CodeCommit repository and include invalid IAM roles or policies. For example, you can use an action that doesn’t exist or an invalid IAM policy version.

  2. Verify the pipeline implementation. IAM Access Analyzer stops the pipeline during the validation stage if it detects invalid IAM policies or roles.

App developer, General AWS
TaskDescriptionSkills required

Prepare for cleanup.

Empty the S3 buckets and then run the destroy command.

App developer, General AWS

Delete the RolesStack stack.

  1. The RolesPipeline pipeline creates a RolesStack AWS CloudFormation stack that deploys the IAM policies and roles. You must delete this stack before deleting the RolesPipeline pipeline.

  2. Sign in to the AWS Management Console, open the AWS CloudFormation console, and then choose the RolesStack stack and choose Delete.

App developer, General AWS

Delete the RolesPipeline stack.

To delete the RolesPipeline AWS CloudFormation stack, follow the instructions from the ReadMe file in the Github IAM roles pipeline repository.

App developer, General AWS

Related resources