Manage AWS IAM Identity Center permission sets as code by using AWS CodePipeline - AWS Prescriptive Guidance
SummaryPrerequisites and limitationsArchitectureToolsBest practicesEpicsTroubleshootingRelated resources

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.

The diagram shows the following workflow:

  1. A user makes one of the following changes:

    1. Commits one or more changes to the CodeCommit repository

    2. Modifies the accounts in the organization unit (OU) in AWS Organizations

  2. 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 the README.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.

  3. The initiated Lambda function starts the CI/CD pipeline in CodePipeline.

  4. CodePipeline starts the CodebuildTemplateValidation CodeBuild project.

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

  6. 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 the SSOPipeline:true tag are affected. All permission sets that are managed through this pipeline have this tag.

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

  8. CodeBuild assumes a lookup IAM role in the organization’s management account. It calls the organizations and identitystore APIs in order to list the resources required to grant or revoke permissions.

  9. 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 repository. The templates folder in the repository includes sample templates for both permission sets and assignments. It also includes AWS CloudFormation templates for deploying the CI/CD pipeline and AWS resources in the target accounts.

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

TaskDescriptionSkills required

Clone the repository.

In a bash shell, enter the following command. This clones the aws-iam-identity-center-pipeline repository from GitHub.

git clone https://github.com/aws-samples/aws-iam-identity-center-pipeline.git
DevOps engineer

Define the permission sets.

  1. In the cloned repository, navigate to the templates/permissionsets folder, and then open one of the available templates.

  2. In the Name parameter, enter a name for the permission set. This value must be unique, and it cannot be changed after deployment.

  3. In the Description parameter, briefly describe the permission set, such as its use case.

  4. In the SessionDuration parameter, specify the length of time that a user can be signed in to an AWS account. Use ISO-8601 duration format (Wikipedia), such as PT4H for 4 hours. If no value is defined, the default in IAM Identity Center is 1 hour.

  5. Customize the policies in the permission set. All of the following parameters are optional and can be modified after deployment. You must use at least one of the parameters in order to define the policies in the permission set:

    • In the ManagedPolicies parameter, enter the ARNs of any AWS managed policies that you want to assign.

    • In the CustomerManagedPolicies parameter, enter the names of any customer managed policies that you want to assign. Do not use the ARN.

    • In the PermissionBoundary parameter, do the following to assign a permission boundary:

      • If you’re using an AWS managed policy as a permission boundary, in PolicyType, enter AWS, and in Policy, enter the ARN of the policy.

      • If you’re using a customer managed policy as a permission boundary, in PolicyType, enter Customer, and in Policy, enter the name of the policy. Do not use the ARN.

    • In the CustomPolicy parameter, define any custom, JSON-formatted policies that you want to assign. For more information about the JSON policy structure, see Overview of JSON policies.

  6. Save and close the permission set template. We recommend that you save the file with a name that matches the name of the permission set.

  7. Repeat this process to create as many permissions sets as needed for your organization, and delete any sample templates that aren’t required.

DevOps engineer

Define the assignments.

  1. In the cloned repository, navigate to the templates/assignments folder, and then open iam-identitycenter-assigments.json. This file describes how you want to assign the permission sets to AWS accounts or OUs.

  2. In the SID parameter, enter an identifier for the assignment. This value must be unique, and it cannot be modified after deployment.

  3. In the Target parameter, define the accounts or organizations where you want to apply the permission set. Valid values are account IDs, OU IDs, OU names, or root. root assigns the permission set to all member accounts in the organization, excluding the management account. Enter the values in double quotation marks, and separate multiple values with commas. For instructions about how to find IDs, see Viewing details of an account or Viewing the details of an OU.

  4. In the PrincipalType parameter, enter the type of IAM Identity Center principal that will be affected by the permission set. Valid values are USER or GROUP. This value cannot be modified after deployment.

  5. In the PrincipalID parameter, enter the name of the user or group in the IAM Identity Center identity store that will be affected by the permission set. This value cannot be modified after deployment.

  6. In the PermissionSetName parameter, enter the name of the permission set that you want to assign.

  7. Repeat steps 2–6 to create as many assignments as needed in this file. Typically, there is one assignment for each permission set. Delete any sample assignments that aren’t required.

  8. Save and close the iam-identitycenter-assigments.json file.

DevOps engineer
TaskDescriptionSkills required

Upload the files to an S3 bucket.

  1. Compress the cloned repository into a .zip file.

  2. Sign in to the IAM Identity Center delegated administrator account.

  3. Open the Amazon S3 console at https://console.aws.amazon.com/s3/.

  4. In the left navigation pane, choose Buckets.

  5. Choose the bucket that you want to use to deploy this solution.

  6. Upload the .zip file to the target S3 bucket. For instructions, see Uploading objects.

DevOps engineer

Deploy resources in the IAM Identity Center delegated administrator account.

  1. In the IAM Identity Center delegated administrator account, open the CloudFormation console at https://console.aws.amazon.com/cloudformation/.

  2. Deploy the iam-identitycenter-pipeline.yaml template. Give the stack a clear and descriptive name, and update the parameters as instructed. For instructions, see Creating a stack in the CloudFormation documentation.

DevOps engineer

Deploy resources in AWS Organization management account.

  1. Sign in to the organization’s management account.

  2. Open the CloudFormation console at https://console.aws.amazon.com/cloudformation/.

  3. In the navigation bar, choose the name of the currently displayed AWS Region. Then choose the us-east-1 Region. This Region is required so that the MoveAccount EventBridge rule can detect AWS CloudTrail events associated with organization changes.

  4. Deploy the iam-identitycenter-organization template. Give the stack a clear and descriptive name, and update the parameters as instructed. For instructions, see Creating a stack in the CloudFormation documentation.

DevOps engineer
TaskDescriptionSkills required

Update the permission sets and assignments.

When the MoveAccount Amazon EventBridge rule detects modifications to the accounts in the organization, the CI/CD pipeline automatically starts and updates the permission sets. For example, if you add an account to an OU specified in the assignments JSON file, then the CI/CD pipeline will apply the permission set to the new account.

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:

  • If you change the name of a permission set, the CI/CD pipeline deletes the original permission set and creates a new one.

  • This pipeline manages only permission sets that have the SSOPipeline:true tag.

  • You can have multiple permission set and assignment templates in the same folder in the repository.

  • If you delete a template, the pipeline deletes the assignment or permission set.

  • If you delete an entire assignment JSON block, the pipeline deletes the assignment from IAM Identity Center.

  • You can't delete a permission set that is assigned to an AWS account. First, you must unassign the permission set.

DevOps engineer

Troubleshooting

IssueSolution

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.

  1. In CodeBuild, view the build details.

  2. In the build log, find the validation error that provides more information about what caused the build to fail.

  3. Update the permission set or assignment templates, and then commit them to the repository.

  4. The CI/CD pipeline restarts the CodeBuild project. Monitor the status to confirm that the validation error is resolved.

Related resources