Connecting the AWS Adapter Using CloudFormation/Organizations

In large AWS deployments it can become difficult to maintain the accounts/roles that are needed by Axonius in order to collect AWS assets. If you are using the AWS Organizations service to manage your AWS accounts then Axonius can integrate with AWS Organizations and AWS CloudFormation to keep your accounts and asset inventory up to date with much less overhead.

This document is meant to give a high level overview of how the Axonius platform interacts with AWS when customers utilize AWS Organizations in their adapter configuration, as well as simplified instructions on how to set up your AWS accounts to support this configuration.

Architecture Overview

Throughout this document we will be referring to the following architecture components:

1. Launch Account - AWS account used to host an Axonius instance, an entry role, or that contains the IAM user/key Axonius uses to authenticate. The launch account can be any member account in your organization.

2. Organization Management Account - AWS account that is the Management account (or delegated administrator) for your AWS Organization.

3. One or more AWS Organizations member accounts.

4. Three distinct IAM entities:

   1. A ReadOnly role that exists in all accounts attached to the organization. This role is used to fetch asset data from each member account.

   2. An Organizations role on the AWS Organizations Management account. This role will have the ability to list the member accounts enrolled within the Organization.

   3. An initial access method which will exist in the Launch Account which will be a Cross-account role, Instance Profile, or IAM User. To know which initial access method is appropriate for your deployment, see the Selecting an Initial Access Method section below.

Selecting an Initial Access Method

Axonius is capable of initially accessing your AWS environment in three different ways:

1. Cross-account role - The best option for Axonius-hosted (SaaS) customers. Axonius will assume a role in the Launch Account directly and use that role for all other operations within your environment.

2. Instance profile - The best option for customers who host Axonius within their own AWS account. With this option the initial access method is tied directly to your Axonius Primary Instance, or Compute node.

3. IAM User - This method can be used in cases where your Axonius instance is neither Axonius-hosted SaaS or self-hosted within AWS, or in any other situation.

Axonius strongly recommends avoiding the use of IAM Users/Keys in cases where using a cross-account role or instance profile are available. For cases where the use of an IAM key is the only option to integrate with AWS, please ensure you review the documentation from AWS regarding AWS Identity and Access Management Best Practices.

Configuring AWS

In order to deploy Axonius using AWS CloudFormation/Organizations you can utilize the Axonius AWS CloudFormation Template:

This template is designed to be deployed as a CloudFormation StackSet so that it can be managed by AWS and deployed across your entire organization. Using a StackSet allows the required roles used by Axonius to be automatically deployed to all member accounts, including newly added accounts without the need for additional configuration changes in AWS or Axonius.

NOTE

Before you begin, you should know what Initial Access Method will be used to connect to AWS. If you are unsure please reach out to Axonius Support.

Step 1: Running the StackSet

1. Log in to your Delegated Administrator account for your AWS Organization. If you do not have a Delegated Administrator account you will need to log into and perform the following steps from your Organization Management Account.

2. Navigate to CloudFormation using the top search bar. Click StackSets from the left panel then Create Stackset.

3. Select the Service Managed Permissions and Upload a Template file radio buttons. Upload the CloudFormation template file and click Next to proceed to the Specify StackSet details stage of the StackSet deployment.

4. Give the StackSet any name and description of your choice. Expand the appropriate section below depending on what Initial Access method is being used to fill out the Parameters section:

   Cross-account role Method

   1. AWSConnectionMethod - from the dropdown, set this parameter to role.

   2. LaunchAccountID - a 12 digit AWS Account ID. It can be the account ID of any member account within the organization.

   3. AWSOrganizationsAccountID - a 12 digit AWS Account ID. This account ID must be the ID of either your Organizations Delegated Administrator or your Organizations Management account.

   4. ExternalID - Copy your Customer ID from your Axonius Instance. To find your Customer ID, log in to your Axonius instance and go to System Settings → About.

   5. SelfHosted - from the dropdown, set this parameter to AxoniusHosted

   Instance Profile Method

   1. AWSConnectionMethod - from the dropdown, set this parameter to role.

   2. LaunchAccountID - a 12 digit AWS Account ID. This must be the account in which Axonius (or a compute node for your Axonius platform) is currently running.

   3. AWSOrganizationsAccountID - a 12 digit AWS Account ID. This account ID must be the ID of either your Organizations Delegated Administrator or your Organizations Management account.

   4. SelfHosted - from the dropdown, set this parameter to SelfHosted

   IAM User Method

   1. AWSConnectionMethod - from the dropdown, set this parameter to user.

   2. LaunchAccountID - a 12 digit AWS Account ID. It can be the account ID of any member account within the organization.

   3. AWSOrganizationsAccountID - a 12 digit AWS Account ID. This account ID must be the ID of either your Organizations Delegated Administrator or your Organizations Management account.

