What are some of the IAM best practices for using stack set to deploy AWS CloudFormation resources?

Resolution

Identify the error that you received. Then, follow the steps in the related section below to resolve the error.
Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshoot AWS CLI errors. Also, make sure that you're using the most recent AWS CLI version.

Most common IAM permission errors in stack set

Error: "Account 111111111111 should have 'AWSCloudFormationStackSetExecutionRole' role with trust relationship to Role 'AWSCloudFormationStackSetAdministrationRole'."

This error usually occurs when the IAM role AWSCloudFormationStackSetExecutionRole or AWSCloudFormationStackSetAdministrationRole is missing. It also occurs when the trust relationship between the administrator and target account isn't established correctly.

Complete the following steps to resolve the error:

1. Verify that the IAM roles AWSCloudFormationStackSetExecutionRole and AWSCloudFormationStackSetAdministrationRole exist in your administrator account. Make sure that the roles are correctly named. For example, the administration role must be AWSCloudFormationStackSetExecutionRole. The role in each of your target accounts must be named AWSCloudFormationStackSetExecutionRole.
   Note: You can also set up basic IAM permissions for stack sets using the following AWS CloudFormation templates:

   • AWSCloudFormationStackSetAdministrationRole.yml
   • AWSCloudFormationStackSetExecutionRole.yml

2. If the IAM roles exist, then verify that there's a trust relationship between the roles.

   Review the following example code snippets that activate the basic trust relationship between IAM roles.

   AWSCloudFormationStackSetAdministrationRole trust relationship:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": {
           "Service": "cloudformation.amazonaws.com"
         },
         "Action": "sts:AssumeRole"
       }
     ]
   }

   AWSCloudFormationStackSetAdministrationRole inline policy:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Action": [
           "sts:AssumeRole"
         ],
         "Resource": [
           "arn:*:iam::*:role/AWSCloudFormationStackSetExecutionRole"
         ],
         "Effect": "Allow"
       }
     ]
   }

   AWSCloudFormationStackSetExecutionRole trust relationship section:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": {
           "AWS": "arn:aws:iam::admin_account_id:root"
         },
         "Action": "sts:AssumeRole"
       }
     ]
   }

Error : "Resource handler returned message: "Account used is not a delegated administrator (Service: CloudFormation, Status Code: 400, Request ID: xxxxxx-xxxx-xxxx-xxxx-xxxxxxxx)" (RequestToken:xxxxx-xxx-xxxxx, HandlerErrorCode: InvalidRequest)" when deploying StackSet using CloudFormation resource type "AWS::CloudFormation::StackSet"

-or-

Error (AWS CLI): "An error occurred (ValidationError) when calling the ListStackSets operation: Account used is not a delegated administrator"

These errors indicate that the AWS account used for stack set deployment isn't registered as a delegated administrator. Or, the errors occur because the IAM role doesn't have the required permissions. Your organization can have up to five registered delegated administrators at one time. Delegated administrators can choose to deploy to all accounts in your organization or to specific Organization units (OUs).

To resolve the error, complete the following steps:

1. Verify that the account is registered as a delegated administrator account with the following AWS CLI command:

   aws organizations list-delegated-administrators \
     --service-principal=member.org.stacksets.cloudformation.amazonaws.com

2. If the account isn't registered as a delegated administrator, register it. Or, use the following AWS CLI command to register the delegated administrator:

   aws organizations register-delegated-administrator \
     --service-principal=member.org.stacksets.cloudformation.amazonaws.com \
     --account-id="memberAccountId"

   Note: Replace memberAccountId with your AWS account ID.

3. If the account is a delegated administrator, then verify the following IAM permission for your IAM role:

   organizations:ListDelegatedAdministrators
   cloudformation:TagResource
   cloudformation:CreateStackSet

   Note: Delegated administrators have full permissions to deploy to accounts in your organization. The management account can't limit delegated administrator permissions to deploy to specific OUs or to perform specific stack set operations.

Error: "ResourceStatusReason:Invalid principal in policy: "AWS":"arn:aws:iam::111111111111:role/myDeploymentRole" (Service: AmazonIdentityManagement; Status Code: 400; Error Code: MalformedPolicyDocument; Request ID: xxxxxx-xxxx-xxxx-xxxx-xxxxxx; Proxy: null)"

This error message indicates that the value of a Principal element in your IAM trust policy isn't correct. For more information on resolving this error, see How can I resolve the IAM trust policy error "Failed to update trust policy. Invalid principal in policy"?

Error: "ResourceLogicalId:myDeploymentRole, ResourceType:AWS::IAM::Role, ResourceStatusReason:myDeploymentRole already exist"

Error: "ResourceLogicalId:myDeploymentRolePolicy, ResourceType:AWS::IAM::ManagedPolicy, ResourceStatusReason:myDeploymentRolePolicy already exist"

These errors occur because AWS IAM is a globally available service and not a Regional service. AWS services process and store content in the AWS Regions for Regional services. Because IAM is a global service, when you create an IAM role or policy in one Region, you can use that role or policy in all the Regions.

Resolve this error by defining the condition in your CloudFormation stack set template, as listed below. When you specify the Regional condition, the stack deploys the IAM resources in only one Region (us-east-1). When completed, the operation successfully updated all the stack accounts in the Region.

The YAML template snippet below shows how to deploy IAM resources to only the us-east-1 Region:

AWSTemplateFormatVersion: "2010-09-09"
Conditions:
  RoleCreate: !Equals
    - !Ref AWS::Region
    - us-east-1

Resources:
  myIAMRole:
    Type: 'AWS::IAM::Role'
    Condition: RoleCreate
    Properties:
      RoleName: 'TestingIAMRole2'
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Principal:
              Service:
                - ec2.amazonaws.com
            Action:
              - 'sts:AssumeRole'