AWS Security Blog
Use new account assignment APIs for AWS SSO to automate multi-account access
September 28, 2022: In July 2022, we renamed AWS Single Sign-On to AWS IAM Identity Center. In this blog, you will notice that we preserved backward compatibility with API calls and CLI scripts by retaining the API and CLI namespaces that were used under AWS Single Sign-On.
September 12, 2022: This blog post has been updated to reflect the new name of AWS Single Sign-On (SSO) – AWS IAM Identity Center. Read more about the name change here.
February 18, 2021: We updated the name of the organization management account used in the example. The new name is ExampleOrgManagement.
February 10, 2021: We updated the commands in the Cleanup section of this post.
In this blog post, we’ll show how you can programmatically assign and audit access to multiple AWS accounts for your AWS IAM Identity Center (IAM Identity Center) users and groups, using the AWS Command Line Interface (AWS CLI) and AWS CloudFormation.
With AWS IAM Identity Center, you can centrally manage access and user permissions to all of your accounts in AWS Organizations. You can assign user permissions based on common job functions, customize them to meet your specific security requirements, and assign the permissions to users or groups in the specific accounts where they need access. You can create, read, update, and delete permission sets in one place to have consistent role policies across your entire organization. You can then provide access by assigning permission sets to multiple users and groups in multiple accounts all in a single operation.
AWS IAM Identity Center recently added new account assignment APIs and AWS CloudFormation support to automate access assignment across AWS Organizations accounts. This release addressed feedback from our customers with multi-account environments who wanted to adopt AWS IAM Identity Center, but faced challenges related to managing AWS account permissions. To automate the previously manual process and save your administration time, you can now use the new AWS IAM Identity Center account assignment APIs, or AWS CloudFormation templates, to programmatically manage AWS account permission sets in multi-account environments.
With AWS IAM Identity Center account assignment APIs, you can now build your automation that will assign access for your users and groups to AWS accounts. You can also gain insights into who has access to which permission sets in which accounts across your entire AWS Organizations structure. With the account assignment APIs, your automation system can programmatically retrieve permission sets for audit and governance purposes, as shown in Figure 1.
Overview
In this walkthrough, we’ll illustrate how to create permission sets, assign permission sets to users and groups in AWS IAM Identity Center, and grant access for users and groups to multiple AWS accounts by using the AWS Command Line Interface (AWS CLI) and AWS CloudFormation.
To grant user permissions to AWS resources with AWS IAM Identity Center, you use permission sets. A permission set is a collection of AWS Identity and Access Management (IAM) policies. Permission sets can contain up to 10 AWS managed policies and a single custom policy stored in AWS IAM Identity Center.
A policy is an object that defines a user’s permissions. Policies contain statements that represent individual access controls (allow or deny) for various tasks. This determines what tasks users can or cannot perform within the AWS account. AWS evaluates these policies when an IAM principal (a user or role) makes a request.
When you provision a permission set in the AWS account, AWS IAM Identity Center creates a corresponding IAM role on that account, with a trust policy that allows users to assume the role through AWS IAM Identity Center. With AWS IAM Identity Center, you can assign more than one permission set to a user in the specific AWS account. Users who have multiple permission sets must choose one when they sign in through the user portal or the AWS CLI. Users will see these as IAM roles.
To learn more about IAM policies, see Policies and permissions in IAM. To learn more about permission sets, see Permission Sets.
Assume you have a company, Example.com, which has three AWS accounts: an organization management account (ExampleOrgManagement), a development account (ExampleOrgDev), and a test account (ExampleOrgTest). Example.com uses AWS Organizations to manage these accounts and has already enabled AWS IAM Identity Center.
Example.com has the IT security lead, Frank Infosec, who needs PowerUserAccess to the test account (ExampleOrgTest) and SecurityAudit access to the development account (ExampleOrgDev). Alice Developer, the developer, needs full access to Amazon Elastic Compute Cloud (Amazon EC2) and Amazon Simple Storage Service (Amazon S3) through the development account (ExampleOrgDev). We’ll show you how to assign and audit the access for Alice and Frank centrally with AWS IAM Identity Center, using the AWS CLI.
The flow includes the following steps:
- Create three permission sets:
- PowerUserAccess, with the PowerUserAccess policy attached.
- AuditAccess, with the SecurityAudit policy attached.
- EC2-S3-FullAccess, with the AmazonEC2FullAccess and AmazonS3FullAccess policies attached.
- Assign permission sets to the AWS account and AWS IAM Identity Center users:
- Assign the PowerUserAccess and AuditAccess permission sets to Frank Infosec, to provide the required access to the ExampleOrgDev and ExampleOrgTest accounts.
- Assign the EC2-S3-FullAccess permission set to Alice Developer, to provide the required permissions to the ExampleOrgDev account.
- Retrieve the assigned permissions by using Account Entitlement APIs for audit and governance purposes.
Note: AWS IAM Identity Center Permission sets can contain either AWS managed policies or custom policies that are stored in AWS IAM Identity Center. In this blog we attach AWS managed polices to the AWS IAM Identity Center Permission sets for simplicity. To help secure your AWS resources, follow the standard security advice of granting least privilege access using AWS IAM Identity Center custom policy while creating AWS IAM Identity Center Permission set.
To help simplify administration of access permissions, we recommend that you assign access directly to groups rather than to individual users. With groups, you can grant or deny permissions to groups of users, rather than having to apply those permissions to each individual. For simplicity, in this blog you’ll assign permissions directly to the users.
Prerequisites
Before you start this walkthrough, complete these steps:
- Identify the AWS accounts to which you want to grant AWS IAM Identity Center access, and add them to your organization. To learn more, see Managing the AWS accounts in your organization.
- Get the permissions that are required to use the AWS IAM Identity Center console. To learn more, see Permissions Required to Use the AWS IAM Identity Center Console.
- Sign in to the AWS Organizations management account AWS Management Console with AWS IAM Identity Center administrator credentials. To learn more about AWS Organizations and the management account, see AWS Organizations FAQs.
- Enable AWS IAM Identity Center for your AWS Organizations structure. To learn more, see Enable AWS IAM Identity Center.
- Have your users and groups provisioned in AWS IAM Identity Center. You can manage your users and groups in AWS IAM Identity Center internal identity store, connect AWS IAM Identity Center to your Microsoft Active Directory or integrate with an external identity provider using SAML 2.0 and SCIM 2.0. To learn more about AWS IAM Identity Center identity store options, see Manage Your Identity Source.
Use the AWS IAM Identity Center API from the AWS CLI
In order to call the AWS IAM Identity Center account assignment API by using the AWS CLI, you need to install and configure AWS CLI v2. For more information about AWS CLI installation and configuration, see Installing the AWS CLI and Configuring the AWS CLI.
Step 1: Create permission sets
In this step, you learn how to create EC2-S3FullAccess, AuditAccess, and PowerUserAccess permission sets in AWS IAM Identity Center from the AWS CLI.
Before you create the permission sets, run the following command to get the Amazon Resource Name (ARN) of the AWS IAM Identity Center instance and the Identity Store ID, which you will need later in the process when you create and assign permission sets to AWS accounts and users or groups.
Figure 3 shows the results of running the command.
Next, create the permission set for the security team (Frank) and dev team (Alice), as follows.
Permission set for Alice Developer (EC2-S3-FullAccess)
Run the following command to create the EC2-S3-FullAccess permission set for Alice, as shown in Figure 4.
Permission set for Frank Infosec (AuditAccess)
Run the following command to create the AuditAccess permission set for Frank, as shown in Figure 5.
Permission set for Frank Infosec (PowerUserAccess)
Run the following command to create the PowerUserAccess permission set for Frank, as shown in Figure 6.
Copy the permission set ARN from these responses, which you will need when you attach the managed policies.
Step 2: Assign policies to permission sets
In this step, you learn how to assign managed policies to the permission sets that you created in step 1.
Attach policies to the EC2-S3-FullAccess permission set
Run the following command to attach the amazonec2fullacess AWS managed policy to the EC2-S3-FullAccess permission set, as shown in Figure 7.
Run the following command to attach the amazons3fullaccess AWS managed policy to the EC2-S3-FullAccess permission set, as shown in Figure 8.
Attach a policy to the AuditAccess permission set
Run the following command to attach the SecurityAudit managed policy to the AuditAccess permission set that you created earlier, as shown in Figure 9.
Attach a policy to the PowerUserAccess permission set
The following command is similar to the previous command; it attaches the PowerUserAccess managed policy to the PowerUserAccess permission set, as shown in Figure 10.
In the next step, you assign users (Frank Infosec and Alice Developer) to their respective permission sets and assign permission sets to accounts.
Step 3: Assign permission sets to users and groups and grant access to AWS accounts
In this step, you assign the AWS IAM Identity Center permission sets you created to users and groups and AWS accounts, to grant the required access for these users and groups on respective AWS accounts.
To assign access to an AWS account for a user or group, using a permission set you already created, you need the following:
- The principal ID (the ID for the user or group)
- The AWS account ID to which you need to assign this permission set
To obtain a user’s or group’s principal ID (UserID or GroupID), you need to use the AWS IAM Identity Center Identity Store API. The AWS IAM Identity Center Identity Store service enables you to retrieve all of your identities (users and groups) from AWS IAM Identity Center. See AWS IAM Identity Center Identity Store API for more details.
Use the first two commands shown here to get the principal ID for the two users, Alice (Alice’s user name is alice@example.com) and Frank (Frank’s user name is frank@example.com).
Alice’s user ID
Run the following command to get Alice’s user ID, as shown in Figure 11.
Frank’s user ID
Run the following command to get Frank’s user ID, as shown in Figure 12.
Note: To get the principal ID for a group, use the following command.
Assign the EC2-S3-FullAccess permission set to Alice in the ExampleOrgDev account
Run the following command to assign Alice access to the ExampleOrgDev account using the EC2-S3-FullAccess permission set. This will give Alice full access to Amazon EC2 and S3 services in the ExampleOrgDev account.
Note: When you call the CreateAccountAssignment API, AWS IAM Identity Center automatically provisions the specified permission set on the account in the form of an IAM policy attached to the AWS IAM Identity Center–created IAM role. This role is immutable: it’s fully managed by the AWS IAM Identity Center, and it cannot be deleted or changed by the user even if the user has full administrative rights on the account. If the permission set is subsequently updated, the corresponding IAM policies attached to roles in your accounts won’t be updated automatically. In this case, you will need to call ProvisionPermissionSet to propagate these updates.
Assign the AuditAccess permission set to Frank Infosec in the ExampleOrgDev account
Run the following command to assign Frank access to the ExampleOrgDev account using the EC2-S3- AuditAccess permission set.
Assign the PowerUserAccess permission set to Frank Infosec in the ExampleOrgTest account
Run the following command to assign Frank access to the ExampleOrgTest account using the PowerUserAccess permission set.
To view the permission sets provisioned on the AWS account, run the following command, as shown in Figure 16.
To review the created resources in the AWS Management Console, navigate to the AWS IAM Identity Center console. In the list of permission sets on the AWS accounts tab, choose the EC2-S3-FullAccess permission set. Under AWS managed policies, the policies attached to the permission set are listed, as shown in Figure 17.
To see the AWS accounts, where the EC2-S3-FullAccess permission set is currently provisioned, navigate to the AWS accounts tab, as shown in Figure 18.
Step 4: Audit access
In this step, you learn how to audit access assigned to your users and group by using the AWS IAM Identity Center account assignment API. In this example, you’ll start from a permission set, review the permissions (AWS-managed policies or a custom policy) attached to the permission set, get the users and groups associated with the permission set, and see which AWS accounts the permission set is provisioned to.
List the IAM managed policies for the permission set
Run the following command to list the IAM managed policies that are attached to a specified permission set, as shown in Figure 19.
List the assignee of the AWS account with the permission set
Run the following command to list the assignee (the user or group with the respective principal ID) of the specified AWS account with the specified permission set, as shown in Figure 20.
List the accounts to which the permission set is provisioned
Run the following command to list the accounts that are associated with a specific permission set, as shown in Figure 21.
In this section of the post, we’ve illustrated how to create a permission set, assign a managed policy to the permission set, and grant access for AWS IAM Identity Center users or groups to AWS accounts by using this permission set. In the next section, we’ll show you how to do the same using AWS CloudFormation.
Use the AWS IAM Identity Center API through AWS CloudFormation
In this section, you learn how to use CloudFormation templates to automate the creation of permission sets, attach managed policies, and use permission sets to assign access for a particular user or group to AWS accounts.
Sign in to your AWS Management Console and create a CloudFormation stack by using the following CloudFormation template. For more information on how to create a CloudFormation stack, see Creating a stack on the AWS CloudFormation console.
When you create the stack, provide the following information for setting the example permission sets for Frank Infosec and Alice Developer, as shown in Figure 22:
- The Alice Developer and Frank Infosec user IDs
- The ExampleOrgDev and ExampleOrgTest account IDs
- The AWS IAM Identity Center instance ARN
Then launch the CloudFormation stack.
AWS CloudFormation creates the resources that are shown in Figure 23.
Cleanup
To delete the resources you created by using the AWS CLI, use these commands.
Run the following command to delete the account assignment.
After the account assignment is deleted, run the following command to delete the permission set.
To delete the resource that you created by using the CloudFormation template, go to the AWS CloudFormation console. Select the appropriate stack you created, and then choose delete. Deleting the CloudFormation stack cleans up the resources that were created.
Summary
In this blog post, we showed how to use the AWS IAM Identity Center account assignment API to automate the deployment of permission sets, how to add managed policies to permission sets, and how to assign access for AWS users and groups to AWS accounts by using specified permission sets.
To learn more about the AWS IAM Identity Center APIs available for you, see the AWS IAM Identity Center API Reference Guide.
If you have feedback about this post, submit comments in the Comments section below. If you have questions about this post, start a new thread on the AWS IAM Identity Center forum or contact AWS Support.
Want more AWS Security how-to content, news, and feature announcements? Follow us on Twitter.