Configuring the AWS Adapter Using Organizations

Axonius recomends using AWS Organizations.
In large AWS deployments, it becomes difficult to maintain the list of accounts and roles (or individual adapter connections) that are needed by Axonius in order to be able to connect to those accounts and enumerate the AWS resources in those accounts. If you are using the AWS Organizations service to manage your AWS accounts, then there is an easier way to configure Axonius.

You can use AWS Organizations to set up a single AWS adapter connection and then use that connection to discover and connect to all of the AWS Organization member accounts.
To read more about AWS Organizations, see here.

Requirements for Configuring the AWS Adapter Using Organizations

In order for this feature to work correctly, the following criteria must be met:

• A role must be configured on the AWS adapter connection that has the following two IAM permissions (no other permissions are needed):

  sts:AssumeRole

  organizations:ListAccounts

• This role can be inherited through an AWS Access Key ID and Secret Access Key keypair or through an EC2 instance attached role. The configuration for each of these scenarios will be discussed in this section.

• The key/secret used in the adapter configuration will be used to assume the roles named in advanced configuration for every member account.

• The roles that the original role will inherit in each of the member accounts must be named the same across all member accounts and must be in the same path across all member accounts. If an external ID is used for authentication, that external ID must be the same across all member accounts.

Configuration for the AWS Adapter Using Organizations

This section of the document describes how to configure the AWS adapter to query an AWS organization for all member accounts, then inherit a role in those accounts to use for discovery.

There are two ways to configure the AWS adapter connection to simplify the setup in large AWS deployments. You an configure an AWS Access Key ID and Secret Key or configure an EC2 instance attached role. Both of these methods allow the Organization member account discovery and role assumption.

Access Key and Secret Key

In this scenario, you configure an IAM user with an AWS Access Key ID and Secret Key that has the ability to assume a role that will perform the discovery and subsequently assume roles in each organization member account.

In the AWS adapter, create a new connection and configure it as follows (not all configuration fields are discussed here, if they are optional):

• Add a region name or select the 'Get All Regions' checkbox.
• Enter the Access Key ID
• Enter the Secret Key
• Create a roles to assume file, according to the instructions here. The role referenced in this file should have the permissions described below in 'Sample IAM Policy' and should have the appropriate Trust Relationship in the organization root account and all member accounts.

The roles to assume file should look similar to this example, where '111111111111' is the account number of the organization root account and 'Axonius-Adapter' is the name of the role to inherit in the root account and which contains the permissions enumerated in the section titled 'Sample IAM Policy' below:

Roles to Assume Example

[

  {"arn":  "arn:aws:iam::111111111111:role/Axonius-Adapter"}

]

Create an advanced configuration file as described here with skip_ec2_verification set to true.

The following JSON-format advanced configuration file should be used if you are employing an AWS Access Key ID and Secret Key to query the organization and assume roles in the organization.

Advanced Configuration File Example 1

{
  "skip_ec2_verification": true
}

Save the connection.

You're ready to discover AWS resources.

EC2 Instance Attached Role

Here, you will configure the AWS adapter connection to use an EC2 instance attached role. This does not require the use of an AWS Access Key ID / Secret Key keypair.

• Add a region name or select the 'Get All Regions' checkbox.
• Check the 'Use instance profile (attached role)' checkbox.
• Create an advanced configuration file, similar to the sample below.

Advanced Configuration File Example 2

This JSON-format advanced configuration file is an example of a typical configuration for AWS Organization discovery.

{
  "fetch_roles_from_organization":
    {
      "organization_role_for_discovery": "arn:aws:iam::111111111111:role/Axonius-Adapter",

      "role_name": "Axonius-Adapter",

      "role_path": "",

      "external_id": "",

      "region": "us-east-1"

    },

  "skip_ec2_verification": true
}

• Save the connection.

Fetch only Specifide OU accounts

You're ready to discover AWS resources.

Advanced Configuration Fields

This section describes each of the fields in the advanced configuration.

Role for Organization Discovery

The configuration assumes the initial role defined at organization_role_for_discovery. This role is used to query the root organization account for a list of all organization member account numbers. The 111111111111 account number should be replaced with the account number of the root organization account.

Fetch only OU Specific accounts (optional)
fetch_only_ou_accounts This is an optional setting that can be used to fetch only accounts that are hierarchically under the specific OU (instead of the entire organization). The syntax is
"fetch_only_ou_accounts": "ou-aaaa-aaaa", when you replace the second string here with the OU ID.
The following permissions are required for the organization role when you use this:
organizations:ListAccountsForParent
organizations:ListChildren

Common Role Name

The role_name is the name of the role that must be present in all member accounts and the role that will be used for the normal device and user discovery by Axonius. This role should have all of the normal permissions for the adapter.

Role Path

If your IAM strategy uses special paths for IAM roles, that path should be entered here. In most AWS deployments, this field will be left empty.

External ID

If you use an external ID as an additional authentication factor during role inheritance, enter that external ID here between the double quotes. This external ID must be the same in all member accounts.

Region

Use this field in order to make our initial connection to the AWS APIs. This field can be left empty and, if so, we will assume us-east-1 for the initial connection. In most cases, you can leave this field empty.

Skip EC2 Verification

If you have no EC2 instances in the root organization account, you must set skip_ec2_verification to true.

Sample IAM Policy

This sample policy can be used to enable the permissions required for this feature.

{
    "Statement": [
        {
            "Action": [
                "sts:AssumeRole"
            ],
            "Effect": "Allow",
            "Resource": "arn:aws:iam::*:role/Axonius-Adapter",
            "Sid": "AssumeRoleInAllMemberAccounts"
        }
    ],
    "Version": "2012-10-17"
}

Follow this guide to configure AWS Organizations