Setting up Clean Rooms

Setting up AWS Clean Rooms

PDF

The following topics explain how to set up AWS Clean Rooms.

Before you can use any AWS service, including AWS Clean Rooms, you must sign up for AWS.

Service roles for AWS Clean Rooms

Sign up for AWS

If you do not have an AWS account, complete the following steps to create one.

To sign up for an AWS account
  1. Open https://portal.aws.amazon.com/billing/signup .

  2. Follow the online instructions.

    Part of the sign-up procedure involves receiving a phone call and entering a verification code on the phone keypad.

  3. When you sign up for an AWS account, an AWS account root user is created. The root user has access to all AWS services and resources in the account. As a security best practice, assign administrative access to an administrative user, and use only the root user to perform tasks that require root user access.

Create an administrator user

To use AWS Clean Rooms, you need to create an administrator user for yourself and add the administrator user to an administrators group.

To create an administrator user, choose one of the following options.

Choose one way to manage your administrator To By You can also
In IAM Identity Center

(Recommended)

Use short-term credentials to access AWS.

This aligns with the security best practices. For information about best practices, see Security best practices in IAM in the IAM User Guide.

Following the instructions in Getting started in the AWS IAM Identity Center User Guide. Configure programmatic access by Configuring the AWS CLI to use AWS IAM Identity Center in the AWS Command Line Interface User Guide.
In IAM

(Not recommended)

Use long-term credentials to access AWS. Following the instructions in Creating your first IAM admin user and user group in the IAM User Guide. Configure programmatic access by Managing access keys for IAM users in the IAM User Guide.

Create an IAM role for a collaboration member

A member is an AWS customer who is a participant in a collaboration.

