IAM roles and permissions for Quick Setup onboarding Manual onboarding for working with Quick Setup API programatically

Getting started with Quick Setup

Use the information in this topic to help you prepare to use Quick Setup.

Topics

IAM roles and permissions for Quick Setup onboarding
Manual onboarding for working with Quick Setup API programatically

IAM roles and permissions for Quick Setup onboarding

Quick Setup launched a new console experience and a new API. Now you can interact with this API using the console, AWS CLI, AWS CloudFormation, and SDKs. If you opt in to the new experience, your existing configurations are recreated using the new API. Depending on the number of existing configurations in your account, this process can take several minutes.

To use the new Quick Setup console, you must have permissions for the following actions:


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ssm-quicksetup:*",
                "cloudformation:DescribeStackSetOperation",
                "cloudformation:ListStacks",
                "cloudformation:DescribeStacks",
                "cloudformation:DescribeStackResources",
                "cloudformation:ListStackSetOperations",
                "cloudformation:ListStackInstances",
                "cloudformation:DescribeStackSet",
                "cloudformation:ListStackSets",
                "cloudformation:DescribeStackInstance",
                "cloudformation:DescribeOrganizationsAccess",
                "cloudformation:ActivateOrganizationsAccess",
                "cloudformation:GetTemplate",
                "cloudformation:ListStackSetOperationResults",
                "cloudformation:DescribeStackEvents",
                "cloudformation:UntagResource",
                "ec2:DescribeInstances",
                "ssm:DescribeAutomationExecutions",
                "ssm:GetAutomationExecution",
                "ssm:ListAssociations",
                "ssm:DescribeAssociation",
                "ssm:GetDocument",
                "ssm:ListDocuments",
                "ssm:DescribeDocument",
                "ssm:ListResourceDataSync",
                "ssm:DescribePatchBaselines",
                "ssm:GetPatchBaseline",
                "ssm:DescribeMaintenanceWindows",
                "ssm:DescribeMaintenanceWindowTasks",
                "ssm:GetOpsSummary",
                "organizations:DeregisterDelegatedAdministrator",
                "organizations:DescribeAccount",
                "organizations:DescribeOrganization",
                "organizations:ListDelegatedAdministrators",
                "organizations:ListRoots",
                "organizations:ListParents",
                "organizations:ListOrganizationalUnitsForParent",
                "organizations:DescribeOrganizationalUnit",
                "organizations:ListAWSServiceAccessForOrganization",
                "s3:GetBucketLocation",
                "s3:ListAllMyBuckets",
                "s3:ListBucket",
                "resource-groups:ListGroups",
                "iam:ListRoles",
                "iam:ListRolePolicies",
                "iam:GetRole",
                "iam:CreatePolicy",
                "organizations:RegisterDelegatedAdministrator",
                "organizations:EnableAWSServiceAccess",
                "cloudformation:TagResource"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "cloudformation:RollbackStack",
                "cloudformation:CreateStack",
                "cloudformation:UpdateStack",
                "cloudformation:DeleteStack"
            ],
            "Resource": [
                "arn:aws:cloudformation:*:*:stack/StackSet-AWS-QuickSetup-*",
                "arn:aws:cloudformation:*:*:stack/AWS-QuickSetup-*",
                "arn:aws:cloudformation:*:*:type/resource/*",
                "arn:aws:cloudformation:*:*:stack/StackSet-SSMQuickSetup"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "cloudformation:CreateStackSet",
                "cloudformation:UpdateStackSet",
                "cloudformation:DeleteStackSet",
                "cloudformation:DeleteStackInstances",
                "cloudformation:CreateStackInstances",
                "cloudformation:StopStackSetOperation"
            ],
            "Resource": [
                "arn:aws:cloudformation:*:*:stackset/AWS-QuickSetup-*",
                "arn:aws:cloudformation:*:*:stackset/SSMQuickSetup",
                "arn:aws:cloudformation:*:*:type/resource/*",
                "arn:aws:cloudformation:*:*:stackset-target/AWS-QuickSetup-*:*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "iam:CreateRole",
                "iam:DeleteRole",
                "iam:AttachRolePolicy",
                "iam:DetachRolePolicy",
                "iam:GetRolePolicy",
                "iam:PassRole",
                "iam:PutRolePolicy"
            ],
            "Resource": [
                "arn:aws:iam::*:role/AWS-QuickSetup-*",
                "arn:aws:iam::*:role/service-role/AWS-QuickSetup-*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "ssm:DeleteAssociation",
                "ssm:CreateAssociation",
                "ssm:StartAssociationsOnce"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": "ssm:StartAutomationExecution",
            "Resource": "arn:aws:ssm:*:*:automation-definition/AWS-EnableExplorer:*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "ssm:GetOpsSummary",
                "ssm:CreateResourceDataSync",
                "ssm:UpdateResourceDataSync"
            ],
            "Resource": "arn:aws:ssm:*:*:resource-data-sync/AWS-QuickSetup-*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "iam:CreateServiceLinkedRole"
            ],
            "Condition": {
                "StringEquals": {
                    "iam:AWSServiceName": [
                        "accountdiscovery.ssm.amazonaws.com",
                        "ssm.amazonaws.com",
                        "ssm-quicksetup.amazonaws.com",
                        "stacksets.cloudformation.amazonaws.com"
                    ]
                }
            },
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "iam:CreateServiceLinkedRole"
            ],
            "Resource": "arn:aws:iam::*:role/aws-service-role/stacksets.cloudformation.amazonaws.com/AWSServiceRoleForCloudFormationStackSetsOrgAdmin"
        }
    ]
}

