AWS Open Source Blog

Accelerate AWS IAM Identity Center (Successor to AWS Single Sign-On) Implementation using AWS Cloud Development Kit (AWS CDK)

In conversations with our customers, we often hear that they find it tedious to write AWS CloudFormation templates to create new permission sets, assign permission sets to users and groups in AWS IAM Identity Center (successor to AWS Single Sign-On) and grant access for users and groups to multiple AWS accounts in their organization. This problem compounds when you have a large organization structure with many AWS accounts under different organizational units (OU’s) in AWS Organizations and your AWS accounts may also change frequently. You have to duplicate and define the new account assignment resource entity AWS::SSO::Assignment as many times as the total number of AWS accounts that you wish to grant a user or group access to, manually changing its TargetId value (an AWS account identifier) each time the resource is defined in your template. Rinse and repeat this whole process of new account assignment for each user or group and their assigned permission set. It is no fun!

In September 2020, IAM Identity Center added new account assignment APIs and CloudFormation support to automate multi-account access and in February 2021, our colleagues at AWS wrote a blog post on how you can use the new account assignment APIs for IAM Identity Center to automate multi-account access.*

*Note: This blog post uses the name AWS SSO, the service is now called IAM Identity Center (successor to AWS Single Sign-On).

When we study the CloudFormation resource entities for IAM Identity Center, there is some prerequisite information needed prior to creating these CloudFormation templates for new account permissions — namely the IAM Identity Center instance ARN, principal ID for each user or group that you wish to assign to, permission set ARNs, and the AWS account identifiers that you wish to grant access to. This prerequisite information can be retrieved programmatically using the AWS Command Line Interface (AWS CLI) or in the IAM Identity Center Console and is demonstrated in the previously mentioned blog post.

In this blog post, we will show how you can harness the power of the open source AWS Cloud Development Kit (AWS CDK) to programmatically generate and optionally, deploy the CloudFormation templates for IAM Identity Center that are responsible for creating the new permission sets and account assignments for the relevant groups in your large organization. Note that this program is written to support assignments to groups rather than to individual users to help simplify administration of access permissions. Groups are useful when assigning access to AWS accounts and applications. Rather than assigning each user individually, you give permissions to a group. Later, as you add or remove users from a group, the user dynamically is granted or loses access to accounts and applications that you assigned to the group.

Prerequisites

Before you start this walkthrough, you should have the following prerequisites:

  • An organization in AWS Organizations
  • Administrative access to the management account in AWS Organizations
  • Groups in IAM Identity Center
    • We’ve used 8 groups in our example
    • We recommend having at least 2 or 3 to test the automation
  • Python version 3.7.10 or later
  • Git
  • AWS CDK v2

Program Environment Setup
You can find the source code for this post in the AWS samples repository on GitHub.

Clone the repo:

$ git clone https://github.com/aws-samples/aws-iam-identity-center-automation.git

To create a virtualenv run the following command after installing Python:

$ python3 -m venv .env

On macOS/Linux, run the following command to activate your virtualenv:

$ source .env/bin/activate

On Windows, run the following command to activate your virtualenv:

$ .env\Scripts\activate.bat

Once the virtualenv is activated, install the required dependencies:

$ pip install -r requirements.txt

We recommend setting up a named profile for the AWS CLI using the administrative credentials for the management account in AWS Organizations to use when running commands. As a placeholder in this post we’ve used the profile name “IAMIdentityCenter-test”. You can also configure your AWS profile using the following command, which will set up the default profile:

$ aws configure

Run the Help (-h) command to make sure that you have your environment setup correctly:

$ python id_center_automation.py id-center -h
usage: id_center_automation.py id-center [-h] [--permsets PERMSETS] [--assignments ASSIGNMENTS] [--mgmtacct MGMTACCT] -p PROFILE -r REGION [-d] [--destroy]

optional arguments:
  -h, --help            show this help message and exit
  --permsets PERMSETS   File containing permission sets
  --assignments ASSIGNMENTS
                        File containing assigments
  --mgmtacct MGMTACCT   AWS Organizations Management Account
  -p PROFILE, --profile PROFILE
                        Your AWS Profile
  -r REGION, --region REGION
                        AWS Region
  -d, --deploy          Deploy changes
  --destroy             Destroy the deployed CFN stack

You can use the following command to output a JSON file named “org_data.json” that describes your AWS organization structure with the necessary IDs to use in the IAM Identity Center input files:

$ python id_center_automation.py describe-org --profile IAMIdentityCenter-test

Step 1: Define New Permission Sets

Create all your inline custom IAM policies inside the sub folder named “inline_policies”.

Here is an example of powerusercustompolicy.json:

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Sid": "PreventPrivilegeEscalation",
			"Effect": "Deny",
			"Action": [
				"iam:PassRole"
			],
			"Resource": [
				"arn:aws:iam::*:role/aws-reserved/sso.amazonaws.com/*/AWSReservedSSO_AWSAdministratorAccess_*",
				"arn:aws:iam::*:role/*ControlTower*",
				"arn:aws:iam::*:role/*controltower*"
			]
		}
	]
}