To create an IAM role for a collaboration member
  1. Sign in to the IAM console ( https://console.aws.amazon.com/iam/ ) with your administrator account.

  2. Under Access management, choose Roles.

    With Roles, you can create short-term credentials, which is recommended for increased security. You can also choose Users to create long-term credentials.

  3. Choose Create role.

  4. In the Create role wizard, for Trusted entity type, choose AWS account.

  5. Leave the option This account selected, and then choose Next.

  6. For Add permissions, choose Create policy.

    1. In the Policy editor, select the JSON tab, and then add policies depending on the abilities granted to the collaboration member. AWS Clean Rooms offers the following managed policies based on common use cases:

    2. Choose Next: Tags, add tags (optional), and then choose Next: Review.

    3. For Review policy, enter a Name and Description, and review the Summary.

    4. Choose Create policy.

      You have created a policy for a collaboration member.

    5. Go back to your original tab and under Add permissions, enter the name of the policy you just created. (You might need to reload the page.)

    6. Select the check box next to the name of the policy you created, and then choose Next.

  7. For Name, review, and create, enter the Role name and Description.

    1. Review Select trusted entities, enter the AWS account for the person or persons who will assume the role (if necessary).

    2. Review the permissions in Add permissions, and edit if necessary.

    3. Review the Tags, and add tags if necessary.

    4. Choose Create role.

Create a service role to read data

AWS Clean Rooms uses a service role to read the data. You can create this role using the console if you have the necessary IAM permissions. If you do not have CreateRole permissions, ask your administrator to create the service role.

To create a service role to read data
  1. Sign in to the IAM console ( https://console.aws.amazon.com/iam/ ) with your administrator account.

  2. Under Access management, choose Roles.

    With Roles, you can create short-term credentials, which is recommended for increased security. You can also choose Users to create long-term credentials.

  3. Choose Create role.

  4. In the Create role wizard, for Trusted entity type, choose Custom trust policy.

  5. Copy and paste the following custom trust policy into the JSON editor.

    	{ 
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "RoleTrustPolicyForCleanRoomsService",
                "Effect": "Allow",
                "Principal": {
                    "Service": "cleanrooms.amazonaws.com"
                },
                "Action": "sts:AssumeRole"
            }
        ]
    }
    
    
  6. Choose Next.

  7. For Add permissions, choose Create policy.

    A new tab appears.

    1. In the Policy editor, select the JSON tab, and then copy and paste the following policy.

      Note

      The following example policy supports the permissions needed to read AWS Glue metadata and its corresponding Amazon S3 data. However, you might need to modify this policy depending on how you've set up your S3 data.

      Your AWS Glue resources and underlying Amazon S3 resources must be in the same AWS Region as the AWS Clean Rooms collaboration.

      If you want to ensure that the role can only be used in the context of a certain collaboration membership, you can scope down the trust policy further. For more information, see Cross-service confused deputy prevention.

      
      
      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Sid": "NecessaryGluePermissions",
                  "Effect": "Allow",
                  "Action": [
                      "glue:GetDatabase",
                      "glue:GetDatabases",
                      "glue:GetTable",
                      "glue:GetTables",
                      "glue:GetPartition",
                      "glue:GetPartitions",
                      "glue:BatchGetPartition"
                  ],
                  "Resource": [
                      "arn:aws:glue:aws-region:accountId:database/database",
                      "arn:aws:glue:aws-region:accountId:table/table",
                      "arn:aws:glue:aws-region:accountId:catalog"
                  ]
              },
       	{
                  "Effect": "Allow",
                  "Action": [
                      "glue:GetSchema",
                      "glue:GetSchemaVersion"
                  ],
                  "Resource": [
                      "*"
                  ]
              },
              {
                  "Sid": "NecessaryS3BucketPermissions",
                  "Effect": "Allow",
                  "Action": [
                      "s3:GetBucketLocation", 
                      "s3:ListBucket"
                  ],
                  "Resource": [
                      "arn:aws:s3:::bucket"
                  ],
                  "Condition":{
                      "StringEquals":{
                          "s3:ResourceAccount":[
                              "s3BucketOwnerAccountId"
                          ]
                      }
                  }
              },
              {
                  "Sid": "NecessaryS3ObjectPermissions",
                  "Effect": "Allow",
                  "Action": [
                      "s3:GetObject"
                  ],
                  "Resource": [
                      "arn:aws:s3::bucket/prefix/*"
                  ],
                  "Condition":{
                      "StringEquals":{
                          "s3:ResourceAccount":[
                              "s3BucketOwnerAccountId"
                          ]
                      }
                  }
              }
          ]
      }
      
    2. Choose Next: Tags, add tags (optional), and then choose Next: Review.

    3. For Review policy, enter a Name and Description, and review the Summary.

    4. Choose Create policy.

      You have created a policy for AWS Clean Rooms.

  8. Go back to your original tab and, under Add permissions, enter the name of the policy you just created. (You might need to reload the page.)

  9. Select the check box next to the name of the policy you created, and then choose Next.

  10. For Name, review, and create, enter the Role name and Description.

    Note

    The Role name must match the pattern in the passRole permissions granted to the member who can query and receive results and member roles.

    1. Review Select trusted entities, and edit if necessary.

    2. Review the permissions in Add permissions, and edit if necessary.

    3. Review the Tags, and add tags if necessary.

    4. Choose Create role.

  11. The service role for AWS Clean Rooms has been created.

Create a service role to write results

Note

If you are only the member who can receive results (in the console, Your member abilities is Receive results), follow this procedure.

If you are both a member who can query and a member who can receive results (in the console, Your member abilities is both Query and Receive results), you can skip this procedure.

AWS Clean Rooms uses a service role to write results of the queried data in the collaboration to the specified Amazon S3 bucket. You can create this role using the console if you have the necessary IAM permissions. If you do not have CreateRole permissions, ask your administrator to create the service role.