5. Once the parameters have been filled out click Next to proceed to the Configure Stackset Options stage of the deployment.

6. Check the Acknowledgement box at the bottom of the page, then click Next.

7. In the Specify regions section, add us-east-1. If you are integrating a US GovCloud organization, use us-gov-east-1. Optionally, you can choose to deploy to and have Axonius retrieve asset data from a subset of your organization using the Deploy to organizational units (OUs) radio button. If selected, enter the OU(s) that contain your desired accounts. If you want Axonius to retrieve asset data from all Organization member accounts then leave the Deploy to organization radio button selected. Click Next.

8. The Review stage will summarize the configuration from the previous steps. Click Submit to initialize the StackSet.

Step 2: Running a Stack in the Organizations Management Account

1. Log in to your AWS Organizations Management account.

2. Click the region drop down at the top right of the AWS Console and select the us-east-1 region. If you are integrating with a US GovCloud organization, select us-gov-east-1.

3. Navigate to CloudFormation using the top search bar.

4. Click Stacks from the left panel then Create Stack. From the dropdown, select With new resources (standard).

5. Select the Upload a template file radio button. Upload the CloudFormation template file and click Next.

6. Give the Stack any name and description of your choice. Enter the parameters exactly as they were done within Step 1, then click Next.

7. Check the Acknowledgement box at the bottom of the page, then click Next.

8. The Review stage will summarize the configuration from the previous steps. Click Submit to initialize the Stack.

Step 3: Attaching an Instance Profile/Generating Access Keys

NOTE

This step is only required for customers who are using an IAM user/Instance Profile initial access method. If using an cross-account role then the configuration with AWS is already complete and you can proceed to Configuring the AWS Adapter in Axonius.

1. Expand the appropriate section below depending on what Initial Access method is being used:

   Instance Profile Method

   1. Log into the AWS Account ID that was indicated as the LaunchAccountID in Step 1.

   2. Navigate to EC2 using the top search bar.

   3. Click the region drop down at the top right of the AWS Console and select whichever region your Axonius system (or compute node) is hosted in.

   4. Select the your Axonius instance from the EC2 instances list, then click Actions → Security → Modify IAM Role.

   5. Choose the instance profile name that was indicated in Step 1 in the AccessName parameter. By default the name of the instance profile will be Axonius-Access. Click Update IAM role.

   IAM User Method

   1. Log into the AWS Account ID that was indicated as the LaunchAccountID in Step 1.

   2. Navigate to IAM using the top search bar.

   3. From the left menu, click Users.

   4. Click the user name that was indicated in Step 1 in the AccessName parameter. By default the name of the IAM user will be Axonius-Access.

   5. Click the Security Credentials tab.

   6. Under Access keys, click Create access key.

   7. From the list of radio buttons, choose Application running outside AWS and click next.

   8. Add a description of your choice, then click Create access key.

   9. The AWS Access Key ID and Secret will be displayed and downloadable as a CSV file. Save these in a secure location. They will be used in the Configuring the AWS Adapter in Axonius section.

Configuring the AWS Adapter in Axonius

At this point the work in AWS is complete. Let’s move on to configuring the connection within Axonius. How the connection is configured will again depend on your initial access method. In order to configure the connection we will be referencing many of the same values that were used within your StackSet parameters. If you can’t remember what parameters you used you can always look at them after deployment by going to CloudFormation → StackSets → [My StackSet Name] → Parameters.

Axonius uses an advanced configuration file to configure the AWS adapter. This is simply a JSON formatted document. Samples will be included in the documentation below, but be sure to replace any items with their respective values from your StackSet configuration. Each value that needs to be replaced will be enclosed in square brackets. Replace the entire item, including the brackets themselves. For instance, assuming the default role names are used [AccessName] would be replaced with Axonius-Access.

1. Expand the appropriate section below depending on what Initial Access method is being used:

{
"fetch_roles_from_organization": {
"organization_role_for_discovery": "arn:aws:iam::[AWSOrganizationsAccountID]:role/[OrganizationsRole]",
"role_name": "[ReadOnlyRole]"
},
"entry_point_role_arn": "arn:aws:iam::[AWSLaunchAccountID]:role/[AccessName]",
"entry_point_external_id": "[ExternalID]",
"skip_ec2_verification": true
}

{
"fetch_roles_from_organization": {
"organization_role_for_discovery": "arn:aws:iam::[AWSOrganizationsAccountID]:role/[OrganizationsRole]",
"role_name": "[ReadOnlyRole]"
},
"skip_ec2_verification": true
}

{
"fetch_roles_from_organization": {
"organization_role_for_discovery": "arn:aws:iam::[AWSOrganizationsAccountID]:role/[OrganizationsRole]",
"role_name": "[ReadOnlyRole]"
},
"skip_ec2_verification": true
}