How do I configure a central Amazon S3 bucket for Session Manager logging from multiple AWS accounts?

Resolution

Configure the permissions

Systems Manager Agent (SSM Agent) uses the same AWS Identity and Access Management (IAM) role to activate and upload logs to Amazon S3.

You can use one of the following IAM roles:

• An IAM instance profile that's attached to an Amazon Elastic Compute Cloud (Amazon EC2) instance.
• An IAM role that's configured for the Default Host Management Configuration.

To grant permissions, use the following policies:

• The AWS account that owns the IAM principal must use an IAM policy to grant Amazon S3 permissions.
• The owner of the S3 bucket must use the AWS Key Management Service (AWS KMS) key policy or access control list (ACL) to allow access to all accounts.
• If the bucket is encrypted with an AWS KMS key, then you must use an IAM policy.
• You must attach the IAM policy to the role that grants the SSM Agent permissions.
• You must use a KMS key policy to grant access to the AWS KMS key that you use to encrypt the bucket.
• You must use the AmazonSSMManagedInstanceCore AWS managed policy for access to the Systems Manager core functionality.

The following permissions are required for Session Manager to upload logs to the S3 bucket:

• The s3:PutObject and s3:PutObjectAcl permissions to upload encrypted objects into the S3 bucket.
• The kms:Decrypt and kms:GenerateDataKey permissions to access the AWS KMS keys.
• The aws:PrincipalOrgID: o-xxxxxxx permission to restrict access to principals that don't match the ID of your organization in AWS Organizations.

Verify connectivity to the following endpoints:

• Amazon S3 endpoints: com.amazonaws.region.s3
• AWS KMS service endpoints: com.amazonaws.region.kms
• Systems Manager endpoints: com.amazonaws.region.ssm
• Systems Manager Session Manager endpoints: com.amazonaws.region.ssmmessages
• Amazon EC2 endpoints: com.amazonaws.region.ec2

Create AWS KMS keys and key policy

Create AWS KMS keys to encrypt the S3 bucket and Session Manager logs.

You can create one key to encrypt both the Session Manager logs and the AWS KMS encryption, or create separate keys for each.

For each key, add the following key statement to the AWS KMS policy to allow Session Manager to encrypt the logs:

{
  "Effect": "Allow",
  "Principal": {
    "AWS": "*"
  },
  "Action": [
    "kms:Decrypt",
    "kms:GenerateDataKey"
  ],
  "Resource": "*",
  "Condition": {
    "StringEquals": {
      "aws:PrincipalOrgID": "o-xxxxxxx"
    }
  }
}

Note: Replace the aws:PrincipalOrgID with your organization's ID and the Principal with your IAM role's ARN.

Create the S3 bucket and bucket policy

Create an S3 bucket to store Session Manager logs. For more information, see Creating a general purpose bucket and Logging session data using Amazon S3 (console).

To allow access to the logs, add the following resource policy to the S3 bucket:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "*"
      },
      "Action": "s3:GetEncryptionConfiguration",
      "Resource": "arn:aws:s3:::customer_session_manager_logging_bucket",
      "Condition": {
        "StringEquals": {
          "aws:PrincipalOrgID": "o-xxxxxxxxxxxxxx"
        }
      }
    },
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "*"
      },
      "Action": [
        "s3:PutObject",
        "s3:PutObjectAcl"
      ],
      "Resource": "arn:aws:s3:::customer_session_manager_logging_bucket/*",
      "Condition": {
        "StringEquals": {
          "aws:PrincipalOrgID": "o-xxxxxxxxxxxxx"
        }
      }
    }
  ]
}

For more information about log access permissions, see Permissions for log delivery.

Create an IAM policy to access the S3 bucket and AWS KMS keys

Create an IAM policy that grants permissions to access the S3 bucket and AWS KMS keys.  

Attach the following example policy to the instance profile that your accounts use to connect the to the S3 bucket: 

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PutObjectsBucket",
      "Action": [
        "s3:PutObject",
        "s3:PutObjectAcl"
      ],
      "Effect": "Allow",
      "Resource": "arn:aws:s3:::customer_session_manager_logging_bucket/*"
    },
    {
      "Sid": "ListBucketAndEncryptionConfig",
      "Action": [
        "s3:GetEncryptionConfiguration"
      ],
      "Effect": "Allow",
      "Resource": "arn:aws:s3:::customer_session_manager_logging_bucket"
    },
    {
      "Sid": "S3KMSSessionManagerKMS",
      "Effect": "Allow",
      "Action": [
        "kms:Decrypt",
        "kms:GenerateDataKey*"
      ],
      "Resource": [
        "arn:aws:kms:us-east-1:ACCOUNTId:key/YOUR-KMS-FOR-SessionManagerEncryption",
        "arn:aws:kms:us-east-1:ACCOUNTID:key/YOUR-KMS-FOR-S3BucketEncryption"
      ]
    }
  ]
}

Note: You can use either an inline policy or a customer-managed policy. For more information, see Using IAM policies with AWS KMS.

(Optional) Configure Session Manager shell profiles for logs

To create a custom shell profile, create a JSON file, remove the content, and replace it with the following values:

{
  "schemaVersion": "1.0",
  "description": "Document to hold regional settings for Session Manager",
  "sessionType": "Standard_Stream",
  "inputs": {
    "s3BucketName": "customer_session_manager_logging_bucket",
    "s3KeyPrefix": "",
    "s3EncryptionEnabled": true,
    "cloudWatchLogGroupName": "",
    "cloudWatchEncryptionEnabled": false,
    "cloudWatchStreamingEnabled": false,
    "kmsKeyId": "arn:aws:kms:REGION:ACCOUNTID:key/YOUR-KMS-FOR-SessionManagerEncryption",
    "runAsDefaultUser": "",
    "idleSessionTimeout": "20",
    "maxSessionDuration": "",
    "shellProfile": {"windows": "", "linux": ""}
  }
}

Note: Replace customer_session_manager_logging_bucket with your bucket name and YOUR-KMS-FOR-SessionManagerEncryption with your designated key for Session Manager.

Run the following command to save the file as the default Session Manager document with a name such as, SessionManagerRunShell.json:

aws ssm update-document --name "SSM-SessionManagerRunShell" \
--content "file://SessionManagerRunShell.json" \   
--document-version "\$LATEST"

Verify the Session Manager logging configuration

Open the Amazon S3 console, and then navigate to the logging bucket. In the Bucket settings, confirm that that bucket encryption is active. Also, confirm that the AWS KMS key ARN matches Key 1 to make sure that Session Manager uses the correct encryption key.

To verify Session Manager preferences, complete the following steps:

1. Open the Session Manager console.
2. Select your AWS Region.
3. Confirm that you turned on encryption.
4. Enter the ARN of Key 1.
5. Verify that you configured the correct S3 bucket.

Verify that logs are generating in the bucket

To generate logs, use Session Manager in another account.

Complete the following steps:

1. Use Session Manager to connect to an instance.
2. Select your Region.
3. Verify that the session connects and shows "This Session is Encrypted using AWS KMS."
4. Enter test entries to generate the logs, and then end the session.

Note: After the session ends, it can take at least 30 seconds for logs to appear. For more information, see Logging requests using server access logging.

Related information

Protecting data with server-side encryption

Actions, resources, and condition keys for Amazon S3

Examples of Amazon S3 bucket policies

Access control in Amazon S3