Next, create a file named “permsets.json” in the root folder and put in the details for the permission sets you would like to create. Your file should follow this format:

{
	"permissionSets": [
		{
			"permissionSetName": "YourPermissionSetName",
			"managedPolicies": [
				"arn:aws:iam::aws:policy/ManagedPolicy1",
				"arn:aws:iam::aws:policy/ManagedPolicy2",
				"arn:aws:iam::aws:policy/ManagedPolicy3"
			],
			"customPolicy": "custompolicy.json"
		}
	],
}

Note that you can specify up to ten job-related or service-specific AWS managed policies and one inline custom policy for each permission set.

Another example of a permission sets file is included in the root folder (example_permsets.json).

Step 2: Define New Account Assignments

Next, create a text file named “assignments.json” in the root folder and put in the details for the new account assignments you would like to create. Use the target to change the scope with the option to apply to all accounts, all accounts under an OU, or one specific account.

To assign a new permission set to a group and grant access to all accounts in the Organization with this new permission set:

{
	"permissionSet" : "<new permission set name>",
	"groupName" : "<group name>",
	"target" : "all"
}

To assign a new permission set to a group and grant the group access to a specific OU in the organization with this new permission set:

{
	"permissionSet" : "<new permission set name>",
	"groupName" : "<group name>",
	"target" : "<OU ID>"
}

Follow these links to understand what an OU unique identifier (ID) is and how to find out your OU ID.

To assign a new permission set to a group and grant the group access to a specific AWS account in the organization with this new permission set:

{
	"permissionSet" : "<new permission set name>",
	"groupName" : "<group name>",
	"target" : "<AWS Account ID>"
}

An example of a new account assignment file is also included in the root folder (example_assignments.json).

Step 3: Generate IAM Identity Center CloudFormation templates

The following command will generate the CloudFormation template in the “cfn_templates” folder to apply the configured changes without deploying them:

$ python id_center_automation.py id-center --region us-east-1 --profile IAMIdentityCenter-test --mgmtacct 123456789012 --permsets permsets.json --assignments assignments.json

Before deploying your changes, we strongly recommend doing a review of the template after it’s generated to ensure it contains all the desired changes.

[Optional] Step 4: Deploy IAM Identity Center CloudFormation templates

Bootstrap your AWS account so that you can deploy your changes programmatically.

Generate CDK Bootstrap CloudFormation Template:

macOS/Linux:

$ cdk bootstrap --show-template > ./cfn_templates/bootstrap-template.yaml

Windows:

$ powershell "cdk bootstrap --show-template | Out-File -encoding utf8 ./cfn_templates/bootstrap-template.yaml"

Deploy the CDK Bootstrap template stack using cdk bootstrap –template:

macOS/Linux:

$ cdk bootstrap --template ./cfn_templates/bootstrap-template.yaml

Windows:

$ powershell "cdk bootstrap --template ./cfn_templates/bootstrap-template.yaml"

Once CDK has been bootstrapped you can use the following command to deploy your changes by adding the deploy flag:

$ python id_center_automation.py id-center --region us-east-1 --profile IAMIdentityCenter-test --mgmtacct 123456789012 --permsets permsets.json --assignments assignments.json --deploy

Step 5: Clean-up

Destroy the stack by adding the “–destroy” flag:

$ python id_center_automation.py id-center --region us-east-1 --profile IAMIdentityCenter-test --mgmtacct 123456789012 --permsets permsets.json --assignments assignments.json --destroy

Conclusion

In this blog post, we showed you how to leverage AWS CDK to programmatically generate and deploy the CloudFormation templates for IAM Identity Center that are responsible for creating the new permission sets and account assignments for the relevant groups in your large organization.

To learn more about the AWS CDK Toolkit, see Getting started with the AWS CDK.

When you connect an external identity provider to AWS IAM Identity Center using Security Assertion Markup Language 2.0, you must create all users and groups before you can make any assignments to AWS accounts or applications. Read the following blog to learn how to bulk import users and groups from CSV into IAM Identity Center. *

If you have feedback about this post, submit comments in the Comments section below.

Jasmine Chua

Jasmine Chua

Jasmine Chua is a Senior Security Specialist Solutions Architect based in Singapore, specializing in cyber security and digital forensics field. She has a couple of AWS certifications and security certifications including CISSP, CISA, ENCE, GCFA, GREM, GNFA, GCTI, GCIH and GSEC. She enjoys helping customers build their security confidence and capabilities in AWS.

Kevin Taylor

Kevin Taylor

Kevin Taylor is a Senior Solutions Architect based in Ottawa, Canada, specializing in national security and defence with the Canadian federal government.