To create a service role to write results
  1. Sign in to the IAM console ( https://console.aws.amazon.com/iam/ ) with your administrator account.

  2. Under Access management, choose Roles.

    With Roles, you can create short-term credentials, which is recommended for increased security. You can also choose Users to create long-term credentials.

  3. Choose Create role.

  4. In the Create role wizard, for Trusted entity type, choose Custom trust policy.

  5. Copy and paste the following custom trust policy into the JSON editor.

    Example custom trust policy

    In the following example, replace each placeholder with your own information:

    • region – The name of the AWS Region. For example, us-east-1.

    • a1b2c3d4-5678-90ab-cdef-EXAMPLEaaaaa – The Membership ID of the member who can query. The Membership ID can be found on the Details tab of the collaboration. This ensures that AWS Clean Rooms is assuming the role only when this member runs the analysis in this collaboration.

    • arn:aws:cleanrooms:us-east-1:555555555555:membership/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111 – The single Membership ARN of the member who can query. The Membership ARN can be found on the Details tab of the collaboration. This ensures AWS Clean Rooms is assuming the role only when this member runs the analysis in this collaboration.

    
    
    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "AllowIfExternalIdMatches",
                "Effect": "Allow",
                "Principal": {
                    "Service": "cleanrooms.amazonaws.com"
                },
                "Action": "sts:AssumeRole",
                "Condition": {
                    "ArnLike": {
                        "sts:ExternalId": "arn:aws:*:region:*:dbuser:*/a1b2c3d4-5678-90ab-cdef-EXAMPLEaaaaa*"
                    }
                }
            },
            {
                "Sid": "AllowIfSourceArnMatches",
                "Effect": "Allow",
                "Principal": {
                    "Service": "cleanrooms.amazonaws.com"
                },
                "Action": "sts:AssumeRole",
                "Condition": {
                    "ForAnyValue:ArnEquals": {
                        "aws:SourceArn": [
                            "arn:aws:cleanrooms:us-east-1:555555555555:membership/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
                        ]
                    }
                }
            }
        ]
    }
    
  6. Choose Next.

  7. For Add permissions, choose Create policy.

    A new tab appears.

    1. In the Policy editor, choose the JSON button, and then copy and paste the following policy.

      Note

      The following example policy supports the permissions needed to read AWS Glue metadata and its corresponding Amazon S3 data. However, you might need to modify this policy depending on how you've set up your S3 data.

      Your AWS Glue resources and underlying Amazon S3 resources must be in the same AWS Region as the AWS Clean Rooms collaboration.

      If you want to ensure that the role can only be used in the context of a certain collaboration membership, you can scope down the trust policy further. For more information, see Cross-service confused deputy prevention.

      Example service role policy

      In the following example, replace each placeholder with your own information:

      • bucket_name – The Amazon Resource Name (ARN) of the S3 bucket. The Amazon Resource Name (ARN) can be found on the Properties tab of the bucket in Amazon S3.

      • 111122223333 – The AWS account ID in which the S3 bucket is located.

        bucket_name/optional_key_prefix – The Amazon Resource Name (ARN) of the results destination in S3. The Amazon Resource Name (ARN) can be found on the Properties tab of the bucket in Amazon S3.

      
      
      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Effect": "Allow",
                  "Action": [
                      "s3:GetBucketLocation", 
                      "s3:ListBucket"
                  ],
                  "Resource": [
                      "arn:aws:s3:::bucket_name"
                  ],
                  "Condition": {
                      "StringEquals": {
                          "aws:ResourceAccount":"111122223333"
                      }
                  }
              },
              {
                  "Effect": "Allow",
                  "Action": [
                      "s3:PutObject"
                  ],
                  "Resource": [
                      "arn:aws:s3:::bucket_name/optional_key_prefix/*"
                  ],
                  "Condition": {
                      "StringEquals": {
                          "aws:ResourceAccount":"111122223333"
                      }
                  }
              }
          ]
      }
      
    2. Choose Next.

    3. For Review and create,

      1. For Policy details, enter a Name and Description.

      2. Review the Permissions defined in this policy.

    4. Add tags (optional).

    5. Choose Create policy.

      You have created a policy for AWS Clean Rooms.

  8. Go back to your original tab and under Add permissions, enter the name of the policy you just created. (You might need to reload the page.)

  9. Select the check box next to the name of the policy you created, and then choose Next.

  10. For Name, review, and create, enter the Role name and Description.

    Note

    The Role name must match the pattern in the passRole permissions granted to the member who can query and receive results and member roles.

    1. Review Select trusted entities, and edit if necessary.

    2. Review the permissions in Add permissions, and edit if necessary.

    3. Review the Tags, and add tags if necessary.

    4. Choose Create role.

  11. The service role for AWS Clean Rooms has been created.

