Applying managed instance policy best practices
Since AWS Systems Manager was launched, the service has continued to add new features for customers to use. Many features are enabled by granting your Amazon EC2 instances and on-premises servers access to Systems Manager using an AWS Identity and Access Management (IAM) role with the necessary permissions. To provide customers more flexible, fine-grained permission control, AWS introduced the Managed Policy
AmazonSSMManagedInstanceCore. This policy grants instances the permissions needed for core Systems Manager functionality.
In order to take advantage of the new granular permissions model, the
AmazonEC2RoleforSSM policy should be replaced with
AmazonSSMManagedInstanceCore. To ensure we’re following best practices, the
AmazonEC2RoleforSSM policy will no longer be available for new resources. We’ll cover the specifics on this policy deprecation later on.
In this blog post:
- I review each of the IAM Managed Policies available for you to use with Systems Manager managed instances.
- Next, I show you which managed policies enable specific Systems Manager features, so you can allow the features you’re using while following a least privilege security best practice.
- Finally, I demonstrate how to plan for the deprecation of the
AmazonEC2RoleforSSMpolicy and how you can automatically remediate your existing IAM roles in AWS Config by replacing the policy.
AWS IAM managed policies for AWS Systems Manager
Systems Manager provides the following managed policies in IAM to use with Amazon EC2 Instances and on-premises servers. These policies grant permission to the required API actions to be registered as managed instances within the service, and to use additional service features:
|AmazonSSMManagedInstanceCore||This required trust policy enables an instance to use Systems Manager core service functionality. It provides minimum permissions which allow the instance to:
For more details on these API calls, refer to ec2messages, ssmmessages, and Other API Calls.
|AmazonSSMDirectoryServiceAccess||This instance trust policy enables a managed instance to seamlessly join a domain by providing access to the required AWS Directory Service API actions. For more details on this feature, refer to the Directory Service administration guide.|
|CloudWatchAgentServerPolicy||This policy enables the Amazon CloudWatch agent, by allowing access to read instance information and write it to CloudWatch Logs and Metrics. Permissions also grant access to read Amazon EC2 tags, volumes, and CloudWatch configuration parameters in Parameter Store. You can also create a more restrictive policy that, for example, limits writing access to a specific CloudWatch Logs log stream. For more details, refer to the CloudWatch user guide.|
|AmazonEC2RoleforSSM||This policy should be replaced by
To view the full details of each managed policy, navigate to the IAM Console, choose Policies in the navigation pane, and search for the policy name.
For a list of all AWS-provided managed policies for Systems Manager, refer to AWS Managed Policies for AWS Systems Manager.
Managed policy support for Systems Manager features
The following table details the managed policies required for core agent functionality (including registration to Systems Manager as a managed instance) and other common features.
|Core agent features||Session Manager||Seamless Domain Join||CloudWatch Agent||CloudWatch Logs Command Output||S3 Command Output 1||VSS Snap-shots 2|
|Custom policy required||✔|
|Custom policy required||✔|
1 A custom IAM policy is required when using your own Amazon S3 bucket with Systems Manager. For example, Run Command can save command output to an Amazon S3 bucket. For more information, refer to Create a Custom Policy for Amazon S3 Bucket Access.
2 In order to take VSS-enabled EBS snapshots, a custom policy is required to grant access to the needed Amazon EC2 service API calls.
Plan for replacing the AmazonEC2RoleforSSM policy
To help you through the transition of your existing environments, the
AmazonEC2RoleforSSM policy remains in place after the introduction of the new
In the near future, the
AmazonEC2RoleforSSM policy will be deprecated. The policy will continue to provide the included permissions to any currently attached users, groups, and roles. However, it will not be available for attachment to new resources and cannot be re-attached once detached from a resource. For more details, see Deprecated AWS Managed Policies.
To prepare for the deprecation of the
AmazonEC2RoleforSSM policy, we recommend the following transition plan:
- Phase 1: Define required policies
- Phase 2: Update policy references
- Phase 3: Update existing IAM entities
Phase 1: Define required policies
Confirm the managed policy or policies required for the Systems Manager features used in your environment, and create custom policies as required.
For example, to enable core agent functionality (such as Run Command and Session Manager), the
AmazonSSMManagedInstanceCore policy is sufficient. To enable CloudWatch Agent, you need to include the policy
If you plan to use your own Amazon S3 bucket in your System Manager operations—for example, to store Run Command output—a custom IAM policy is required to provide access. For steps to create a custom policy, refer to Create a Custom Policy for Amazon S3 Bucket Access.
For other agent features, refer to the Systems Manager user guide for any IAM permissions which may be required.
Phase 2: Update policy references
Update any references to the
AmazonEC2RoleforSSM policy used within your environment to refer to your new set of policies, for example:
- Amazon EC2 launch templates
- AWS CloudFormation templates or other automation code
It is important to update these references to prevent failed requests to attach the
AmazonEC2RoleforSSM policy or failed requests to launch resources with this policy attached.
Phase 3: Update existing IAM entities
Update any IAM entities (users, groups, and roles) which have the
AmazonEC2RoleforSSM policy attached by attaching your replacement policy or policies, and detaching
AmazonEC2RoleforSSM. Most commonly, this policy is attached to an IAM role associated with an instance profile.
One way you can update your IAM entities is using AWS Config, which allows you to audit your existing roles by checking if the
AmazonEC2RoleforSSM policy is attached. The managed rule IAM-policy-blacklisted-check allows you to mark any entities with this policy attached as noncompliant. Using the remediation feature with a custom Systems Manager automation document, you can automatically replace the
AmazonEC2RoleforSSM policy with a set of new policies.
In the next steps, I use an example AWS CloudFormation template to demonstrate how to deploy AWS Config and a custom remediation document.
For details on AWS Config pricing, refer to the AWS Config pricing page.
Auditing and remediating roles with AWS Config
You need the following prerequisites for auditing and remediating roles:
- Custom instance policies defined
- IAM permissions to launch a CloudFormation stack and create associated resources
- Example CloudFormation template
Step 1: Enable AWS Config
To get started, navigate to the AWS Config console and enable the service if needed.
To collect IAM entities, verify that Include global resources is enabled. If you are recording only specific resource types, ensure IAM:Role, IAM:User, and IAM:Group are being recorded. For more details about enabling AWS Config, refer to Setting Up AWS Config.
Step 2: Launch CloudFormation stack
Next, launch an AWS CloudFormation stack template to create the following resources:
- AWS Config rule to scan/remediate IAM roles for the
- AWS Config rule to scan IAM users and groups for the
- Systems Manager automation remediation document
- IAM automation service role used for remediation
- AWS Config remediation configuration
To launch the stack, take the following steps:
- Download the example CloudFormation template SSMManagedPolicyBestPractice.yaml located in GitHub.
- In the AWS CloudFormation console, select Stacks and choose Create Stack.
- In the Template source section, choose Upload a template file and specify the downloaded example template.
- Choose Next and enter a Stack Name.
- Specify your replacement IAM policies in the policiesToAdd parameter, using Amazon Resource Names (ARNs) in comma-separated format. Specified policies are attached to the noncompliant IAM role, replacing the policy specified in policyToRemove. The default limit is 10 managed policies attached to a role. For more details, see IAM Object Limits. The following AWS Managed Policies are specified by default:
arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore arn:aws:iam::aws:policy/AmazonSSMDirectoryServiceAccess arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy
- Leaving other parameters as default, choose Next and continue to the Review
- On the Review page, scroll to the end to acknowledge that IAM resources will be created, then choose Create stack.
- Review the stack details and verify the status changes to
CREATE_COMPLETE. For more details, refer to Creating a Stack on the AWS CloudFormation Console.
Step 3: Run AWS Config remediation
Now that the AWS Config rule and remediation document are created, you can remediate any noncompliant IAM roles.
Navigate back to the AWS Config console and choose Rules, as shown in the following screenshot. Note that it can take some time for your resources to be recorded by AWS Config.
Choose the rule
Iam-Roles-Deprecated-AmazonEC2RoleforSSM to review any IAM roles marked Noncompliant, as shown in the following screenshot.
In the example shown in the screenshot, I have one IAM role with the
AmazonEC2RoleforSSM policy attached marked Noncompliant, which can be manually remediated by selecting the role and choosing Remediate.
Note that the resource must be re-scanned by the AWS Config rule to be updated as Compliant, as shown in the following screenshot.
You can review details about the remediation actions performed in the Systems Manager automations console.
You should also review any resources marked Noncompliant in the separate
Iam-UsersGroups-Deprecated-AmazonEC2RoleforSSM AWS Config rule. Since the
AmazonEC2RoleforSSM policy is intended for use in instance profile roles, any IAM users or groups with this policy attached should be carefully reviewed to assign the intended permissions.
In this blog post, I covered the AWS IAM managed policies recommended for use with managed instances and how they enable features in Systems Manager. I also provided recommended steps you can take to transition from the
AmazonEC2RoleforSSM policy, along with an example solution using AWS Config to remediate your current IAM roles.
To expand on the example solution, you can also consider enabling AWS Config to automatically remediate any detected noncompliant roles, or deploying this solution across multiple AWS accounts using AWS CloudFormation StackSets. For more information, see Setting Up Auto Remediation and Working with AWS CloudFormation StackSets.
About the authors
Adam Creech is a Cloud Support Engineer in AWS Premium Support. He specializes in AWS Systems Manager and Amazon EC2 Windows. In his personal time, he enjoys reading and playing the piano.
Vladimir Drozdenko is a Senior Software Engineer with AWS Systems Manager. He is passionate about building secure and effective solutions for AWS customers. Outside of work, he is a martial art enthusiast and a coffee junky.