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

Short description

In Systems Manager, you can identify and configure the Amazon S3 logging for Session Manager. 

Getting started

AWS Systems Manager Agent (SSM Agent) uses the same AWS Identity and Access Management (IAM) role to activate itself and upload logs to Amazon S3. You can use either an IAM instance profile that's attached to an Amazon Elastic Compute Cloud (Amazon EC2) instance or the IAM role that's configured for the Default Host Management Configuration.

You must have the following permissions to complete the configuration:

• The account that owns the IAM principal that's used for permissions must grant the Amazon S3 permissions through an IAM policy.
• The owner of the S3 bucket must also grant permissions through a bucket policy or access control list (ACL) to all the accounts.
• If the bucket is encrypted with a AWS Key Management Service (AWS KMS) key, then you must create and use an IAM policy.

Note:

• You must attach the IAM policy to the role that grants the SSM Agent permissions.
• The KMS key that's used to encrypt the bucket must also grant the permission through the KMS key policy.

To configure central Amazon S3 bucket logging for Session Manager, first identify the primary account that owns your centralized S3 bucket. In the following example, Account A owns the centralized bucket.

Then, complete the following steps:

1. In Account A, create one or two custom AWS KMS keys and one custom KMS policy.
2. In Account A, create an S3 bucket for Systems Manager logging.
3. In account A, create the resource policy for the S3 bucket.
4. In another account, create an IAM policy to grant permissions to the S3 bucket and both KMS keys.
5. (Optional) Use Session Manager shell profiles to create and configure logging.
6. Verify that the Session Manager logging is configured to the destination buckets and is using the KMS key.
7. Verify that logs are generating in the bucket.

Resolution

Note: To scope the permissions, the following example process uses condition keys for the roles and AWS Organizations. If you require additional permissions control, then it's a best practice to use principal roles in Session Manager.

This process uses the following key permissions:

• The IAM AWS managed policy AmazonSSMManagedInstanceCore to provide Systems Manager permissions.
• The s3:GetEncryptionConfiguration permission for describing the encryption configuration on the S3 bucket.
• The s3:PutObject and s3:PutObjectAcl permissions to put encrypted objects into the S3 bucket.
• The kms:Decrypt and kms:GenerateDataKey permissions to provide access to the KMS keys when accessing the buckets and Session Manager.
• The aws:PrincipalOrgID: o-xxxxxxx permission to allow restricted access to any principal who doesn't match the Organizations ID.

Prerequisites

You must have connectivity to endpoints for the following services:

• Amazon S3
• AWS KMS
• Systems Manager and Systems Manager messages
• Amazon EC2 messages

Create the KMS keys

First, create one or two keys.

• If you're creating one key, then use it (Key 1) for S3 encryption on the Session Manager logging bucket and the Session Manager preferences KMS encryption.
• If you're creating two keys, then use the first KMS key (Key 1) to encrypt the S3 bucket for logging. Use the second KMS key (Key 2) to encrypt the Session Manager stream to the Amazon S3 bucket.

Then, create the key Sid for each key. Be sure to add the Sid element to your KMS policy for each key. 

To allow Session Manager to encrypt the session, add the following permissions to Organizations:

Note: Replace the aws:PrincipalOrgID value with your Organizations ID and the principal ARN.

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

Create an S3 bucket for logging in Account A

Create an Amazon S3 bucket for logging Session Manager data in Account A. Make sure to name the bucket, for example, customer_session_manager_logging_bucket. When choosing the encryption, use Key 1.

Create the resource policy for the S3 bucket

Apply the following resource policy to the bucket that you're using to log your sessions.

To use a condition key for PrincipalOrgId to restrict access to the S3 bucket, add the following resource policy to your S3 bucket:

Note: This policy rejects access requests from a principal who's outside your organization.

{  
    "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"  
                }  
            }  
        }  
    ]  
}

Create an IAM policy

First, create an IAM policy to grant permissions to the S3 bucket and the keys.

Attach the following example policy to your instance profile to use on the accounts that you want to connect. You can use an inline policy or customer managed policy to attach the policy:

{  
    "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"  
            ]  
        }  
    ]  
}

(Optional) Use Session Manager shell profiles to create and configure logging

To create a custom shell profile, first create a file. Then, save the file with a description name, for example SessionManagerRunShell.json. Replace the contents of this .json file with the following example:

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

{  
"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": ""}  
  }  
}

Run the following commands to save this file as the default Session Manager document:

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

Verify that the Session Manager logging is configured to the destination buckets and is using the KMS key

Open the S3 bucket, and verify that you have Bucket Encryption turned on. Check the KMS ARN to make sure that Session Manager is using Key 1.

Note: When configuring Session Manager cross-account logging, it's a best practice to use a prefix of the account ID. This helps you keep track of the accounts and their associated logs.

To check the Session Manager preferences, complete the following steps:

1. Open the Session Manager console, and then choose your AWS Region.
2. Verify that you have S3 bucket encryption turned on, and then enter the ARN of Key 1 that's in Account A.
3. In the S3 bucket, enter the name of the S3 bucket that's in Account A.

Verify that logs are generating in the bucket

To generate logs, use Session Manager in another account to connect to your instance.

Complete the following steps:

1. Open the Session Manager console, and then choose your Region.
2. Check that the session connects and the following message displays: "This Session is Encrypted using AWS KMS"
3. Enter a few test entries to generate the logs, and then end your session.
4. In Account A, navigate to the S3 bucket that you created for logging and look for the latest logs by time.

Note: After disconnecting the session, it can take at least 30 seconds for the logs to populate. 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

Bucket policy examples

Access policy guidelines

Allow a user to encrypt and decrypt with specific KMS keys