Self-managed permissions Set up basic permissions for stack set operations Set up advanced permissions options for stack set operations Confused deputy prevention

Grant self-managed permissions

With self-managed permissions, you create the AWS Identity and Access Management (IAM) roles required by StackSets to deploy across accounts and AWS Regions. These roles are necessary to establish a trusted relationship between the account you're administering the stack set from and the account you're deploying stack instances to. Using this permissions model, StackSets can deploy to any AWS account in which you have permissions to create an IAM role.

Topics

Self-managed permissions
Set up basic permissions for stack set operations
Set up advanced permissions options for stack set operations
Set up global keys to mitigate confused deputy problems

Self-managed permissions

To set up the required permissions for creating a service-managed stack set, see Enable trusted access with AWS Organizations.

Before you create a stack set with self-managed permissions, you need to establish a trust relationship between the administrator and target accounts by creating IAM roles in each account.

Determine which AWS account is the administrator account.

Stack sets are created in this administrator account. A target account is the account in which you create individual stacks that belong to a stack set.
Determine how you want to structure permissions for the stack sets.

The simplest (and most permissive) permissions configuration is where you give all users and groups in the administrator account the ability to create and update all the stack sets managed through that account. If you need finer-grained control, you can set up permissions to specify:
- Which users and groups can perform stack set operations in which target accounts.
- Which resources users and groups can include in their stack sets.
- Which stack set operations specific users and groups can perform.
Create the necessary IAM service roles in your administrator and target accounts to define the permissions you want.

Important
The role in your administrator account should be named AWSCloudFormationStackSetAdministrationRole. The role in each of your target accounts should be named AWSCloudFormationStackSetExecutionRole.

Set up basic permissions for stack set operations

The simplest (and most permissive) permissions configuration is where you give all users and groups in the administrator account the ability to create and update all the stack sets managed through that account. To do this, you create IAM service roles for your administrator and all target accounts. Anyone with permissions to the administrator account then has permissions to create, update, or delete any stacks in any of the target accounts.

Your administrator account and target accounts must have service roles configured that create a trust relationship between the accounts, and grant the target accounts permission to create and manage the resources described in your template.

If you structure your permissions this way, users don't pass an administrator role when creating or updating stack sets.

Set up a trust relationship between the administrator account and the
target accounts. Any user in the administrator account can then create any
stack set.

Set up permissions for all users of the administrator account to perform stack set operations in all target accounts

In the administrator account, create an IAM role named AWSCloudFormationStackSetAdministrationRole. The role must have this exact name. You can do this by creating a stack from the following AWS CloudFormation template, available online at https://s3.amazonaws.com/cloudformation-stackset-sample-templates-us-east-1/AWSCloudFormationStackSetAdministrationRole.yml. The role created by this template enables the following policy on your administrator account.
```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "sts:AssumeRole"
            ],
            "Resource": [
                "arn:aws:iam::*:role/AWSCloudFormationStackSetExecutionRole"
            ],
            "Effect": "Allow"
        }
    ]
}
```
The following trust relationship is created by the preceding template.
```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "cloudformation.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
```
Be aware that to deploy stack instances into a target account that resides in a Region that's disabled by default, you will also need to include the regional service principal for that Region. Each Region that's disabled by default will have its own regional service principal.

For more information on regional endpoints, including a list of endpoints, see Regional endpoints in the AWS General Reference Guide.

The following example includes the regional service principal (cloudformation.ap-east-1.amazonaws.com) for the Asia Pacific (Hong Kong) Region, a Region which is disabled by default.
```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": [
            "cloudformation.amazonaws.com",
            "cloudformation.ap-east-1.amazonaws.com"
         ]
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
```
For more information, see Prerequisites for stack set operations.
In each target account, create a service role named AWSCloudFormationStackSetExecutionRole that trusts the administrator account. The role must have this exact name. You can do this by creating a stack from the following AWS CloudFormation template, available online at https://s3.amazonaws.com/cloudformation-stackset-sample-templates-us-east-1/AWSCloudFormationStackSetExecutionRole.yml. When you use this template, you are prompted to provide the name of the administrator account with which your target account must have a trust relationship.

