Integration & Automation

Manage permission sets and account assignments in AWS IAM Identity Center with a CI/CD pipeline

Have you created permission sets and assigned them to AWS Identity and Access Management (IAM) groups in AWS Organizations? Have you used existing corporate identities with AWS IAM Identity Center (successor to AWS Single Sign-On) to grant Active Directory groups access to AWS accounts and applications? If so, you know that doing these things manually can be time-consuming and error-prone.

You can save time and minimize errors by managing permission sets automatically. To do this, you can use AWS developer tools to build a continuous integration and continuous deployment (CI/CD) pipeline, as we show you in this post.

Other benefits of this approach:

  • You prevent people from tampering with your deployed permission sets.
  • You can more easily extend a permission set or group mapping to a new AWS account.
  • You can audit changes to your permission sets through version control.
About this blog post
Time to read ~25 min.
Time to complete ~45 min.
Cost to complete ~$1
Learning level Advanced (300)
AWS services AWS CloudFormation
AWS CodeBuild
AWS CodeCommit
AWS CodePipeline
Amazon EventBridge
AWS IAM Identity Center
AWS Lambda
AWS Organizations
Amazon Simple Notification Service (Amazon SNS)

Solution overview

Figure 1 shows the architecture that you deploy in our walkthrough.

Architecture diagram for the IAM Identity Center CI/CD pipeline

Figure 1. Architecture diagram for the IAM Identity Center CI/CD pipeline

The following points summarize the high-level workflow after the solution shown in Figure 1 is deployed.

  1. You (the cloud administrator) provision AWS CodePipeline by deploying the file codepipeline-stack.template using AWS CloudFormation, updating the stack parameters with your own values.
  2. You push the updated code to AWS CodeCommit, which initiates the AWS CodePipeline run.
  3. CodePipeline creates a CloudFormation stack to provision an Amazon Simple Storage Service (Amazon S3) bucket. It then synchronizes the Lambda code archives—mapping-definition files—from CodeCommit to the S3 bucket.
  4. CodePipeline creates a CloudFormation stack of Lambda functions.
  5. You approve the review action to invoke the Lambda functions.
  6. The first Lambda function (auto-permissionsets) uses the mapping-definition files downloaded from the S3 bucket to create an IAM Identity Center permission set. It then invokes the second Lambda function (auto-assignment), which assigns the permission set to an IAM group in an AWS Organizations account.
  7. (Optional) When an IAM Identity Center API action is made by an IAM user, group, or role that’s not on the allow list, Amazon EventBridge rules invoke the third Lambda function (auto-notification), which sends out a notification email through Amazon Simple Notification Service (Amazon SNS).

Prerequisites

Walkthrough

In this walkthrough, you source-control example IAM Identity Center permission sets and a group-to-account mapping for deploying those permissions. The CodeCommit repository contains permission-set definitions, JSON data files for mapping those sets for group-to-account combinations, and permission-set-to-group mappings that go to all accounts. We recommend that you manage the IAM Identity Center identity on the group level as a best practice, as in this walkthrough; every workforce user should be part of a group.­­­

Main steps:

Step 1: Clone the sample GitHub repository
Step 2: Create IAM groups
Step 3: Create an AWS CodeCommit repository
Step 4: Create a CodePipeline stack
Step 5: Modify parameters and mapping files
Step 6: Initiate the AWS CodePipeline run
Step 7: Validate the new resources

Step 1: Clone the sample GitHub repository

Clone the sample GitHub repository to your local system. This repository contains example data files that you can use to deploy permission sets. You can modify the example data with your own account IDs and resource names. Although you could fork the GitHub repository and link it directly to the CI/CD pipeline, we show you how to use the AWS CodeCommit repository.

Step 2: Create IAM groups

  1. Enable IAM Identity Center. For details, see IAM Identity Center prerequisites.
  2. Create your own testing IAM groups in an AWS Organizations management account.
    • If you use IAM Identity Center as your identity source, use either the AWS Management Console or AWS Command Line Interface (AWS CLI). This example, as shown in Figure 2, shows one group called admin_group.
    • If you use Active Directory or an external identity provider (IdP) such as Okta or Azure Active Directory, users and groups should be automatically synchronized from the source to IAM Identity Center.
Sample IAM group

Figure 2. Example IAM group

Step 3: Create an AWS CodeCommit repository

  1. Create a CodeCommit repository in your AWS account, as shown in Figure 3. For details, refer to Create a repository.
Creating a CodeCommit repository

Figure 3: Creating a CodeCommit repository

  1. Connect to the new repository. For details, refer to Connect to an AWS CodeCommit repository.
  2. Clone the IAM Identity Center project.
  3. Copy the files from the GitHub IAM Identity Center project to the CodeCommit repository directory.

Step 4: Create a CodePipeline stack

  1. In the AWS CloudFormation console, create a stack using codepipeline-stack.template in the CodeCommit repository, as shown in Figure 4. For details, refer to Creating a stack on the AWS CloudFormation console.
Creating your CodePipeline stack using a CloudFormation template

Figure 4. Creating your CodePipeline stack using a CloudFormation template

  1. Fill in the stack parameters with your own values, as shown in Figure 5. For ICMappingBucketName, the CloudFormation stack creates a new bucket with the name you enter. The same name is used later in your file identity-center-stacks-parameters.json.
Specifying CloudFormation stack details

Figure 5: Specifying CloudFormation stack details

  1. Keep the defaults for all stack options, and choose Next.
  2. On the Review page, select I acknowledge that AWS CloudFormation might create IAM resources with custom names. Then choose Create stack.

