aws-samples / aws-permission-set-assignment-custom-resource

This CDK project provides an example solution of how customers can automate the association of permission sets with AWS users and groups to accounts and organizational units (OUs) within an AWS organization using CloudFormation custom resources.

aws-permission-set-assignment-custom-resource

Overview

AWS IAM Identity Center provides a way for organizations to centrally manage the administration of users and their access to AWS accounts via the AWS Console. However, large enterprises, with many accounts, need a solution for automatically associating groups of users with specific permission sets to accounts in a given organizational units. This CDK project provides an example solution of how customers can automate the association of permission sets with AWS users and groups to accounts and organizational units (OUs) within an AWS organization using CloudFormation custom resources.

Prerequisites

• Install NodeJS
• AWS Organization
• AWS Control Tower
• AWS IAM Identity Center
  • An AWS IAM Identity Center delegated administration account

Architecture

The CDK application consists of two CloudFormation stacks; PermissionSetAssignmentCustomResourceStack and ControlTowerLifeCycleEventSourceRuleStack.

PermissionSetAssignmentCustomResourceStack

This stack is designed to be deployed in the AWS IAM Identity Center delegated administration account. It deploys infrastructure and resources that are used to manage permission set associations between users/groups and AWS accounts. The stack consists of the following components

• AssignPermissionSetsTable - An AWS DynamoDB table that stores information on the completion status of AWS Step Functions state machines along with accounts and organizational unit associations with permission-set-assignment CloudFormation stacks.
• PermissionSetAssignment - A custom CDK construct whose components handle the creation, update, and deletion of permission set associations to users and group for AWS accounts as specified in permission-set-assignment CloudFormation stacks
  • permissionSetAssignmentHandler - A lambda function that processes a CdkCustomResourceEvent, transforms the input from a permission-set-assignment stack into AccountAssignmentCommandInput objects, records the targets in the AssignPermissionSetsTable, and then submits that input to the assignPermissionSetsStateMachine for processing.
  • permissionSetAssignmentIsCompleteHandler - A lambda function that provides asynchronous status information to CloudFormation.
  • permissionSetAssignmentProvider - The AWS CloudFormation custom resource provider
  • assignPermissionSetsStateMachine - AWS Step Function standard state machine that maps AccountAssignmentCommandInput to create/delete state machine inputs.
    • createAccountAssignmentStateMachine - AWS Step Functions express state machine for creating permission set associations
    • deleteAccountAssignmentStateMachine - AWS Step Functions express state machine for deleting permission set associations
• ControlTowerLifeCycleEvent - A custom CDK construct whose components handle Control Tower lifecycle events, UpdateManagedAccount and CreateManagedAccount, that are forwarded from the AWS Organization management account.
  • onControlTowerLifeCycleEvent - Retrieves the associations at the root, ou, and account level for the account that generated the event and runs applicable permission-set-assignment stacks.
    • onUpdateManagedAccountHandler
    • onCreateManagedAccount
  • ControlTowerLifeCycleEventBus - An Amazon EventBridge eventbus the receives Control Tower LifeCycle Events, UpdateManagement and CreateManagedAccount, forwarded from the AWS Organization management account.
    • onControlTowerLifecycleEventCreateManagedAccountSuccess - Handles CreateManagedAccount events and trigger permission-set-assignment CloudFormation stacks that would apply to the root, ou, or account of the newly created account
    • onControlTowerLifecycleEventUpdateManagedAccountSuccess - Handles UpdateManagedAccount events and trigger permission-set-assignment CloudFormation stacks that would apply to the root, ou, or account of the updated account

Creation of permission set

The diagram above summarizes the system interactions executed to create a permission set assignment