Important
Be aware that this template grants administrator access. After you use the template to create a target account execution role, you must scope the permissions in the policy statement to the types of resources that you are creating by using StackSets.

The target account service role requires permissions to perform any operations that are specified in your AWS CloudFormation template. For example, if your template is creating an S3 bucket, then you need permissions to create new objects for S3. Your target account always needs full AWS CloudFormation permissions, which include permissions to create, update, delete, and describe stacks. The role created by this template enables the following policy on a target account.
```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "*",
            "Resource": "*"
        }
    ]
}
```
You must add the S3 service action and resources to AWSCloudFormationStackSetExecutionRole policy statement for each target account for StackSets to work. StackSets uses these permissions to notify the stack instance state in the target accounts and in the administrator account.

To create stacks in target accounts that use resources from services other than CloudFormation, you must add those service actions and resources to the AWSCloudFormationStackSetExecutionRole policy statement for each target account. The following example shows a policy statement with the required permissions for StackSets.
```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": 
               [
                 "cloudformation:*",
                 "s3:*"
               ],
            "Resource": "*"
        }
      ]
}
```
The following trust relationship is created by the template. The administrator account's ID is shown as admin_account_id.
```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::admin_account_id:root"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
```
You can configure the trust relationship of an existing target account execution role to trust a specific role in the administrator account. If you delete the role in the administrator account, and create a new one to replace it, you must configure your target account trust relationships with the new administrator account role, represented by admin_account_id in the preceding example.

Set up advanced permissions options for stack set operations

If you require finer-grained control over the stack sets that users and groups are creating through a single administrator account, you can use IAM roles to specify:

Which users and groups can perform stack set operations in which target accounts.
Which resources users and groups can include in their stack sets.
Which stack set operations specific users and groups can perform.

Set up permissions to control target account access

Use customized administrator roles to control which users and groups can perform stack set operations in which target accounts. You might want to control which users of the administrator account can perform stack set operations in which target accounts. To do this, you create a trust relationship between each target account and a specific customized administration role, rather than creating the AWSCloudFormationStackSetAdministrationRole service role in the administrator account itself. You then activate specific users and groups to use the customized administration role when performing stack set operations in a specific target account.

For example, you can create Role A and Role B within your administrator account. You can give Role A permissions to access target account 1 through account 8. You can give Role B permissions to access target account 9 through account 16.

Set up a trust relationship between a customized administrator role
and the target accounts. The user then passes that role when creating
the stack set.

Setting up the necessary permissions involves defining a customized administrator role, creating a service role for the target account, and granting users permission to pass the customized administrator role when performing stack set operations.

In general, here's how it works once you have the necessary permissions in place: When creating a stack set, the user must specify a customized administrator. The user must have permission to pass the role to AWS CloudFormation. In addition, the customized administrator role must have a trust relationship with the target accounts specified for the stack set. AWS CloudFormation creates the stack set and associates the customized administrator role with it. When updating a stack set, the user must explicitly specify a customized administrator role, even if it's the same customized administrator role used with this stack set previously. AWS CloudFormation uses that role to update the stack, subject to the requirements above.

Set up permissions for which users and groups can perform stack set operations in specific target accounts

For each stack set, create a customized administrator role with permissions to assume the AWSCloudFormationStackSetExecutionRole service role in the target accounts.

Create an IAM service role with a custom name, using the following permissions policy:
```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "sts:AssumeRole"
            ],
            "Resource": [
                "arn:aws:iam::target_account_id:role/AWSCloudFormationStackSetExecutionRole"
            ],
            "Effect": "Allow"
        }
    ]
}
```
Or, if you want to specify all target accounts, use the following permissions policy:
```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "sts:AssumeRole"
            ],
            "Resource": [
                "arn:aws:iam::*:role/AWSCloudFormationStackSetExecutionRole"
            ],
            "Effect": "Allow"
        }
    ]
}
```
You must provide the following trust policy when you create the role to define the trust relationship:
```
{ 
  "Version": "2012-10-17", 
  "Statement": [ 
    { 
      "Effect": "Allow", 
      "Principal": { 
        "Service": "cloudformation.amazonaws.com" 
      }, 
      "Action": "sts:AssumeRole" 
    } 
  ] 
}
```
Be aware that to deploy stack instances into a target account that resides in a Region that's disabled by default, you will also need to include the regional service principal for that Region. Each Region that's unavailable by default will have its own regional service principal.

