AWS systems-manager: Recommend AWS RAM for sharing SSM documents; add migration guidance
Summary
Rewrites the SSM document sharing guide to recommend AWS Resource Access Manager (AWS RAM) over the ModifyDocumentPermission API, adds AWS RAM console/CLI sharing procedures, documents the AWS-MigrateSSMDocumentSharingToRAM runbook, and moves account-permission (private/public) sharing into its own section with its limitations.
Security assessment
The change documents access-control best practices for sharing SSM documents, steering users toward AWS RAM resource shares with resource-based policies and organization/OU scoping instead of broad account-ID or public sharing. It also notes AWS RAM supports private sharing only and that migrated documents reject ModifyDocumentPermission/DescribeDocumentPermission calls, which is security-relevant authorization guidance but not tied to a specific vulnerability or incident.
Evidence
+For new document sharing, we recommend using AWS Resource Access Manager (AWS RAM) instead of the `ModifyDocumentPermission` API operation.
Diff
diff --git a/systems-manager/latest/userguide/documents-ssm-sharing.md b/systems-manager/latest/userguide/documents-ssm-sharing.md index 9ad7c5331..f89c1b830 100644 --- a//systems-manager/latest/userguide/documents-ssm-sharing.md +++ b//systems-manager/latest/userguide/documents-ssm-sharing.md @@ -7 +7 @@ -Best practices for shared SSM documentsBlock public sharing for SSM documentsShare an SSM documentModify permissions for a shared SSM documentUsing shared SSM documents +Best practices for shared SSM documentsBlock public sharing for SSM documentsShare an SSM document using AWS RAMShare an SSM document using account permissionsUsing shared SSM documents @@ -11 +11,7 @@ Best practices for shared SSM documentsBlock public sharing for SSM documentsSha -You can share AWS Systems Manager (SSM) documents privately or publicly with accounts in the same AWS Region. To privately share a document, you modify the document permissions and allow specific individuals to access it according to their AWS account ID. To publicly share an SSM document, you modify the document permissions and specify `All`. Documents can't be simultaneously shared publicly and privately. +You can share AWS Systems Manager (SSM) documents with other accounts in the same AWS Region in two ways. For new document sharing, we recommend using AWS Resource Access Manager (AWS RAM). With AWS RAM, you can share a document with an entire organization or organizational unit (OU) in AWS Organizations, or with individual AWS accounts. You can also manage all of your shares from the AWS RAM console. For more information, see Share an SSM document using AWS RAM. + +You can also share a document by using account permissions, the original sharing mechanism. With account permissions, you modify the document permissions directly to share a document privately with specific AWS account IDs, or publicly with everyone. Account-permission sharing remains supported. For more information, see Share an SSM document using account permissions. + +If you already share documents by using account permissions, you can migrate those shares to AWS RAM. For more information, see Migrate an existing shared document to AWS RAM. + +You can't share a document publicly and privately at the same time. You also can't use AWS RAM sharing and account-permission (`ModifyDocumentPermission`) sharing on the same document at the same time. @@ -23,6 +28,0 @@ As you begin working with SSM documents, be aware of the following limitations. - * You must stop sharing a document before you can delete it. For more information, see Modify permissions for a shared SSM document. - - * You can share a document with a maximum of 1000 AWS accounts. You can request an increase to this limit in the [Support Center](https://console.aws.amazon.com/support/home#/case/create?issueType=service-limit-increase). For **Limit type** , choose _EC2 Systems Manager_ and describe your reason for the request. - - * You can publicly share a maximum of five SSM documents. You can request an increase to this limit in the [Support Center](https://console.aws.amazon.com/support/home#/case/create?issueType=service-limit-increase). For **Limit type** , choose _EC2 Systems Manager_ and describe your reason for the request. - @@ -38,2 +37,0 @@ In Systems Manager, an _Amazon-owned_ SSM document is a document created and man -For more information about Systems Manager service quotas, see [AWS Systems Manager Service Quotas](https://docs.aws.amazon.com/general/latest/gr/ssm.html#limits_ssm). - @@ -46 +44 @@ For more information about Systems Manager service quotas, see [AWS Systems Mana - * Share an SSM document + * Share an SSM document using AWS RAM @@ -48 +46 @@ For more information about Systems Manager service quotas, see [AWS Systems Mana - * Modify permissions for a shared SSM document + * Share an SSM document using account permissions @@ -58,0 +57,5 @@ Review the following guidelines before you share or use a shared document. +**Use AWS RAM to share documents (recommended)** + + +For new document sharing, we recommend using AWS Resource Access Manager (AWS RAM) instead of the `ModifyDocumentPermission` API operation. When you share through AWS RAM, you can share a document with an entire organization or organizational unit (OU) in AWS Organizations instead of listing individual AWS account IDs. You can also manage access with a resource-based policy, and view and audit all of your shares in one place in the AWS RAM console. For steps, see Share an SSM document using AWS RAM. Documents that you share with individual AWS account IDs by using `ModifyDocumentPermission` are still supported. To move a document that you already share to AWS RAM, see Migrate an existing shared document to AWS RAM. + @@ -201 +204 @@ JSON -## Share an SSM document +## Share an SSM document using AWS RAM @@ -203 +206 @@ JSON -You can share AWS Systems Manager (SSM) documents by using the Systems Manager console. When sharing documents from the console, only the default version of the document can be shared. You can also share SSM documents programmatically by calling the `ModifyDocumentPermission` API operation using the AWS Command Line Interface (AWS CLI), AWS Tools for Windows PowerShell, or the AWS SDK. Before you share a document, get the AWS account IDs of the people with whom you want to share. Specify these account IDs when you share the document. +AWS Resource Access Manager (AWS RAM) is the recommended way to share AWS Systems Manager (SSM) documents. With AWS RAM, you create a resource share that grants access to your document, and you manage all of your shares from the AWS RAM console. You can share an SSM document with the following three types of principals: @@ -205 +208 @@ You can share AWS Systems Manager (SSM) documents by using the Systems Manager c -### Share a document (console) + * An entire organization in AWS Organizations. @@ -207 +210 @@ You can share AWS Systems Manager (SSM) documents by using the Systems Manager c - 1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/). + * An organizational unit (OU) in AWS Organizations. @@ -209 +212 @@ You can share AWS Systems Manager (SSM) documents by using the Systems Manager c - 2. In the navigation pane, choose **Documents**. + * Individual AWS accounts. @@ -211 +213,0 @@ You can share AWS Systems Manager (SSM) documents by using the Systems Manager c - 3. In the documents list, choose the document you want to share, and then choose **View details**. On the **Permissions** tab, verify that you're the document owner. Only a document owner can share a document. @@ -213 +214,0 @@ You can share AWS Systems Manager (SSM) documents by using the Systems Manager c - 4. Choose **Edit**. @@ -215 +215,0 @@ You can share AWS Systems Manager (SSM) documents by using the Systems Manager c - 5. To share the command publicly, choose **Public** and then choose **Save**. To share the command privately, choose **Private** , enter the AWS account ID, choose **Add permission** , and then choose **Save**. @@ -216,0 +217 @@ You can share AWS Systems Manager (SSM) documents by using the Systems Manager c +You can share a document only with accounts in the same AWS Region, and only the document owner can share a document. For more information about sharing with AWS RAM, see [Getting started with AWS RAM](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html) in the _AWS Resource Access Manager User Guide_. @@ -217,0 +219 @@ You can share AWS Systems Manager (SSM) documents by using the Systems Manager c +###### Important @@ -218,0 +221 @@ You can share AWS Systems Manager (SSM) documents by using the Systems Manager c +When you share an SSM document by using AWS RAM, you share all versions of the document, not only the default version. @@ -220 +223 @@ You can share AWS Systems Manager (SSM) documents by using the Systems Manager c -### Share a document (command line) +###### Note @@ -222 +225 @@ You can share AWS Systems Manager (SSM) documents by using the Systems Manager c -The following procedure requires that you specify an AWS Region for your command line session. +AWS RAM supports private sharing only. To share a document publicly, use the procedure in Share an SSM document using account permissions instead. @@ -224 +227 @@ The following procedure requires that you specify an AWS Region for your command - 1. Open the AWS CLI or AWS Tools for Windows PowerShell on your local computer and run the following command to specify your credentials. +###### Note @@ -226 +229 @@ The following procedure requires that you specify an AWS Region for your command -In the following command, replace `region` with your own information. For a list of supported `region` values, see the **Region** column in [Systems Manager service endpoints](https://docs.aws.amazon.com/general/latest/gr/ssm.html#ssm_region) in the _Amazon Web Services General Reference_. +When you share a document with an AWS account that is outside your organization, the consumer must accept the resource share invitation in AWS RAM before they can access the document. When you share within an organization that has AWS RAM sharing enabled, no invitation is required, and AWS RAM grants access automatically. @@ -228 +231 @@ In the following command, replace `region` with your own information. For a list -Linux & macOS +AWS RAM service quotas apply when you share SSM documents through AWS RAM. For more information, see [Service quotas for AWS RAM](https://docs.aws.amazon.com/ram/latest/userguide/service-quotas.html) in the _AWS Resource Access Manager User Guide_. @@ -229,0 +233 @@ Linux & macOS +To manage an existing share (for example, to update principals or stop sharing a document that you shared through AWS RAM), see [Working with shared AWS resources](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing.html) in the _AWS Resource Access Manager User Guide_. @@ -231 +235 @@ Linux & macOS - aws config +### Share a document using AWS RAM (console) @@ -233,4 +237 @@ Linux & macOS - AWS Access Key ID: [your key] - AWS Secret Access Key: [your key] - Default region name: region - Default output format [None]: +###### To share a document using AWS RAM @@ -238 +239 @@ Linux & macOS -Windows + 1. Open the AWS RAM console at [https://console.aws.amazon.com/ram/](https://console.aws.amazon.com/ram/). @@ -239,0 +241 @@ Windows + 2. In the navigation pane, choose **Resource shares** , and then choose **Create resource share**. @@ -241 +243 @@ Windows - aws config + 3. For **Name** , enter a name for the resource share. @@ -243,4 +245 @@ Windows - AWS Access Key ID: [your key] - AWS Secret Access Key: [your key] - Default region name: region - Default output format [None]: + 4. Under **Resources** , choose the resource type **SSM Documents** , and then select the document that you want to share. @@ -248 +247,5 @@ Windows -PowerShell + 5. (Optional) Under **Managed permissions** , review the managed permission that AWS RAM applies to the shared document. + + 6. Choose **Next**. Under **Principals** , add the organization, OUs, or AWS accounts that you want to share with. To share with your organization or an OU, you must enable sharing within AWS Organizations. + + 7. Choose **Next** , review your choices, and then choose **Create resource share**. @@ -251,2 +253,0 @@ PowerShell - Set-AWSCredentials –AccessKey your key –SecretKey your key - Set-DefaultAWSRegion -Region region @@ -254 +255,4 @@ PowerShell - 2. Use the following command to list all of the SSM documents that are available for you. The list includes documents that you created and documents that were shared with you. + +### Share a document using AWS RAM (command line) + +Open the AWS Command Line Interface (AWS CLI) or AWS Tools for Windows PowerShell on your local computer and run the following command to share a document by creating an AWS RAM resource share. For the `--principals` parameter, specify an organization ARN, an OU ARN, or an AWS account ID. @@ -259 +263,5 @@ Linux & macOS - aws ssm list-documents + + aws ram create-resource-share \ + --name MyDocumentShare \ + --resource-arns arn:aws:ssm:region:account-id:document/document-name \ + --principals principal @@ -264 +271,0 @@ Windows - aws ssm list-documents @@ -266 +273,4 @@ Windows -PowerShell + aws ram create-resource-share ^ + --name MyDocumentShare ^ + --resource-arns arn:aws:ssm:region:account-id:document/document-name ^ + --principals principal @@ -267,0 +278 @@ PowerShell +###### Note @@ -269 +280 @@ PowerShell - Get-SSMDocumentList +After you create a share, AWS RAM might take a few minutes to propagate the change before consuming accounts can see it. @@ -271 +282 @@ PowerShell - 3. Use the following command to get a specific document. +### Migrate an existing shared document to AWS RAM @@ -273 +284 @@ PowerShell -Linux & macOS +If you currently share a document by using account permissions (the `ModifyDocumentPermission` API operation), you can migrate it to an AWS RAM resource share by running the `AWS-MigrateSSMDocumentSharingToRAM` runbook. This AWS-owned AWS Systems Manager Automation runbook migrates a document from account-permission sharing to an AWS RAM resource share while preserving the document's existing consumers. @@ -274,0 +286 @@ Linux & macOS +###### Note @@ -276,2 +288 @@ Linux & macOS - aws ssm get-document \ - --name document name +Running the `AWS-MigrateSSMDocumentSharingToRAM` runbook uses AWS Systems Manager Automation, which incurs charges. For more information, see [AWS Systems Manager pricing](https://aws.amazon.com/systems-manager/pricing/). @@ -279 +290 @@ Linux & macOS -Windows +###### Note @@ -280,0 +292 @@ Windows +You can't migrate a document that is shared publicly, because AWS RAM supports private sharing only. If you specify a publicly shared document, the runbook fails. If you migrate all documents in the account, the runbook skips publicly shared documents. To migrate a publicly shared document, first stop sharing it publicly, and then share it with the accounts, organizational units (OUs), or organization that you want. @@ -282,2 +294 @@ Windows - aws ssm get-document ^ - --name document name +###### Important @@ -285 +296,15 @@ Windows -PowerShell +After you migrate a document, you manage sharing for that document through AWS RAM. The `ModifyDocumentPermission` and `DescribeDocumentPermission` API operations return a 4xx error for a migrated document. If the migration fails or is canceled, the runbook automatically rolls back the change. + +###### To migrate a document from its Permissions view (console) + + 1. Open the AWS Systems Manager console and, in the navigation pane, choose **Documents**. + + 2. Choose the document that you want to migrate. + + 3. Choose the **Details** tab. + + 4. In the **Permissions** section, choose **Migrate to RAM**. Systems Manager opens the **Migrate to RAM** page, which helps you start the migration. + + 5. For **Documents to migrate** , select the documents to migrate. Select individual documents, or choose **All documents** to migrate every document in the account that uses account-permission sharing. + + 6. For **AutomationAssumeRole** , choose the IAM role that Systems Manager Automation assumes to run the migration. @@ -286,0 +312 @@ PowerShell + 7. (Optional) For **Organizational units** , add an organization ID or organizational unit (OU) ID to share the documents with. @@ -288,2 +314 @@ PowerShell - Get-SSMDocument ` - –Name document name + 8. Choose **Start migration**. @@ -291 +316,50 @@ PowerShell - 4. Use the following command to get a description of the document. + + + +For the full list of parameters, the IAM permissions required for the `AutomationAssumeRole` role, and step-by-step instructions for running the runbook, see [AWS-MigrateSSMDocumentSharingToRAM](https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/automation-aws-migratessmdocumentsharingtoram.html) in the AWS Systems Manager Automation runbook reference. + +## Share an SSM document using account permissions + +You can share AWS Systems Manager (SSM) documents by modifying the document permissions to grant access to specific AWS account IDs (private sharing) or to everyone (public sharing). You can share documents from the Systems Manager console, or programmatically by calling the `ModifyDocumentPermission` API operation using the AWS Command Line Interface (AWS CLI), AWS Tools for Windows PowerShell, or the AWS SDK. When you share documents from the console, you can share only the default version of the document. Before you share a document, get the AWS account IDs of the accounts that you want to share with. Specify these account IDs when you share the document. + +###### Note + +For new document sharing, we recommend using AWS Resource Access Manager (AWS RAM) instead. With AWS RAM, you can share with an entire organization or OU and manage all of your shares in one place. For more information, see Share an SSM document using AWS RAM. +