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

This post was updated on March 10, 2023, to add the options of delegating an administrator for AWS IAM Identity Center or using AWS Control Tower. 

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.
• You can delegate administration of IAM Identity Center to a member account in AWS Organizations.

Solution overview

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

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 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). That Lambda function sends out a notification email through Amazon SNS and invokes the other two Lambda functions to revert manual changes.
8. (Optional) If you have a delegated administrator for Identity Center or if you have AWS Control Tower enabled, the first Lambda function (auto-permissionsets) also makes a list of permission sets that were provisioned in the AWS Organizations management account and tagged with ManagedBy:ControlTower. It then stores those permission-set names and Amazon Resource Names (ARNs) in a DynamoDB table (ic-SkippedPermissionSetsTable).

Prerequisites

• An AWS account with AWS Organizations enabled. If you don’t have an account, sign up at https://aws.amazon.com.
• Basic knowledge of CloudFormation.
• IAM Identity Center prerequisites.
• An identity provider (IAM Identity Center or one of the supported identity providers).
• Git.

Considerations when delegating an administrator or using with Control Tower

If you are deploying this solution in a delegated administrator account (recommended) for IAM Identity Center, create permission sets for use only in the management account. This makes it easier to administer permission sets solely for users who access your management account and helps differentiate them from permission sets managed by your delegated administrator account. Additionally, a delegated administrator account does not have permissions to manage permission sets provisioned in the management account. You must have permission sets provisioned in the management account. These permission sets are used only in that account.

If you want to deploy this solution in an AWS Control Tower–based landing zone, AWS Control Tower creates some preconfigured groups and corresponding permission sets for you and requires them for account provisioning. You can either add users into those AWS Control Tower groups or create your own groups and use those to assign permission sets. Regardless, you can either tag permission sets created by AWS Control Tower with ManagedBy:ControlTower (recommended) before running the pipeline or delete those permission sets in the management account and recreate them using this solution. AWS Control Tower–created permission sets must exist for proper account provisioning.

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. If you chose to administer IAM Identity Center in the AWS Organizations management account, continue to item 3 below. If you have chosen to delegate an AWS Organizations member account as administrator for Identity Center, create a stack using the delegate-admin/IC-Delegate-Admin.yml template in the CodeCommit repository, as shown in Figure 2. For details, refer to Creating a stack on the AWS CloudFormation console. You can alternatively delegate administrator for Identity Center in the IAM Identity Center Console directly. For details, refer to Register a member account.

Figure 2: Creating IAM groups

Additionally, if you have chosen to delegate an AWS Organizations member account as administrator for Identity Center, create permission sets using IAM Identity Center console in the AWS Organizations management account for use only in the management account. Use unique names when creating permission sets for use only in the management account, for example, management-administrator, management-readOnly, and management-ViewOnly. These permission sets will give you access to the management account through the AWS access portal. The delegated administrator does not have permissions to provision permission sets in the management account. Unique names help differentiate these permission sets from those that are managed by your delegated administrator account.

3. Create your own testing IAM groups in an AWS Organizations management account or a delegated administrator account depending on where you choose to manage IAM Identity Center.

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

    Figure 3. Example IAM group

Step 3: Create an AWS CodeCommit repository

1. Create a CodeCommit repository in your AWS Organizations management account or delegated administrator account depending on where you choose to manage IAM Identity Center, as shown in Figure 4. For details, refer to Create a repository.
   

   Figure 4: Creating a CodeCommit repository

2. Connect to the new repository. For details, refer to Connect to an AWS CodeCommit repository.
3. Clone the IAM Identity Center project.
4. 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 in the same account, create a stack using codepipeline-stack.template in the CodeCommit repository, as shown in Figure 5. For details, refer to Creating a stack on the AWS CloudFormation console.
   

   Figure 5. Creating your CodePipeline stack using a CloudFormation template

2. Fill in the stack parameters with your own values, as shown in Figure 6. For ICMappingBucketName, the CloudFormation stack creates a new S3 bucket with the name you enter and appends the current AWS Region and ID for the AWS account that you’re deploying the solution in. The same name is used later in your file identity-center-stacks-parameters.json.
   

   Figure 6: Specifying CloudFormation stack details

3. Keep the defaults for all stack options, and choose Next.
4. 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. AdminDelegated: If you have delegated an administrator for Identity Center, set to true. If you have not delegated an administrator and are deploying in the management account, set to false.
   2. ControlTowerEnabled: If you have AWS Control Tower enabled, set to true. If not, set to false.
   3. OrgManagementAccount: Enter the 12-digit management account ID of your AWS Organization.
   4. 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.
   5. IdentityStoreId: Identity Store ID can be found on the IAM Identity Center console Settings page.
   6. ICInstanceARN: You can find this ARN on the IAM Identity Center console Settings page.
   7. ICMappingBucketName: The same bucket name that you defined in codepipeline-stack.template.
   8. SNSEmailEndpointSubscription: The email address that notifications for the IAM Identity Center permission set will be sent to.
   9. createICAdminRole: If you do not have an existing IAM role or user in your account for administering IAM Identity Center, you can set the value to true, and the solution will create an IAM role for you. If you have an existing IAM role or a user, set it to false and update the ICAutomationAdminArn parameter.
   10. ICAutomationAdminArn: The ARN of an existing IAM role or user in your account that will be used as the IAM Identity Center administrator. Leave it blank if you do not have an existing IAM role or user and if you set createICAdminRole to true.
   11. createICKMSAdminRole: If you do not have an existing IAM role or user in your account for administering AWS Key Management Service (AWS KMS) keys, you can set the value to true and the solution will create an IAM role for you. If you have an existing IAM role or a user, set it to false, and update the ICKMSAdminArn parameter.
   12. ICKMSAdminArn: The ARN of an existing IAM role or user that will have administrator permissions to manage the IAM Identity Center’s AWS KMS key. Leave it blank if you do not have an existing IAM role or user and if you set createICKMSAdminRole to true.
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 you specified in codepipeline-stack.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 CodeCommit. 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 7.
   

   Figure 7: CodePipeline waiting for manual approval

3. 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 8.
   

   Figure 8: Provisioned status of permission sets

2. Verify the account assignments on the management account’s IAM Identity Center console using the List view, as shown in Figure 9.
   

   Figure 9: List of AWS accounts in IAM Identity Center

3. If you deployed in a Control Tower–enabled AWS account or in a delegated administrator account for IAM Identity Center, verify that the Amazon DynamoDB table exists and contains permission set names and ARNs of the skipped permission sets, as shown in Figure 10.
   

   Figure 10: Skipped permission sets in ic-SkippedPermissionSetsTable

4. Verify that manual changes are getting detected and reverted automatically. You can test this by making a manual change, such as creating/deleting a Permission Set, attaching/detaching a Permission Set from accounts, or any other change within IAM Identity Center. This will trigger the EventBridge rule to send an SNS email notification on the specified email address, and will revert the manual changes back to baseline configuration by invoking IC-permissionsets Lambda function and subsequently, ic-auto-assignment-enabler Lambda function.

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