• An AWS Identity Center administrator would specify a permission set assignment via the permission-set-assignment.yaml template which they would deploy via CloudFormation either through the AWS console or the AWS CLI
• The deployment of the stack would asynchronously invoke the permissionSetAssignmentHandler and begin polling the permissionSetAssignmentIsCompleteHandler to check for completion status
• The permissionSetAssignmentHandler would process the input specified by the AWS Identity Center administrator via the Cloudformation template to assemble a list of AccountAssignmentCommandInput objects. Depending on the input the following API calls could be made;
  • DescribeOrganization - Use to get the AWS Organization managment account id
  • DescribeAccount - Looping over each account id specified in the input to get account information
  • ListOrganizationalUnitsForParent - Looping over each OU specified in the input to get accounts
  • ListInstances - Get the identity store
  • ListGroups - Get the groups specified in the input
  • ListUsers - Get the users specifeid in the input
  • ListPermissionSets - Get the permission sets specified in the input
• Once the AccountAssignmentCommandInput objects have been created the function invokes the assignPermissionSetsStateMachine
• The function then stores the step function's execution id associated with the stack's physical id in the AssignPermissionSetsTable. This data is used by the permissionSetAssignmentIsCompleteHandler to check the state machine's execution status.
• The function also stores account ids and/or OU ids associated with the stack in the AssignPermissionSetsTable. This data is used later by the ControlTowerLifeCycleEvent handler to rerun stacks associated with particular accounts and/or OUs that generated a Control Tower lifecycle event.

ControlTowerLifeCycleEventSourceRuleStack

This stack is meant to be deployed into the AWS organizations management account. The stack deploys two Amazon EventBridge rules that forward Control Tower lifecycle events, UpdateManagedAccount and CreateManagedAccount, to the ControlTowerLifeCycleEventBus deployed in the AWS IAM Identity Center delegated administration account.

Deployment

• Install dependencies

  npm install

• Deploy PermissionSetAssignmentCustomResourceStack to the AWS IAM Identity Center delegated administration account

  1. Set AWS environment credentials to the AWS IAM Identity Center delegated administration Account

  2. Run the following command:

     cdk deploy PermissionSetAssignmentCustomResourceStack -c managementAccountId=<AWS_MANAGEMENT_ACCOUNT_ID>

  3. Once the stack has deployed the ControlTowerLifeCycleEventBus arn will be display on the output, copy this value.

• Deploy ControlTowerLifeCycleEventSourceRuleStack to the AWS Organization management account

  1. Set AWS environment credentials to the AWS Organizations management account

  2. Run the following command:

     cdk deploy ControlTowerLifeCycleEventSourceRuleStack -c targetEventBusArn=<ControlTowerLifeCycleEventBus_ARN>

     

permission-set-assignment CloudFormation template

Permission set assignments are specified via CloudFormation stacks deployed to the AWS IAM Identity Center delegated administration account using the permission-set-assignment template.

The template takes the following parameters;

• Principals
  • Group names - A comma delimited list of identity store group names to apply the permission set(s) to for the specified targets (accounts/OUs)
  • User names - A comma delimited list of user names to apply the permission set(s) to for the specified targets (accounts/OUs)
• Targets
  • Organizational unit names - A comma delimited list of organizational unit names or ids. Nested OUs with non-unique names should be specified using either dot notation (A.B.C) or the OU id directly. You can also a special OU name 'root' or the root id (r-*) to refer to the root organizational unit. The permission sets will be applied to the specified principal(s) for all accounts in the specified organizational unit. In the case of 'root' this would be all accounts. The OU does not have to contain any accounts.
  • Account ids - A comma delimited list of account ids. The permission sets will be applied to the specified principals for all account ids
• Permission Sets
  • Permission set names - A comma delimited list of permission set names
• Other
  • ForceUpdate - Used by the solution to force a rerun of the CloudFormation stack on receipt of Control Tower lifecycle events. Any value which is unique compared to the previous run will work.

At a minimum you must specify at least one entry for Principals, one entry for Targets, and one entry for Permission Sets.

Security

See CONTRIBUTING for more information.

License

This library is licensed under the MIT-0 License. See the LICENSE file.

Examples

python-usage