Table of contents
Topics on this page

Add an AWS account using a cross-account role

You can add an AWS account using a cross-account role. Use a cross-account role if you want to add multiple AWS accounts, or if you want to add a single account but do not want to use the quick setup method.

The following instructions assume you want to add an AWS account with the name AWS Account A.

You can also add a cross-account role through the Workload Security API. See Add the account through the API for details.

First, note the Workload Security account ID

Workload Security Account ID: 147995105371
You will need this ID later, when creating the cross-account role.

Next, configure the manager instance role
  1. In the Workload Security console, click Administration at the top.
  2. Click System Settings on the left.
  3. Click the Advanced tab in the main pane.
  4. Scroll to the bottom and look for the Manager AWS Identity section.
  5. Make sure Use Manager Instance Role is selected.
  6. Click Save.
Next, retrieve the external ID
  1. Log in to Workload Security.
  2. Click Computers at the top.
  3. Click Add > Add AWS Account. A wizard appears.
  4. Click Advanced, then click Next.
  5. Click the eye icon next to the obscured external ID to reveal it. For more on this ID, see What is the external ID?
  6. Copy the external ID to a secure place. You will need it in the next step to configure AWS Account A and any other AWS accounts you want to add.
  7. Optionally, close the wizard and the Workload Security console.
Next, configure an IAM policy for AWS Account A
  1. Make sure you're logged in to AWS Account A.
  2. In the Amazon Web Services Console, go to the IAM service.
  3. In the left navigation pane, click Policies.

    If this is your first time on this page, you'll need to click Get Started.

  4. Click Create policy.
  5. Select the JSON tab.
  6. Copy the following JSON code into the text box:
        "Version": "2012-10-17",
        "Statement": [
                "Sid": "cloudconnector",
                "Action": [
                "Effect": "Allow",
                "Resource": "*"

    The "iam:GetRole" and "iam:GetRolePolicy" permissions are optional, but recommended because they allow Workload Security to determine whether you have the correct policy when an update to Workload Security occurs that requires additional AWS permissions.

  7. Click Review policy.
  8. Give the policy a name and description. Example name: Workload_Security_Policy_Cross.
  9. Click Create policy. Your policy is now ready to use.
Next, create a cross-account role for AWS Account A
  1. Make sure you are logged in to AWS Account A.
  2. Go to the IAM service.
  3. In the left navigation pane, click Roles.
  4. In the main pane, click Create role.
  5. Click Another AWS account.
  6. In the Account ID field, enter the Workload Security account ID. It is: 147995105371
  7. Next to Options, enable Require external ID. In the External ID field, enter the external ID you retrieved from the Workload Security console earlier.
  8. Click Next: Permissions.
  9. Select the IAM policy that you just created (the example name was Workload_Security_Policy_Cross) and then click Next: Review.
  10. On the Review page, enter a role name and description. Example role name: Workload_Security_Role_Cross.
  11. On the main role page, search for the role you just created (Workload_Security_Role_Cross).
  12. Click it.
  13. Find the Role ARN field at the top. It looks similar to:
  14. Note the Role ARN value. You will need it later.
    You now have a cross-account role under AWS Account A that includes the correct policy and references the of the AWS Primary Account.
Next, add AWS Account A to Workload Security
  1. Log in to Workload Security.
  2. Click Computers at the top.
  3. Click Add > Add AWS Account.
  4. Select Advanced and click Next.
  5. Select Use Cross Account Role.
  6. Enter AWS Account A's Cross Account Role ARN. You noted this earlier, when you created the cross-account role. In this example, it is arn:aws:iam::2222222222:role/Workload_Security_Role_Cross
  7. If AWS Account A includes Amazon WorkSpaces, select Include Amazon WorkSpaces to include them with your Amazon EC2 instances. By enabling the check box, you ensure that your Amazon WorkSpaces appear in the correct location in the tree structure in the Workload Security console and are billed at the correct rate.
  8. Click Next.
    AWS Account A's Amazon EC2 instances and Amazon WorkSpaces are loaded.

You have now added AWS Account A to Workload Security.

After completing the preceding steps, proceed to Install the agent on your Amazon EC2 and WorkSpace instances if you have not done so already.

Add the account through the API

  1. If you do not yet have the external ID, call the Workload Security /api/awsconnectorsettings endpoint to retrieve it (the ExternalId parameter). For more on this ID, see What is the external ID?
  2. In AWS, specify the external ID in your cross-account role's IAM trust policy.
  3. Use the /api/awsconnectors API endpoint to add AWS accounts to Workload Security. (Do not use the /rest/cloudaccounts/aws API because it has been deprecated.) See for details on how long the /rest/cloudaccounts/aws API will continue to be supported and tips on how to move to the new endpoint.