Manage AWS IAM Identity Center permission sets as code by using AWS CodePipeline
Created by Andre Cavalcante (AWS) and Claison Amorim (AWS)
Code repository: aws-iam-identity-center-pipeline | Environment: Production | Technologies: Security, identity, compliance; DevOps |
AWS services: AWS CodeBuild; AWS CodeCommit; AWS CodePipeline; AWS IAM Identity Center |
Summary
AWS IAM Identity Center (successor to AWS Single Sign-On) helps you centrally manage single sign-on (SSO) access to all of your AWS accounts and applications. You can create and manage user identities in IAM Identity Center, or you can connect an existing identity source, such as a Microsoft Active Directory domain or an external identity provider (IdP). IAM Identity Center provides a unified administration experience to define, customize, and assign fine-grained access to your AWS environment by using permission sets. Permission sets apply to the federated users and groups from your AWS IAM Identity Center identity store or your external IdP.
This pattern helps you to manage IAM Identity Center permission sets as code in your multi-account environment that is managed as an organization in AWS Organizations. With this pattern, you can achieve the following:
Create, delete, and update permission sets
Create, update, or delete permission set assignments to target AWS accounts, organizational units (OUs), or your organization root.
To manage IAM Identity Center permissions and assignments as code, this solution deploys a continuous integration and continuous delivery (CI/CD) pipeline that uses AWS CodeCommit, AWS CodeBuild, and AWS CodePipeline. You manage the permission sets and assignments in JSON templates that you store in the CodeCommit repository. When Amazon EventBridge rules detect a change to the repository or detect modifications to the accounts in the target OU, it starts an AWS Lambda function. The Lambda function initiates the CI/CD pipeline that updates the permission sets and assignments in IAM Identity Center.
Prerequisites and limitations
Prerequisites
A multi-account environment managed as an organization in AWS Organizations. For more information, see Creating an organization.
IAM Identity Center, enabled and configured with an identity source. For more information, see Getting Started in the IAM Identity Center documentation.
A member account that is registered as the delegated administrator for IAM Identity Center. For instructions, see Register a member account in the IAM Identity Center documentation.
Permissions to deploy AWS CloudFormation stacks in the IAM Identity Center delegated administrator account and in the organization’s management account. For more information, see Controlling access in the CloudFormation documentation.
An Amazon Simple Storage Service (Amazon S3) bucket in the Identity Center delegated administrator to upload the artifact code. For instructions, see Creating a bucket.
The account ID of the organization’s management account. For instructions, see Finding your AWS account ID.
Limitations
This pattern cannot be used to manage or assign permission sets for single-account environments or for accounts that are not managed as an organization in AWS Organizations.
Permission set names, assignment IDs, and IAM Identity Center principal types and IDs cannot be modified after deployment.
This pattern helps you create and manage custom permissions. You cannot use this pattern to manage or assign predefined permissions.
This pattern cannot be used to manage a permission set for the organization’s management account.
Architecture
Technology stack
AWS CodeBuild
AWS CodeCommit
AWS CodePipeline
Amazon EventBridge
AWS Identity Center
AWS Lambda
AWS Organizations
Target architecture
![Using CI/CD pipeline and AWS CodeCommit repo to manage permission sets in AWS IAM Identity Center.](/images/prescriptive-guidance/latest/patterns/images/pattern-img/419aaa80-1b97-402d-9c74-c1b8c1ddd1cb/images/3d671cf3-329b-4292-aa2d-1027886074f4.png)
The diagram shows the following workflow:
A user makes one of the following changes:
Commits one or more changes to the CodeCommit repository
Modifies the accounts in the organization unit (OU) in AWS Organizations
If the user committed a change to the CodeCommit repository, then the
CodeChange
EventBridge rule detects the change and starts a Lambda function in the IAM Identity Center delegated administrator account. The rule doesn’t react to changes in certain files in the repository, such as theREADME.md
file.If the user modified the accounts in the organizational unit, then the
MoveAccount
EventBridge rule detects the change and starts a Lambda function in the organization’s management account.The initiated Lambda function starts the CI/CD pipeline in CodePipeline.
CodePipeline starts the
CodebuildTemplateValidation
CodeBuild project.The
CodebuildTemplateValidation
CodeBuild project uses a Python script in the CodeCommit repository to validate the permission set templates. CodeBuild validates the following:The permission set names are unique.
The assignment statement IDs (
Sid
) are unique.Policy definitions in the
CustomPolicy
parameter and valid. (This validation uses AWS Identity and Access Management Access Analyzer.)The Amazon Resource Names (ARNs) of the managed policies are valid.
The
CodebuildPermissionSet
CodeBuild project uses AWS SDK for Python (Boto3) to delete, create, or update the permission sets in IAM Identity Center. Only permission sets with theSSOPipeline:true
tag are affected. All permission sets that are managed through this pipeline have this tag.The
CodebuildAssignments
CodeBuild project uses Terraform to delete, create, or update the assignments in IAM Identity Center. The Terraform backend state files are stored in an S3 bucket in the same account.CodeBuild assumes a
lookup
IAM role in the organization’s management account. It calls the organizations and identitystoreAPIs in order to list the resources required to grant or revoke permissions. CodeBuild updates the permissions sets and assignments in IAM Identity Center.
Automation and scale
Because all new accounts in a multi-account environment are moved to a specific organizational unit in AWS Organizations, this solution automatically runs and grants the required permission sets to all accounts that you specify in the assignment templates. No additional automations or scaling actions are necessary.
In large environments, the number of API requests to IAM Identity Center might cause this solution to run more slowly. Terraform and Boto3 automatically manage throttling to minimize any performance degradation.
Tools
AWS services
AWS CloudFormation helps you set up AWS resources, provision them quickly and consistently, and manage them throughout their lifecycle across AWS accounts and Regions.
AWS CodeBuild is a fully managed build service that helps you compile source code, run unit tests, and produce artifacts that are ready to deploy.
AWS CodeCommit is a version control service that helps you privately store and manage Git repositories, without needing to manage your own source control system.
AWS CodePipeline helps you quickly model and configure the different stages of a software release and automate the steps required to release software changes continuously.
Amazon EventBridge is a serverless event bus service that helps you connect your applications with real-time data from a variety of sources. For example, AWS Lambda functions, HTTP invocation endpoints using API destinations, or event buses in other AWS accounts.
AWS IAM Identity Center helps you centrally manage single sign-on (SSO) access to all of your AWS accounts and cloud applications.
AWS Organizations is an account management service that helps you consolidate multiple AWS accounts into an organization that you create and centrally manage.
AWS SDK for Python (Boto3)
is a software development kit that helps you integrate your Python application, library, or script with AWS services. Amazon Simple Storage Service (Amazon S3) is a cloud-based object storage service that helps you store, protect, and retrieve any amount of data.
Code repository
The code for this pattern is available in the aws-iam-identity-center-pipeline
Best practices
Before you start modifying the permission set and assignment templates, we recommend that you plan permission sets for your organization. Consider what the permissions should be, which accounts or OUs the permission set should apply to, and which IAM Identity Center principals (users or groups) should be affected by the permission set. Permission set names, association IDs, and IAM Identity Center principal types and IDs cannot be modified after deployment.
Adhere to the principle of least privilege and grant the minimum permissions required to perform a task. For more information, see Grant least privilege and Security best practices in the IAM documentation.
Epics
Task | Description | Skills required |
---|---|---|
Clone the repository. | In a bash shell, enter the following command. This clones the aws-iam-identity-center-pipeline
| DevOps engineer |
Define the permission sets. |
| DevOps engineer |
Define the assignments. |
| DevOps engineer |
Task | Description | Skills required |
---|---|---|
Upload the files to an S3 bucket. |
| DevOps engineer |
Deploy resources in the IAM Identity Center delegated administrator account. |
| DevOps engineer |
Deploy resources in AWS Organization management account. |
| DevOps engineer |
Task | Description | Skills required |
---|---|---|
Update the permission sets and assignments. | When the If you want to modify the deployed permission sets and assignments, update the JSON files and then commit them to the CodeCommit repository in the IAM Identity Center delegated administrator account. For instructions, see Create a commit in the CodeCommit documentation. Note the following when using the CI/CD pipeline to manage previously deployed permission sets and associations:
| DevOps engineer |
Troubleshooting
Issue | Solution |
---|---|
Access denied errors | Confirm that you have the permissions required to deploy the CloudFormation templates and the resources defined within them. For more information, see Controlling access in the CloudFormation documentation. |
Pipeline errors in the validation phase | This error appears if there are any errors in the permission set or assignment templates.
|
Related resources
Permission sets (IAM Identity Center documentation)