After you’ve created the stack, your CodePipeline would fail in the build stage because there’s no file in your remote AWS CodeCommit repository. Don’t worry; in the following steps you’ll modify the local repository before pushing it to AWS CodeCommit.

Step 5: Modify parameters and mapping files

  1. Provide the value for all the required parameters to create the CloudFormation stacks for S3 and other AWS resources for this solution. Some of the parameters have the default value in the templates. Review and update all the nondefault parameters in the file identity-center-stacks-parameters.json.
    1. IdentityStoreId: Identity Store ID can be found on the IAM Identity Center console Settings page.
    2. OrganizationId: AWS Organizations ID, for example, o-awsaabb12. Enter the correct Organizations ID; otherwise, you will lock yourself out from the new IAM Identity Center S3 bucket.
    3. ICMappingBucketName: The same bucket name that you defined in codepipeline-stack.template.
    4. SNSEmailEndpointSubscription: The email address that notifications for the IAM Identity Center permission set will be sent to.
    5. ICAutmationAdminArn: The Amazon Resource Name (ARN) of an existing IAM role or user in your account that will be used as the IAM Identity Center administrator.
    6. ICInstanceARN: You can find this ARN on the IAM Identity Center console Settings page.
    7. ICKMSAdminArn: The ARN of an existing IAM role or user that will have administrator permissions to manage the IAM Identity Center’s AWS Key Management Service (AWS KMS) key.
  2. Modify the IAM Identity Center mapping files in your CodeCommit repository. To do this, create your own permission-set files: global-mapping.json and target-mapping.json. Refer to the example in readme.md.
    1. Clone your CodeCommit repo and create a branch with the same name as your CloudFormation template.
    2. Create your permission set and mapping files in your cloned CodeCommit repo directory.
    3. Add your modified files to the CodeCommit repo using Git commands.

Step 6: Initiate the AWS CodePipeline run

  1. Push your code changes to AWS CodeCommits. For details, refer to Getting started with Git and AWS CodeCommit.
  2. Provide the manual approval to invoke the Lambda functions, as shown in Figure 6.
CodePipeline waiting for manual approval

Figure 6: CodePipeline waiting for manual approval

  1. If the CloudFormation stack fails, delete the failed stack, fix the issue, and rerun the pipeline by pushing a newer version of the code to AWS CodeCommit.

Step 7: Validate the new resources

  1. In the IAM Identity Center console, verify that the management account’s permission sets have been provisioned, as shown in Figure 6.
Provisioned status of permission sets

Figure 6: Provisioned status of permission sets

  1. Verify the account assignments on the management account’s IAM Identity Center console using the List view, as shown in Figure 8.
List of AWS accounts in IAM Identity Center

Figure 7: List of AWS accounts in IAM Identity Center

Troubleshooting

When you use this pipeline, you might encounter issues when you create, update, or delete resources in your account. The following tips can help you troubleshoot some common issues that you might encounter.

  • View pipeline details, including when actions last ran in the pipeline, whether any actions have failed, and other information.
  • For issues creating the CloudFormation stack, view the error message in the stack events, and refer to Troubleshooting CloudFormation.
  • For CodePipeline issues, review the error messages on the CodePipeline console.
  • For IAM issues, refer to Troubleshooting AWS CodePipeline identity and access.
  • Review the default log groups for the automation Lambda functions:
    • /aws/lambda/ic-permissionsets-enabler
    • /aws/lambda/ic-auto-assignment-enabler
    • /aws/lambda/ic-alert-SNSnotification

Cleanup

When you finish your tests or no longer need this solution in your environment, follow these steps to remove the AWS resources so that you don’t continue to incur costs:

  1. Replace all the mapping information with an empty list ([]) in global-mapping.json and target-mapping.json. Then rerun the pipeline to automatically remove all the IAM Identity Center assignments.
  2. Delete all the .json files in the permissions-set folder. Then rerun the pipeline to automatically remove all permission sets.
  3. Delete CloudFormation stack that was created using identity-center -automation.template.
  4. Empty the IAM Identity Center S3 bucket that was created as part of this stack. Then delete the CloudFormation stack that was created using identity-center-s3-bucket.template.
  5. Empty the S3 bucket named ic-pipeline-artifact-bucket-<name> where <name> is the name of the bucket that was created as a part of this stack. Then delete CloudFormation stack that was created using pipeline-stack.template.
  6. Delete the AWS CodeCommit repository that you created in this walkthrough.

These cleanup steps will remove only the resources that were provisioned in this walkthrough. You may need to remove other permission sets or IAM Identity Center assignments if any were created beyond what we’ve described.

Conclusion

In this post, we introduced an automated pipeline that allows you to manage your IAM Identity Center with AWS DevOps services. After implementing this solution, you should be able to source-control your IAM Identity Center permission sets and account assignments using your own code repository on AWS CodeCommit. In this way, you save time by avoiding repetitive manual changes and troubleshooting inconsistent issues that are caused by unexpected operational incidents. You can also audit user access across your organization with confidence.

Do you have feedback about this blog post? Please submit comments below. You can also post questions on the AWS re:Post forum.

About the authors

Wenxin Liu

Wenxin Liu is a cloud infrastructure architect with AWS Professional Services. Wenxin advises AWS enterprise customers on how to accelerate cloud adoption and supports their innovations on the cloud. He’s a pet lover and is passionate about snowboarding and traveling.

Chris Childers

Chris Childers is a cloud infrastructure architect with AWS Professional Services. He helps AWS customers design and automate their cloud infrastructure and supports their adoption of DevOps culture and processes.