Create a service role to read training data

AWS Clean Rooms uses a service role to read training data. You can create this role using the console if you have the necessary IAM permissions. If you do not have CreateRole permissions, ask your administrator to create the service role.

To create a service role to train a dataset
  1. Sign in to the IAM console ( https://console.aws.amazon.com/iam/ ) with your administrator account.

  2. Under Access management, choose Policies.

  3. Choose Create policy.

  4. In the Policy editor, select the JSON tab, and then copy and paste the following policy.

    Note

    The following example policy supports the permissions needed to read AWS Glue metadata and its corresponding Amazon S3 data. However, you might need to modify this policy depending on how you've set up your S3 data. This policy does not include a KMS key to decrypt data.

    Your AWS Glue resources and underlying Amazon S3 resources must be in the same AWS Region as the AWS Clean Rooms collaboration.

    
    
    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Action": [
                    "glue:GetDatabase",
                    "glue:GetDatabases",
                    "glue:GetTable",
                    "glue:GetTables",
                    "glue:GetPartitions",
                    "glue:GetPartition",
                    "glue:BatchGetPartition", 
                    "glue:GetUserDefinedFunctions"
                ],
                "Resource": [
                    "arn:aws:glue:region:accountId:database/databases",
                    "arn:aws:glue:region:accountId:table/databases/tables",
                    "arn:aws:glue:region:accountId:catalog",
                    "arn:aws:glue:region:accountId:database/default"
                ]
            },
            {
                "Effect": "Allow",
                "Action": [
                    "glue:CreateDatabase"
                ],
                "Resource": [
                    "arn:aws:glue:region:accountId:catalog",
                    "arn:aws:glue:region:accountId:database/default"
                ]
            },
            {
                "Effect": "Allow",
                "Action": [
                    "s3:ListBucket",
                    "s3:GetBucketLocation"
                ],
                "Resource": [
                    "arn:aws:s3:::bucket"
                ],
                "Condition":{
                    "StringEquals":{
                        "s3:ResourceAccount":[
                            "accountId"
                        ]
                    }
                }
            },
            {
                "Effect": "Allow",
                "Action": [
                    "s3:GetObject"
                ],
                "Resource": [
                    "arn:aws:s3:::bucketFolders/*"
                ],
                "Condition":{
                    "StringEquals":{
                        "s3:ResourceAccount":[
                            "accountId"
                        ]
                    }
                }
            }
        ]
    }
    

    If you need to use a KMS key to decrypt data, add this AWS KMS statement to the previous template:

    
    
    {
                "Effect": "Allow",
                "Action": [
                    "kms:Decrypt",
                ],
                "Resource": [
                    "arn:aws:kms:region:accountId:key/keyId"
                ],
                "Condition": {
                    "StringLike": {
                            "kms:EncryptionContext:aws:s3:arn": "arn:aws:s3:::bucketFolders/*"
                    }
                }
            }
        ]
    }
    		                    
    
  5. Choose Next.

  6. For Review and create, enter a Policy name and Description, and review the Summary.

  7. Choose Create policy.

    You have created a policy for AWS Clean Rooms.

  8. Under Access management, choose Roles.

    With Roles, you can create short-term credentials, which is recommended for increased security. You can also choose Users to create long-term credentials.

  9. Choose Create role.

  10. In the Create role wizard, for Trusted entity type, choose Custom trust policy.

  11. Copy and paste the following custom trust policy into the JSON editor.

    { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowAssumeRole", "Effect": "Allow", "Principal": { "Service": "cleanrooms-ml.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "StringEqualsIfExists": { "aws:SourceAccount": ["yourAccount"] }, "StringLikeIfExists": { "aws:SourceArn": "arn:aw:cleanrooms-ml:region:account:training-dataset/*" } } } ] }

    The SourceAccount is always your AWS account. The SourceArn can be limited to a specific training dataset, but only after that dataset is created. Because you can't pre-know the training dataset ARN, the wildcard is specified here.

  12. Choose Next and under Add permissions, enter the name of the policy you just created. (You might need to reload the page.)

  13. Select the check box next to the name of the policy you created, and then choose Next.

  14. For Name, review, and create, enter the Role name and Description.

    Note

    The Role name must match the pattern in the passRole permissions granted to the member who can query and receive results and member roles.

    1. Review Select trusted entities, and edit if necessary.

    2. Review the permissions in Add permissions, and edit if necessary.

    3. Review the Tags, and add tags if necessary.

    4. Choose Create role.

  15. The service role for AWS Clean Rooms has been created.