For more information on regional endpoints, including a list of endpoints, see Regional endpoints in the AWS General Reference Guide.

The following example includes the regional service principal (cloudformation.ap-east-1.amazonaws.com) for the Asia Pacific (Hong Kong) Region, a Region which is disabled by default.
```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": [
            "cloudformation.amazonaws.com",
            "cloudformation.ap-east-1.amazonaws.com"
         ]
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
```
For more information, see Prerequisites for stack set operations.
In each target account, create a service role named AWSCloudFormationStackSetExecutionRole that trusts the customized administration role you want to use with this account.

Important
You must scope the permissions in the policy statement to the types of resources that you are creating by using StackSets.

The target account service role requires permissions to perform any operations that are specified in your AWS CloudFormation template. For example, if your template is creating an S3 bucket, then you need permissions to create new objects in S3. Your target account always needs full AWS CloudFormation permissions, which include permissions to create, update, delete, and describe stacks.

The following example shows a policy statement with the minimum permissions for StackSets to work. To create stacks in target accounts that use resources from services other than AWS CloudFormation, you must add those service actions and resources to the AWSCloudFormationStackSetExecutionRole permissions policy statement for each target account.
```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": 
               [
                 "cloudformation:*",
                 "s3:*"
               ],
            "Resource": "*"
        }
      ]
}
```
You must provide the following trust policy when you create the role to define the trust relationship:
```
{
  "Version": "2012-10-17", 
  "Statement": [ 
    { 
      "Effect": "Allow", 
      "Principal": { 
      "AWS": "arn:aws:iam::admin_account_id:role/customized_admin_role" 
      }, 
      "Action": "sts:AssumeRole"
    } 
  ] 
} 
```
Allow users to pass the customized administrator role when performing stack set operations.

Attach an IAM permissions policy to users or groups that allows them to pass the appropriate customized administrator role when creating or updating specific stack sets. For more information, see Granting a user permissions to pass a role to an AWS service. In the example below, customized_admin_role refers to the administrator role the user needs to pass.
```
{
    "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Allow",
        "Action": [
            "iam:GetRole",
            "iam:PassRole"
        ],
        "Resource": "arn:aws:iam::*:role/customized_admin_role"
    }]
}
```

Set up permissions to control stack resource inclusion

Use customized execution roles to control which stack resources users and groups can include in their stack sets. For example, you might want to set up a group that can only include Amazon S3-related resources in the stack sets they create, while another team can only include DynamoDB resources. To do this, you create a trust relationship between the customized administrator role for each group and a customized execution role for each set of resources. The customized execution role defines which stack resources can be included in stack sets. The customized administrator role resides in the administrator account, while the customized execution role resides in each target account in which you want to create stack sets using the defined resources. You then activate specific users and groups to use the customized administration role when performing stack set operations.

For example you can create customized administrator roles A, B, and C in the administrator account. Users and groups with permission to use Role A can create stack sets containing the stack resources specifically listed in customized execution role X, but not those in roles Y or Z, or resource not included in any execution role.

Set up a trust relationship between a customized administrator role
and a customized execution role in the target accounts. The user then
passes those roles when creating the stack set.

When updating a stack set, the user must explicitly specify a customized administrator role, even if it's the same customized administrator role used with this stack set previously. AWS CloudFormation performs the update using the customized administrator role specified, so long as the user has permissions to perform operations on that stack set.

Similarly, the user can also specify a customized execution role. If they specify a customized execution role, AWS CloudFormation uses that role to update the stack, subject to the requirements above. If the user doesn't specify a customized execution role, AWS CloudFormation performs the update using the customized execution role previously associated with the stack set, so long as the user has permissions to perform operations on that stack set.