To restrict users to read-only permissions, only allow ssm-quicksetup:List* and ssm-quicksetup:Get* operations for the Quick Setup API.

During onboarding, Quick Setup creates the following AWS Identity and Access Management (IAM) roles on your behalf:

AWS-QuickSetup-LocalExecutionRole – Grants AWS CloudFormation permissions to use any template, excluding the patch policy template, and create the necessary resources.
AWS-QuickSetup-LocalAdministrationRole – Grants permissions to AWS CloudFormation to assume AWS-QuickSetup-LocalExecutionRole.
AWS-QuickSetup-PatchPolicy-LocalExecutionRole – Grants permissions to AWS CloudFormation to use the patch policy template, and create the necessary resources.
AWS-QuickSetup-PatchPolicy-LocalAdministrationRole – Grants permissions to AWS CloudFormation to assume AWS-QuickSetup-PatchPolicy-LocalExecutionRole.

If you're onboarding a management account—the account that you use to create an organization in AWS Organizations—Quick Setup also creates the following roles on your behalf:

AWS-QuickSetup-SSM-RoleForEnablingExplorer – Grants permissions to the AWS-EnableExplorer automation runbook. The AWS-EnableExplorer runbook configures Explorer, a capability of Systems Manager, to display information for multiple AWS accounts and AWS Regions.
AWSServiceRoleForAmazonSSM – A service-linked role that grants access to AWS resources managed and used by Systems Manager.
AWSServiceRoleForAmazonSSM_AccountDiscovery – A service-linked role that grants permissions to Systems Manager to call AWS services to discover AWS account information when synchronizing data. For more information, see Using roles to collect AWS account information for OpsCenter and Explorer.

When onboarding a management account, Quick Setup enables trusted access between AWS Organizations and CloudFormation to deploy Quick Setup configurations across your organization. To enable trusted access, your management account must have administrator permissions. After onboarding, you no longer need administrator permissions. For more information, see Enable trusted access with Organizations.

For information about AWS Organizations account types, see AWS Organizations terminology and concepts in the AWS Organizations User Guide.

Note

Quick Setup uses AWS CloudFormation StackSets to deploy your configurations across AWS accounts and Regions. If the number of target accounts multiplied by the number of Regions exceeds 10,000, the configuration fails to deploy. We recommend reviewing your use case and creating configurations that use fewer targets to accommodate the growth of your organization. Stack instances aren't deployed to your organization's management account. For more information, see Considerations when creating a stack set with service-managed permissions.

Manual onboarding for working with Quick Setup API programatically

If you use the console to work with Quick Setup, the service handles onboarding steps for you. If you plan to use SDKs or the AWS CLI to work with the Quick Setup API, you can still use the console to complete onboarding steps for you so you don't have to perform them manually. However, some customers need to complete onboarding steps for Quick Setup programmatically without interacting with the console. If this method fits your use case, you must complete the following steps. All of these steps must be completed from your AWS Organizations management account.

To complete manual onboarding for Quick Setup

Activate trusted access for AWS CloudFormation with Organizations. This provides the management account with the permissions needed to create and manage StackSets for your organization. You can use AWS CloudFormation's ActivateOrganizationsAccess API action to complete this step. For more information, see ActivateOrganizationsAccess in the AWS CloudFormation API Reference.
Enable the integration of Systems Manager with Organizations. This allows Systems Manager to create a service-linked role in all the accounts in your organization. This also allows Systems Manager to perform operations on your behalf in your organization and its accounts. You can use AWS Organizations's EnableAWSServiceAccess API action to complete this step. The service principal for Systems Manager is ssm.amazonaws.com.rproxy.goskope.com.For more information, see EnableAWSServiceAccess in the AWS Organizations API Reference.

Create the required IAM role for Explorer. This allows Quick Setup to create dashboards for your configurations so you can view deployment and association statuses. Create an IAM role and attach the AWSSystemsManagerEnableExplorerExecutionPolicy managed policy. Modify the trust policy for the role to match the following. Replace each account ID with your information.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "ssm.amazonaws.com"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "account ID"
                },
                "ArnLike": {
                    "aws:SourceArn": "arn:*:ssm:*:account ID:automation-execution/*"
                }
            }
        }
    ]
}

Update the Quick Setup service setting for Explorer. You can use Quick Setup's UpdateServiceSettings API action to complete this step. Specify the ARN for the IAM role you created in the previous step for the ExplorerEnablingRoleArn request parameter. For more information, see UpdateServiceSettings in the Quick Setup API Reference.

Create the required IAM roles for AWS CloudFormation StackSets to use. You must create an execution role and an administration role.

Create the execution role. The execution role should have at least one of the AWSQuickSetupDeploymentRolePolicy or AWSQuickSetupPatchPolicyDeploymentRolePolicy managed policies attached. If you're only creating patch policy configurations, you can use AWSQuickSetupPatchPolicyDeploymentRolePolicy managed policy. All other configurations use the AWSQuickSetupDeploymentRolePolicy policy. Modify the trust policy for the role to match the following. Replace each account ID and administration role name with your information.
```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::account ID:role/administration role name"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}
```

Create the administration role. The permissions policy must match the following. Replace each account ID and execution role name with your information.


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

Modify the trust policy for the role to match the following. Replace each account ID with your information.


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

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

Quick Setup

Using a delegated administrator for Quick Setup