Create a service role to write a lookalike segment

AWS Clean Rooms uses a service role to write lookalike segments to a bucket. You can create this role using the console if you have the necessary IAM permissions. If you do not have CreateRole permissions, ask your administrator to create the service role.

To create a service role to write a lookalike segment
  1. Sign in to the IAM console ( https://console.aws.amazon.com/iam/ ) with your administrator account.

  2. Under Access management, choose Policies.

  3. Choose Create policy.

  4. In the Policy editor, select the JSON tab, and then copy and paste the following policy.

    Note

    The following example policy supports the permissions needed to read AWS Glue metadata and its corresponding Amazon S3 data. However, you might need to modify this policy depending on how you've set up your S3 data. This policy does not include a KMS key to decrypt data.

    Your AWS Glue resources and underlying Amazon S3 resources must be in the same AWS Region as the AWS Clean Rooms collaboration.

    
    
    {
        "Version": "2012-10-17",
        "Statement": [
        {
                "Effect": "Allow",
                "Action": [
                    "s3:ListBucket",
                    "s3:GetBucketLocation"
                ],
                "Resource": [
                    "arn:aws:s3:::buckets"
                ],
                "Condition":{
                    "StringEquals":{
                        "s3:ResourceAccount":[
                            "accountId"
                        ]
                    }
                }
            },
            {
                "Effect": "Allow",
                "Action": [
                    "s3:PutObject"
                ],
                "Resource": [
                    "arn:aws:s3:::bucketFolders/*"
                ],
                "Condition":{
                    "StringEquals":{
                        "s3:ResourceAccount":[
                            "accountId"
                        ]
                    }
                }
            }
      ]
    }
    

    If you need to use a KMS key to decrypt data, add this AWS KMS statement to the template:

    
    
    {
                "Effect": "Allow",
                "Action": [
                    "kms:Encrypt",
                    "kms:GenerateDataKey*",
                    "kms:ReEncrypt*",
                ],
                "Resource": [
                    "arn:aws:kms:region:accountId:key/keyId"
                ],
                "Condition": {
                    "StringLike": {
                            "kms:EncryptionContext:aws:s3:arn": "arn:aws:s3:::bucketFolders/*"
                    }
                }
            }
      ]
    }
    
  5. Choose Next.

  6. For Review and create, enter a Policy name and Description, and review the Summary.

  7. Choose Create policy.

    You have created a policy for AWS Clean Rooms.

  8. Under Access management, choose Roles.

    With Roles, you can create short-term credentials, which is recommended for increased security. You can also choose Users to create long-term credentials.

  9. Choose Create role.

  10. In the Create role wizard, for Trusted entity type, choose Custom trust policy.

  11. Copy and paste the following custom trust policy into the JSON editor.

    
    
    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "AllowAssumeRole",
                "Effect": "Allow",
                "Principal": {
                    "Service": "cleanrooms-ml.amazonaws.com"
                },
                "Action": "sts:AssumeRole",
                "Condition": {
                    "StringEqualsIfExists": { 
                        "aws:SourceAccount": ["yourAccount"]
    
                    },
                    "StringLikeIfExists": { 
                        "aws:SourceArn": "arn:aw:cleanrooms-ml:region:account:configured-audience-model/*"
                    }
                }
            }
        ]
    }
    
    

    The SourceAccount is always your AWS account. The SourceArn can be limited to a specific training dataset, but only after that dataset is created. Because you can't pre-know the training dataset ARN, the wildcard is specified here.

  12. Choose Next.

  13. Select the check box next to the name of the policy you created, and then choose Next.

  14. For Name, review, and create, enter the Role name and Description.

    Note

    The Role name must match the pattern in the passRole permissions granted to the member who can query and receive results and member roles.

    1. Review Select trusted entities, and edit if necessary.

    2. Review the permissions in Add permissions, and edit if necessary.

    3. Review the Tags, and add tags if necessary.

    4. Choose Create role.

  15. The service role for AWS Clean Rooms has been created.