Set up permissions for which resources users and groups can include in specific stack sets

In the target accounts in which you want to create your stack sets, create a customized execution role that grants permissions to the services and resources that you want users and groups to be able to include in the stack sets.

The following example provides the minimum permissions for stack sets, along with permission to create Amazon DynamoDB tables.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action":
               [
                 "cloudformation:*",
                 "s3:*",
               ],
            "Resource": "*"
        },
  {
            "Effect": "Allow",
            "Action":
               [
                 "dynamoDb:createTable"
  ],
            "Resource": "*"
        }
    ]
}

You must provide the following trust policy when you create the role to define the trust relationship:


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

Create a customized administrator role in your administrator account, as detailed in Set up advanced permissions options for stack set operations Set up permissions to control target account access Set up permissions for which users and groups can perform stack set operations in specific target accounts. Include a trust relationship between the customized administrator role and the customized execution roles which you want it to use.

The following example includes an sts::AssumeRole policy for both the AWSCloudFormationStackSetExecutionRole defined for the target account, in addition to a customized execution role.


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

Set up permissions for specific stack set operations

In addition, you can set up permissions for which user and groups can perform specific stack set operations, such as creating, updating, or deleting stack sets or stack instances. For more information, see Actions, resources, and condition keys for AWS CloudFormation in the IAM User Guide.

Set up global keys to mitigate confused deputy problems

The confused deputy problem is a security issue where an entity that doesn't have permission to perform an action can coerce a more-privileged entity to perform the action. In AWS, cross-service impersonation can result in the confused deputy problem. Cross-service impersonation can occur when one service (the calling service) calls another service (the called service). The calling service can be manipulated to use its permissions to act on another customer's resources in a way it shouldn't otherwise have permission to access. To prevent this, AWS provides tools that help you protect your data for all services with service principals that have been given access to resources in your account.

We recommend using the aws:SourceArn and aws:SourceAccount global condition context keys in resource policies to limit the permissions that AWS CloudFormation StackSets gives another service to the resource. If you use both global condition context keys, the aws:SourceAccount value and the account in the aws:SourceArn value must use the same account ID when used in the same policy statement.

The most effective way to protect against the confused deputy problem is to use the aws:SourceArn global condition context key with the full ARN of the resource. If you don't know the full ARN of the resource or if you are specifying multiple resources, use the aws:SourceArn global context condition key with wildcards (*) for the unknown portions of the ARN. For example, arn:aws:cloudformation::123456789012:*. Whenever possible, use aws:SourceArn, because it's more specific. Use aws:SourceAccount only when you can't determine the correct ARN or ARN pattern.

When StackSets assumes the Administration role in your administrator account, StackSets populates your administrator account ID and StackSets Amazon Resource Name (ARN). Therefore, you can define conditions for global keys aws:SourceAccount and aws:SourceArn in the trust relationships to prevent confused deputy problems. The following example shows how you can use the aws:SourceArn and aws:SourceAccount global condition context keys in StackSets to prevent the confused deputy problem.

Example Global keys for `aws:SourceAccount` and `aws:SourceArn`

When using StackSets, define the global keys aws:SourceAccount and aws:SourceArn in your AWSCloudFormationStackSetAdministrationRole trust policy to prevent confused deputy problems.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "cloudformation.amazonaws.com"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "111122223333"
                },
                "StringLike": {
                    "aws:SourceArn": "arn:aws:cloudformation:*:111122223333:stackset/*"
                }
            }
        }
    ]
}

Example StackSets ARNs

Specify your associated StackSets ARNs for finer control.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "cloudformation.amazonaws.com"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "111122223333",
                    "aws:SourceArn": [
                        "arn:aws:cloudformation:STACKSETS-REGION:111122223333:stackset/STACK-SET-ID-1",
                        "arn:aws:cloudformation:STACKSETS-REGION:111122223333:stackset/STACK-SET-ID-2",
                     ]
                }
            }
        }
    ]
}

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Prerequisites for stack set operations

Enable trusted access with AWS Organizations