# Apono Connector for AWS

## Overview

To integrate with AWS and start managing JIT access to AWS cloud resources, you must **first install a connector in your AWS environment**.

The connector should match the level of access management you want to achieve with Apono: on a single account or on the entire organization.

* To manage access to a single AWS account, install a connector on that account. Follow [this guide](#aws-account-connector).
* To manage access to all the accounts in the AWS organization:
  * Install a connector on the management account. Follow [this guide](#aws-organization-connector-on-the-management-account).\
    **OR**
  * Install a connector in any account with ECS or EKS and give it assumable permissions to the management account. Follow [this guide](#connector-with-delegated-permissions-to-the-aws-management-account).

{% hint style="info" %}
What's a connector? What makes it so secure?

The Apono Connector is an on-prem connection that can be used to connect resources to Apono and separate the Apono web app from the environment for maximal [security](https://docs.apono.io/docs/about-apono/security-and-architecture).

Read more about the recommended [AWS Installation Architecture](https://docs.apono.io/docs/about-apono/security-and-architecture#apono-and-aws).
{% endhint %}

First, decide if you want to integrate Apono with a specific AWS Account or with the entire Organization (containing multiple Accounts).

Follow the guides below depending on your selection.

***

### AWS Account connector

#### Prerequisites

* Administrator permissions to the AWS account you want to connect.
* VPC with outbound connectivity

#### 1. In Apono

1. Login to the Apono platform
2. Go to the Apono Integrations page
3. From the Catalog, pick AWS
4. Pick Account\
   ![](https://files.readme.io/5c631fa-image.png)
5. Install a new connector in AWS. Read more [here](https://app.apono.io/connectors/install).
6. Choose the desired deployment method\
   ![](https://files.readme.io/727751c-image.png)

#### 2. In CloudFormation

1. Choose Cloudformation
2. Click "Open Cloud Formation"
3. Sign in to your AWS user and click **Next**

![](https://files.readme.io/4869f8b-AWS.png)

4. Within the AWS create stack page, scroll down
5. Make sure you pick at least one Subnet and one VPC from the dropdown lists
6. Tick the acknowledge box and then select **Create Stack**

*Apono integrates with AWS natively, using AWS CloudFormation as a standard mechanism to deploy all required configurations including a Cross Account Role with Read permission, a SNS notification message, and the Apono Connector that runs using an AWS ECS on Fargate.*

***

### AWS Organization connector on the Management account

Apono integrates seamlessly with your AWS Organization, using CloudFormation to automate the deployment of all the necessary configurations:

* **Cross-account IAM role** with read permissions
* **Amazon SNS topic** for event notifications
* **Apono connector**, which runs on AWS Elastic Container Service (ECS)

Once installed, the connector syncs data from cloud applications and enables you to manage access to your Organization resources.

#### Prerequisites

<table><thead><tr><th width="199.59375">Item</th><th>Description</th></tr></thead><tbody><tr><td><strong>AWS IAM Role</strong></td><td><p>IAM role with permissions to manage resources in your AWS Organization</p><p>We recommend <a href="https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AdministratorAccess.html">AdministratorAccess</a> for connector deployment, but this policy is not required.</p><p><strong>Full AWS access is not granted to Apono</strong>.</p></td></tr><tr><td><strong>OrganizationID</strong></td><td><p>Unique identifier of the Organization that will be connected via the integration (ex. <code>o-k012345a67</code>)</p><p>Follow these steps to find your OrganizationID:</p><ol><li>In your AWS console settings, click <strong>Organization</strong>. The <strong>AWS accounts</strong> page appears.</li><li>In the left navigation, click <strong>Settings</strong>. The <strong>Settings</strong> page appears.</li><li>Under <strong>Organization details</strong>, copy your <strong>OrganizationID</strong>.</li></ol></td></tr><tr><td><strong>OrganizationUnitID</strong></td><td><p>Root ID for the AWS Organization Unit that will be connected via the integration (ex. <code>r-1a2b</code>)<br></p><p>Follow these steps to obtain your OrganizationUnitID:</p><ol><li>In your <strong>IAM Identity Center</strong>, expand <strong>Multi-account permissions</strong>.</li><li>Click <strong>AWS accounts</strong>. The <strong>AWS accounts</strong> page appears.</li><li>In the <strong>Organizational structure</strong> section, copy the ID from the <strong>Root</strong> folder. This is the parent organizational unit for all accounts in your organization.</li></ol></td></tr><tr><td><strong>VPC</strong></td><td>Virtual Private Cloud (VPC) with outbound connectivity</td></tr><tr><td><strong>Subnet</strong></td><td>One or more Subnet IDs within the selected VPC where the connector resources will run</td></tr><tr><td><strong>Permission</strong></td><td>Full access (Manage IAM) permissions to enable the connector to create and manage the required IAM resources during deployment</td></tr><tr><td><strong>EKS</strong> <strong>Access Entry</strong></td><td><p>(<strong>For EKS Namespaces and Groups</strong>) Connection between EKS permissions and an IAM identity<br></p><p>AWS-managed access entries link an IAM principal to a specific EKS cluster and define its level of Kubernetes access through associated access policies.</p><p>For <strong>each EKS cluster</strong> where resources, namespaces, or groups should be managed, add an access entry in the relevant AWS account and region:</p><ul><li><strong>IAM principal</strong>: Apono connector role</li><li><strong>Type</strong>: Standard</li><li><strong>AccessPolicies</strong>: <code>AmazonEKSClusterAdminPolicy</code></li><li><strong>AccessScope</strong>: Cluster</li></ul><p>This enables Apono to discover and manage Kubernetes namespaces within the cluster.</p><p><br>Learn how to <a href="https://docs.aws.amazon.com/eks/latest/userguide/creating-access-entries.html">create an access entry</a>.</p></td></tr><tr><td><strong>EKS Groups</strong></td><td><p>(<strong>For EKS Groups only</strong>) Enablement to manage custom Kubernetes RBAC roles through Apono</p><p>To grant access to custom Kubernetes and cluster roles using EKS Groups, you must have the following items:</p><ul><li><strong>Connected cluster</strong>: An EKS cluster must already be integrated and discoverable via the AWS Organization connector.</li><li><strong>Preconfigured RBAC roles in Kubernetes</strong>: Admins must create the relevant <code>Role</code>/<code>ClusterRole</code> and <code>RoleBinding</code>/<code>ClusterRoleBinding</code>. Apono does not create or manage these resources. <a href="https://kubernetes.io/docs/reference/access-authn-authz/rbac/">Learn more</a>.</li></ul><p><br>Please note the following limitations of EKS Groups:</p><ul><li>Groups with prefixes such as <code>eks:</code> and <code>system:</code> are <strong>not</strong> supported and are automatically filtered out.</li><li>AWS predefined access policies (such as <code>AmazonEKSViewPolicy</code>) are not applicable. Only custom Kubernetes RBAC roles are supported.</li></ul><p><strong>Minimum Required Version:</strong> 1.7.8</p></td></tr></tbody></table>

#### Install a connector

<figure><img src="https://1094436629-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fv6MBfUGvblSdAz31yJXm%2Fuploads%2Fgit-blob-2ff080544e2bee1128d5318f73483ab026bad1a6%2Finstalling-connector-ECS.png?alt=media" alt="" width="375"><figcaption><p><em>Installing a connector in Apono</em></p></figcaption></figure>

Follow these steps to install the connector:

1. Start integrating your [AWS Organization](https://docs.apono.io/docs/aws-integrations/integrate-an-aws-account-or-organization#integration-1) (steps **1-5**).
2. From the **Select Connector** dropdown menu, click **+ Add new connector**. The **Select connector installation strategy** section appears.

{% hint style="success" %}
If you choose an existing connector, we recommend [updating the connector](https://docs.apono.io/docs/aws-environment/apono-connector-for-aws/updating-a-connector-in-aws) in CloudFormation.
{% endhint %}

3. Click **Cloud installation > CloudFormation (ECS)**.

{% hint style="success" %}
You can also install the connector using [**CloudFormation (EKS)**](https://docs.apono.io/docs/aws-environment/apono-connector-for-aws/installing-a-connector-on-eks-using-cloudformation) or [**Terraform (ECS)**](https://docs.apono.io/docs/aws-environment/apono-connector-for-aws/installing-a-connector-on-aws-ecs-using-terraform).
{% endhint %}

4. Under **Follow these steps to install connector**, click **Open Cloud Formation**. AWS CloudFormation opens. The **Create stack** page appears with one of Apono's stack templates.

{% hint style="info" %}
If you are not already signed in, AWS will prompt you to log in to your AWS Management account.
{% endhint %}

5. From the settings dropdown at the top of the page, select your **Region**.
6. Enter the **Stack name**.
7. Define the following **Parameters**:
   1. Enter the **AponoConnectorId**. This can be any alphanumeric name to identify the connector.
   2. Enter your **OrganizationId**.
   3. Enter your **OrganizationUnitId**.
   4. From the **Permissions** dropdown menu, select **Full-Access (Manage IAM)**.
   5. Select one or more **SubnetIDs**.
   6. Select one or more **VpcId** parameters.
8. Under **Capabilities**, select **I acknowledge that AWS CloudFormation might create IAM resources with custom names**.
9. Click **Create stack**.
10. On the [**Connectors**](https://app.apono.io/connectors) page, verify that the connector has been deployed.
11. [Complete the integration](https://docs.apono.io/docs/aws-integrations/integrate-an-aws-account-or-organization#integration-1) (steps **6-10**).

***

### Connector with IAM role permissions for AWS Organization management

You can install a connector with assumable permissions to the AWS Management account using either AWS Elastic Container Service (ECS) or Elastic Kubernetes Service (EKS) in CloudFormation.

Once installed, the connector syncs data from cloud applications and enables you to manage access permissions through access flows within Amazon ECS or EKS.

#### Prerequisites

<table><thead><tr><th width="230.03125">Item</th><th>Description</th></tr></thead><tbody><tr><td><strong>AdminstratorAccess Policy</strong></td><td><p>AWS role with <a href="https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AdministratorAccess.html">AdministratorAccess</a> policy providing full access to AWS services and resources</p><p><strong>Full AWS access is not granted to Apono</strong>.</p></td></tr><tr><td><strong>OrganizationID</strong></td><td><p>Unique identifier of the AWS Organization that will be connected via the integration (ex. <code>o-k012345a67</code>)</p><p>Follow these steps to find your OrganizationID:</p><ol><li>In your AWS console settings, click <strong>Organization</strong>. The <strong>AWS accounts</strong> page appears.</li><li>In the left navigation, click <strong>Settings</strong>. The <strong>Settings</strong> page appears.</li><li>Under <strong>Organization details</strong>, copy your <strong>OrganizationID</strong>.</li></ol></td></tr><tr><td><strong>OrganizationUnitID</strong></td><td><p>Root ID for the AWS Organization Unit that will be connected via the integration (ex. <code>r-1a2b</code>)</p><p>Follow these steps to obtain your OrganizationUnitID:</p><ol><li>In your <strong>IAM Identity Center</strong>, expand <strong>Multi-account permissions</strong>.</li><li>Click <strong>AWS accounts</strong>. The <strong>AWS accounts</strong> page appears.</li><li>In the <strong>Organizational structure</strong> section, copy the ID from the <strong>Root</strong> folder. This is the parent organizational unit for all accounts in your organization.</li></ol></td></tr><tr><td><strong>VPC</strong></td><td>Virtual Private Cloud (VPC) with outbound connectivity</td></tr><tr><td><strong>Subnet</strong></td><td>One or more Subnet IDs within the selected VPC where the connector resources will run</td></tr><tr><td><strong>Permission</strong></td><td>Full access (Manage IAM) permissions to enable the connector to create and manage the required IAM resources during deployment</td></tr></tbody></table>

#### Install the connector

<figure><img src="https://1094436629-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fv6MBfUGvblSdAz31yJXm%2Fuploads%2Fgit-blob-1479278043babb5ce080b7eaef617289f518536a%2Faws-assumable-connector.png?alt=media" alt="" width="375"><figcaption><p><em>Installing the connector in Apono</em></p></figcaption></figure>

Follow these steps to enable the connector to manage the entire AWS Organization:

1. On the [**Connectors**](https://app.apono.io/connectors) page, click **Install Connector**. The **Install Connector** page appears.
2. Under **Select connector installation strategy**, click **Cloud installation > AWS**. The permission options appear.
3. Click **No, Just Install the Connector**. The installation methods appear.

{% hint style="danger" %}
Do **not** select **Install and Connect AWS Account**. This option creates IAM roles in the member account that will conflict with the CloudFormation roles deployed in the Management account, causing the installation to fail.
{% endhint %}

4. Click the **CloudFormation (ECS)** or **CloudFormation (EKS)** installation method.

{% hint style="success" %}
You can also install the connector using [Terraform](https://docs.apono.io/docs/aws-environment/apono-connector-for-aws/installing-a-connector-on-aws-ecs-using-terraform).
{% endhint %}

5. Finish [installing the connector](https://docs.apono.io/docs/aws-environment/apono-connector-for-aws#id-2.-in-cloudformation) in CloudFormation for your AWS Account.
6. Once the connector is installed, copy the following values from CloudFormation.

<table><thead><tr><th width="230.09765625">Key</th><th>Location</th></tr></thead><tbody><tr><td><strong>AponoConnectorRoleArn</strong></td><td>On the <strong>Outputs</strong> tab, copy the <strong>Value</strong> for the <strong>AponoConnectorRoleArn</strong>.</td></tr><tr><td><strong>AponoConnectorId</strong></td><td>On the <strong>Parameters</strong> tab, copy the <strong>Value</strong> for the <strong>AponoConnectorId</strong> key.</td></tr></tbody></table>

7. Open [CloudFormation](https://console.aws.amazon.com/cloudformation/home#/stacks/quickcreate?templateURL=https%3A%2F%2Fapono-public.s3.amazonaws.com%2Fcloudformation%2Faws_organization_roles_only_integration_template.yml\&stackName=apono-aws-organization-integration) with your Management account. T**he Quick create stack** page appears.
8. Under **Parameters**, enter values for the following fields:
   1. **AponoConnectorId**: Value copied in step **6**.
   2. **ConnectorRoleArn**: Value copied in step **6**.
   3. **OrganizationId**: Organization ID copied during the [prerequisites](#prerequisites-2).
   4. **OrganizationUnitId**: Root ID copied during the [prerequisites](#prerequisites-2).
   5. From the **Permissions** dropdown menu, select **Full-Access (Manage IAM)**.
9. Under **Capabilities**, select **I acknowledge that AWS CloudFormation might create IAM resources with custom names**.
10. Click **Create stack**.
11. (Optional) On the **Outputs** tab, copy the **Value** for the **ManagementAccountRoleArnOutput**.

{% hint style="info" %}
When integrating an AWS Organization, you can paste the **ManagementAccountRoleArnOutput** value in the **Integration Config** settings to use the connector.
{% endhint %}

12. On the [**Connectors**](https://app.apono.io/connectors) page, verify that the connector has been deployed.
13. (Optional) Follow the steps to [integrate an AWS organization](https://docs.apono.io/docs/aws-integrations/integrate-an-aws-account-or-organization#integrate-an-aws-organization).