Create a service role to read seed data

AWS Clean Rooms uses a service role to read seed data. You can create this role using the console if you have the necessary IAM permissions. If you do not have CreateRole permissions, ask your administrator to create the service role.

To create a service role to read seed data
  1. Sign in to the IAM console ( https://console.aws.amazon.com/iam/ ) with your administrator account.

  2. Under Access management, choose Policies.

  3. Choose Create policy.

  4. In the Policy editor, select the JSON tab, and then copy and paste the following policy.

    Note

    The following example policy supports the permissions needed to read AWS Glue metadata and its corresponding Amazon S3 data. However, you might need to modify this policy depending on how you've set up your S3 data. This policy does not include a KMS key to decrypt data.

    Your AWS Glue resources and underlying Amazon S3 resources must be in the same AWS Region as the AWS Clean Rooms collaboration.

    
    
    {
        "Version": "2012-10-17",
        "Statement": [
        {
                "Effect": "Allow",
                "Action": [
                    "s3:ListBucket",
                ],
                "Resource": [
                    "arn:aws:s3:::buckets"
                ],
                "Condition":{
                    "StringEquals":{
                        "s3:ResourceAccount":[
                            "accountId"
                        ]
                    }
                }
            },
            {
                "Effect": "Allow",
                "Action": [
                    "s3:GetObject"
                ],
                "Resource": [
                    "arn:aws:s3:::bucketFolders/*"
                ],
                "Condition":{
                    "StringEquals":{
                        "s3:ResourceAccount":[
                            "accountId"
                        ]
                    }
                }
            }
      ]
    }
    

    If you need to use a KMS key to decrypt data, add this AWS KMS statement to the template:

    
    
    {
                "Effect": "Allow",
                "Action": [
                    "kms:Decrypt",
                    "kms:DescribeKey"
                ],
                "Resource": [
                    "arn:aws:kms:region:accountId:key/keyId"
                ],
                "Condition": {
                    "StringLike": {
                            "kms:EncryptionContext:aws:s3:arn": "arn:aws:s3:::bucketFolders/*"
                    }
                }
            }
      ]
    }
    
  5. Choose Next.

  6. For Review and create, enter a Policy name and Description, and review the Summary.

  7. Choose Create policy.

    You have created a policy for AWS Clean Rooms.

  8. Under Access management, choose Roles.

    With Roles, you can create short-term credentials, which is recommended for increased security. You can also choose Users to create long-term credentials.

  9. Choose Create role.

  10. In the Create role wizard, for Trusted entity type, choose Custom trust policy.

  11. Copy and paste the following custom trust policy into the JSON editor.

    
    
    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "AllowAssumeRole",
                "Effect": "Allow",
                "Principal": {
                    "Service": "cleanrooms-ml.amazonaws.com"
                },
                "Action": "sts:AssumeRole",
                "Condition": {
                    "StringEqualsIfExists": {
                        "aws:SourceAccount": ["yourAccount"]
    
                    },
                    "StringLikeIfExists": { 
                        "aws:SourceArn": "arn:aw:cleanrooms-ml:region:account:audience-generation-job/*"
                    }
                }
            }
        ]
    }
    
    

    The SourceAccount is always your AWS account. The SourceArn can be limited to a specific training dataset, but only after that dataset is created. Because you can't pre-know the training dataset ARN, the wildcard is specified here.

  12. Choose Next.

  13. Select the check box next to the name of the policy you created, and then choose Next.

  14. For Name, review, and create, enter the Role name and Description.

    Note

    The Role name must match the pattern in the passRole permissions granted to the member who can query and receive results and member roles.

    1. Review Select trusted entities, and edit if necessary.

    2. Review the permissions in Add permissions, and edit if necessary.

    3. Review the Tags, and add tags if necessary.

    4. Choose Create role.

  15. The service role for AWS Clean Rooms has been created.