1 of 4

Apono Connector for AWS

How to install a Connector on an AWS account to integrate an AWS Account or Organization with Apono

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.
To manage access to all the accounts in the AWS organization:
- Install a connector on the management account. Follow this guide. OR
- Install a connector in any account with ECS or EKS and give it delegated permissions to the management account. Follow this guide.

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.

Read more about the recommended AWS Installation Architecture.

How to install the Connector

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

Now, follow one of 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

Login to the Apono platform
Go to the Apono Integrations page
From the Catalog, pick AWS
Install a new connector in AWS. Read more here.

2. In CloudFormation

Choose Cloudformation
Click "Open Cloud Formation"
Sign in to your AWS user and click Next

Within the AWS create stack page, scroll down
Make sure you pick at least one Subnet and one VPC from the dropdown lists
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

Prerequisites

Administrator permissions to the AWS management account in the Organization.
VPC with outbound connectivity.

1. In Apono

Login to the Apono platform
Go to the Apono Integrations page
From the Catalog, pick AWS

2. In CloudFormation

Click "Open Cloud Formation"
Sign in to your AWS user and click Next

The new stack should be installed in the management account (which manages the organization's Identity Center)
Within the AWS create stack page, scroll down
Make sure you pick at least one Subnet and one VPC from the dropdown lists
Tick the acknowledge box and then select Create Stack

Verify that "trusted access" is activated for your organization. Read more here.

Connector with delegated permissions to the AWS management account

Prerequisites

Administrator permissions to the AWS management account in the Organization
For EKS: admin permissions on the cluster

Step 1: Deploy a connector in an AWS account

Using CloudFormation (ECS)

Open the CloudFormation in the member account you want to deploy at.
Fill the SubnetIDs, VpcId parameters
Create stack, and wait to finish
Copy the connector role from the "Outputs" tab

Using Helm (EKS)

Create an AWS role for the connector. Follow step 3 in this guide.
Set the following environment variables, to set the AWS Role for the connector deployed in EKS.

export AWS_ACCOUNT_ID=  
export AWS_ROLE_NAME=
export CONNECTOR_TOKEN=
export CONNECTOR_ID=

Where:

AWS_ACCOUNT_ID is the account where the EKS deployment is hosted

AWS_ROLE_NAME is the role defined for the connector in step 1

CONNECTOR_TOKEN is the token generated in the Apono UI when creating a new connector

[block:image] { "images": [ { "image": [ "https://files.readme.io/78e94c2-image.png", null, "" ], "align": "center", "sizing": "300px" } ] } [/block]

CONNECTOR_ID is the connector name. Set any name of your choosing.

Run the following helm command to deploy the connector

helm install apono-connector apono-connector --repo https://apono-io.github.io/apono-helm-charts \
    --set-string apono.token=$CONNECTOR_TOKEN \
    --set-string apono.connectorId=$CONNECTOR_ID \
    --set serviceAccount.awsRoleAccountId=$AWS_ACCOUNT_ID \
    --set serviceAccount.awsRoleName=$AWS_ROLE_NAME \
    --set serviceAccount.manageClusterRoles=false \
    --namespace apono-connector \
    --create-namespace

Copy the role given to the connector (arn:aws:iam::$AWS_ACCOUNT_ID:role/$AWS_ROLE_NAME)

Interested in HA for the connector?

Add this variable to the Helm chart to create one or more replicas of the Apono connector instance:

--set-string replicaCount=<number_of_replicas>

Step 2: Deploy roles in the Management Account (assumable by the connector)

Open CloudFormation in the AWS Management account using this link.
In "ConnectorRoleArn" parameter, paste the connector role from the previous step.
Fill the "OrganizationalUnitId" parameter.
Create stack, and wait to finish.
Copy the Management Account Role ARN from the "Outputs" tab.

Results

Verify that the Stackset was created successfully and that Cloudformation finished.

Then, In the Apono app, you will see the connector was found and a green checkmark indication.

Hurray!

You can now integrate an AWS Account or Organization!

Installing a connector on EKS Using Terraform

This guide is intended for admins managing a Connector in the environment

📘 You have chosen the advanced installation method
You can also easily connect AWS in Apono following this UI guide here

How to install the Connector on EKS Using Terraform

Prerequisites

Required CLI: terraform

Step 1 - Create Connector

Important: before you start, copy the connector Terraform params and export them in the terminal.

Step 2 - Configure Variables

variable "eks_cluster_name" {
  type    = string
  default = "PLEASE_REPLACE_WITH_CLUSTER_NAME"
}

variable "CONNECTOR_ID" {
  type    = string
  description = "Apono Connector ID"
}

variable "APONO_TOKEN" {
  type    = string
  description = "Apono authoriozatrion token"
  sensitive = true
}

variable "APONO_WEBSOCKET_URL" {
  type    = string
  description = "Apono websocket URL"
}

variable "aws_region" {
  type    = string
  default = "us-east-1"
}

variable "service_account_name" {
  type    = string
  default = "apono"
}

variable "namespace" {
  type    = string
  default = "apono"
}

Step 3 - Add necessary Terraform providers

** if you already use your own providers, you can skip this step

provider "aws" {
  alias  = "apono"
  region = var.aws_region
}

data "aws_eks_cluster" "cluster" {
  name     = var.eks_cluster_name
}

data "aws_eks_cluster_auth" "eks_cluster_auth" {
  name     = var.eks_cluster_name
}

data "aws_caller_identity" "aws_account" {
}

locals {
  aws_account_id = data.aws_caller_identity.aws_account.account_id
  oidc_provider = replace(data.aws_eks_cluster.cluster.identity[0].oidc[0].issuer, "https://", "")
  config_path = "~/.kube/config"
  config_context = "my-context" 
}

provider "kubernetes" {
  config_path = local.config_path
  config_context = local.config_context
}

provider "helm" {
  kubernetes {
    config_path = local.config_path
    config_context = local.config_context
  }
}

Run terraform init to validate it works

Step 4 - Add EKS cluster OIDC provider to your IAM

It's required that your EKS cluster OIDC provider will be added to your IAM. This step is required only once, and you may have already done it.

data "aws_eks_cluster" "eks_cluster" {
  name = var.eks_cluster_name
}

data "tls_certificate" "tls_cert" {
  url = data.aws_eks_cluster.eks_cluster.identity[0].oidc[0].issuer
}

resource "aws_iam_openid_connect_provider" "eks-oidc-provider" {
  client_id_list  = ["sts.amazonaws.com"]
  thumbprint_list = [data.tls_certificate.tls_cert.certificates[0].sha1_fingerprint]
  url             = data.aws_eks_cluster.eks_cluster.identity[0].oidc[0].issuer
}

Step 5 - Create the Connector IAM role

The Connector is deployed using helm and requires an IAM Role to be able to access tagged ASM secrets in the future.

// IAM role and access policy for apono tagged secrets
resource "aws_iam_role" "apono-connector" {
  name     = "${var.service_account_name}-${var.CONNECTOR_ID}"

  assume_role_policy = jsonencode({
    "Version" : "2012-10-17",
    "Statement" : [
      {
        "Effect" : "Allow",
        "Principal" : { "Federated" : "arn:aws:iam::${local.aws_account_id}:oidc-provider/${local.oidc_provider}" },
        "Action" : "sts:AssumeRoleWithWebIdentity",
        "Condition" : {
          "StringEquals" : { "${local.oidc_provider}:sub" : "system:serviceaccount:${var.namespace}:${var.service_account_name}" }
        }
      }
    ]
  })
  
  inline_policy {
    name = "apono-tagged-keys-access-policy"

    policy = jsonencode({
      Version = "2012-10-17"
      Statement = [
        {
          Effect = "Allow"
          Action = [ "kms:Sign" ]
          Resource = "*"
          Condition = { "StringEquals": {"aws:ResourceTag/apono-connector-read": "true"} }
        },
      ]
    })
  }
  
  inline_policy {
    name = "apono-tagged-secrets-access-policy"

    policy = jsonencode({
      Version = "2012-10-17"
      Statement = [
        {
          Effect = "Allow"
          Action = [ "secretsmanager:GetSecretValue", "secretsmanager:DescribeSecret"]
          Resource = "arn:aws:secretsmanager:*:${local.aws_account_id}:secret:*"
          Condition = { "StringEquals": {"aws:ResourceTag/apono-connector-read": "true"} }
        },
      ]
    })
  }

  // for IAM Managment
  inline_policy {
    name = "iam-access-policy"
    policy = jsonencode({
      Version = "2012-10-17"
      Statement = [
        {
            Effect = "Allow"
            Action = [
                "iam:ListPolicies",
                "iam:CreateInstanceProfile",
                "iam:ListGroups",
                "iam:ListInstanceProfiles"
            ],
            Resource = "*"
        },
        {
            Effect = "Allow"
            Action = [
                "iam:CreateInstanceProfile",
                "iam:GetRole",
                "iam:UpdateAssumeRolePolicy",
                "iam:ListRoleTags",
                "iam:TagRole",
                "iam:CreateRole",
                "iam:DeleteRole",
                "iam:AttachRolePolicy",
                "iam:PutRolePolicy",
                "iam:AddRoleToInstanceProfile",
                "iam:ListInstanceProfilesForRole",
                "iam:DetachRolePolicy",
                "iam:ListAttachedRolePolicies",
                "iam:DeleteRolePolicy",
                "iam:ListAttachedGroupPolicies",
                "iam:ListRolePolicies",
                "iam:GetRolePolicy",
                "iam:PassRole",
                "iam:GetInstanceProfile",
                "iam:CreateUser",
                "iam:CreateAccessKey",
                "iam:DeleteAccessKey",
                "iam:PutUserPolicy",
                "iam:DeleteUserPolicy",
                "iam:GetUser",
                "iam:GetUserPolicy",
                "iam:ListAttachedUserPolicies",
                "iam:ListUserPolicies",
                "iam:UpdateLoginProfile",
                "iam:ListAccessKeys",
                "iam:AttachUserPolicy",
                "iam:DetachUserPolicy",
                "iam:CreateLoginProfile"
            ]
            Resource = [
                "arn:aws:iam::*:instance-profile/*",
                "arn:aws:iam::*:role/*",
                "arn:aws:iam::*:group/*",
                "arn:aws:iam::*:user/*"
            ]
        }
      ]
    })
  }
  
  inline_policy {
    name = "ec2-policy"
    policy = jsonencode({
      Version = "2012-10-17"
      Statement = [{
        "Effect": "Allow",
        "Action": [ "ec2:DescribeInstances","ec2:DescribeTags","ec2:AssociateIamInstanceProfile" ],
        "Resource": "*"
      }]
    })
  }
}

data "aws_iam_policy" "SecurityAudit" {
  arn = "arn:aws:iam::aws:policy/SecurityAudit"
}

resource "aws_iam_role_policy_attachment" "connector-security-audit" {
  role       = "${aws_iam_role.apono-connector.name}"
  policy_arn = "${data.aws_iam_policy.SecurityAudit.arn}"
}

Step 6 - Deploy Apono Connector

locals {
  connector_helm_repo = "https://apono-io.github.io/apono-helm-charts/"
  connector_helm_chart = "apono-connector"
  connector_helm_chart_version = "<<helmVersion>>"
}

// agent deployment
resource "kubernetes_namespace_v1" "apono-namespace" {
  metadata {
    name = var.namespace
  }
}

resource "helm_release" "apono-connector" {
  name             = "apono-connector"
  repository       = local.connector_helm_repo
  chart            = local.connector_helm_chart
  version          = local.connector_helm_chart_version
  namespace        = kubernetes_namespace_v1.apono-namespace.metadata[0].name


  set {
    name = "serviceAccount.name"
    value = var.service_account_name
  }
  
  set {
    name = "serviceAccount.awsRoleAccountId"
    value = local.aws_account_id
  }
  
  set {
    name = "serviceAccount.awsRoleName"
    value = "${var.service_account_name}-${var.CONNECTOR_ID}"
  }

  set {
    name = "image.tag"
    value = "<<connectorVersion>>"
  }

  set {
    name  = "apono.token"
    value = var.APONO_TOKEN
  }

  set {
    name  = "apono.url"
    value = var.APONO_WEBSOCKET_URL
  }

  set {
    name  = "apono.connectorId"
    value = var.CONNECTOR_ID
  }
}

Validate the Connector is Connected

You can validate the Connector is installed in the Connector status page.

Updating a connector in AWS

Learn how to update a connector through the AWS CLI

Periodically, you may need to update your AWS connector to help maintain functionality, performance, and security.

This article explains how to update a connector through the AWS CLI and redeploy the CloudFormation stack with the latest connector template.

Prerequisites

Item

Description

Update a connector

Follow these steps to update a connector:

Copy the following Account level or Organization level AWS update script. Be sure to replace AWS_STACK_NAME with your AWS stack name.

Be sure to replace AWS_PROFILE and AWS_SERVER_REGION with your profile and region values.

At your AWS CLI prompt, enter the updated script from the previous step to initiate the update. The AWS CLI will return an object containing the StackId.
In CloudFormation, on the Stack Info tab, confirm that the update has completed:
2. Under the Stack name column, click the stack name.
3. On the Stack info tab, check the Status.

Troubleshooting

This section details common errors that can occur during the updating process. If an error occurs that is not listed below, please contact your Apono representative.

An error occurred (ValidationError) when calling the UpdateStack operation: Stack [stack name] does not exist.

This occurs when the incorrect stack name has been included in the update script.

Use the following steps to correct this error:

Installing a connector on AWS ECS using Terraform

Create a connector on Amazon Elastic Container Service

Connectors are secure on-prem components that link Apono and your resources:

No secrets are read, cached, or stored.
No account admin privileges need to be granted to Apono.
The connector contacts your secret store or key vault to sync data or provision access.

Once set up, this connector will enable you to sync data from cloud applications and grant and revoke access permissions through Amazon Elastic Container Service (ECS).

Prerequisites

Item

Description

Install a connector

Use the following steps to install an Apono connector for AWS on ECS:

At the shell prompt, define an environment variable named TF_VAR_APONO_TOKEN with your Apono token value.

export TF_VAR_APONO_TOKEN="<APONO_TOKEN>"
export TF_VAR_REGION="<AWS_REGION>"
export TF_VAR_CONNECTOR_ID="<APONO_CONNECTOR_NAME>"
export TF_VAR_VPC_ID="<AWS_VPC_ID>"
export TF_VAR_SUBNET_IDS="<["SUBNET_ID1","SUBNET_ID2"]>"
export TF_VAR_TAGS="<{tag1="value1"}>"

In a new or existing Terraform (.tf) file, add the following provider and module information to create a connector with permissions or without permissions.

When using the following snippets, be sure to use the correct value for assignPublicIp:

true: Set when a subnet has an Internet Gateway
false: Set shen a subnet has a NAT Gateway

Enables installing the connector in the cloud environment and managing access to resources, such as Amazon RDS, S3 buckets, EC2 machines, and self-hosted databases

Terraform

provider "aws" {
    region = "{var.REGION}"
}

module "apono-connector" {
    source = "github.com/apono-io/terraform-modules//aws/connector-with-permissions/stacks/apono-connector"
    connectorId = "{var.CONNECTOR_ID}"
    aponoToken = "{var.APONO_TOKEN}"
    vpcId = "{var.VPC_ID}"
    subnetIds = "{var.SUBNET_IDS}"
    assignPublicIp = true
    tags = "{var.TAGS}"
}

Enables installing the connector in the cloud environment but managing access to non-AWS resources, such as self-hosted databases

Terraform

provider "aws" {
    region = "{var.REGION}"
}

module "apono-connector" {
    source = "github.com/apono-io/terraform-modules//aws/connector-without-permissions/stacks/apono-connector"
    connectorId = "{var.CONNECTOR_ID}"
    aponoToken = "{var.APONO_TOKEN}"
    vpcId = "{var.VPC_ID}"
    subnetIds = "{var.SUBNET_IDS}"
    assignPublicIp = true
    tags = "{var.TAGS}"
}

At the Terraform CLI, download and install the provider plugin and module.

terraform init

Apply the Terraform changes. The proposed changes and a confirmation prompt will be listed.

terraform apply

Enter yes to confirm deploying the changes to your AWS account.
On the Connectors page, verify that the connector has been deployed.

FAQ

Can the Apono Terraform module be pinned to a version?

Yes. You can append the version number to the source location with the ?ref=vX.X.X query string.

The following example pins the version to 1.0.0 for a connector without permissions.

Terraform

provider "aws" {
    region = "{var.REGION}"
}

module "apono-connector" {
    source = "github.com/apono-io/terraform-modules//aws/connector-without-permissions/stacks/apono-connector"
    connectorId = "{var.CONNECTOR_ID}"
    aponoToken = "{var.APONO_TOKEN}"
    vpcId = "{var.VPC_ID}"
    subnetIds = "{var.SUBNET_IDS}"
    assignPublicIp = true
    tags = "{var.TAGS}"
}

Installing a connector on EKS Using Terraform

This guide is intended for admins managing a Connector in the environment

📘 You have chosen the advanced installation method
You can also easily connect AWS in Apono following this UI guide here

How to install the Connector on EKS Using Terraform

Prerequisites

Required CLI: terraform

Step 1 - Create Connector

Important: before you start, copy the connector Terraform params and export them in the terminal.

Step 2 - Configure Variables

variable "eks_cluster_name" {
  type    = string
  default = "PLEASE_REPLACE_WITH_CLUSTER_NAME"
}

variable "CONNECTOR_ID" {
  type    = string
  description = "Apono Connector ID"
}

variable "APONO_TOKEN" {
  type    = string
  description = "Apono authoriozatrion token"
  sensitive = true
}

variable "APONO_WEBSOCKET_URL" {
  type    = string
  description = "Apono websocket URL"
}

variable "aws_region" {
  type    = string
  default = "us-east-1"
}

variable "service_account_name" {
  type    = string
  default = "apono"
}

variable "namespace" {
  type    = string
  default = "apono"
}

Step 3 - Add necessary Terraform providers

** if you already use your own providers, you can skip this step

provider "aws" {
  alias  = "apono"
  region = var.aws_region
}

data "aws_eks_cluster" "cluster" {
  name     = var.eks_cluster_name
}

data "aws_eks_cluster_auth" "eks_cluster_auth" {
  name     = var.eks_cluster_name
}

data "aws_caller_identity" "aws_account" {
}

locals {
  aws_account_id = data.aws_caller_identity.aws_account.account_id
  oidc_provider = replace(data.aws_eks_cluster.cluster.identity[0].oidc[0].issuer, "https://", "")
  config_path = "~/.kube/config"
  config_context = "my-context" 
}

provider "kubernetes" {
  config_path = local.config_path
  config_context = local.config_context
}

provider "helm" {
  kubernetes {
    config_path = local.config_path
    config_context = local.config_context
  }
}

Run terraform init to validate it works

Step 4 - Add EKS cluster OIDC provider to your IAM

It's required that your EKS cluster OIDC provider will be added to your IAM. This step is required only once, and you may have already done it.

data "aws_eks_cluster" "eks_cluster" {
  name = var.eks_cluster_name
}

data "tls_certificate" "tls_cert" {
  url = data.aws_eks_cluster.eks_cluster.identity[0].oidc[0].issuer
}

resource "aws_iam_openid_connect_provider" "eks-oidc-provider" {
  client_id_list  = ["sts.amazonaws.com"]
  thumbprint_list = [data.tls_certificate.tls_cert.certificates[0].sha1_fingerprint]
  url             = data.aws_eks_cluster.eks_cluster.identity[0].oidc[0].issuer
}

Step 5 - Create the Connector IAM role

The Connector is deployed using helm and requires an IAM Role to be able to access tagged ASM secrets in the future.

// IAM role and access policy for apono tagged secrets
resource "aws_iam_role" "apono-connector" {
  name     = "${var.service_account_name}-${var.CONNECTOR_ID}"

  assume_role_policy = jsonencode({
    "Version" : "2012-10-17",
    "Statement" : [
      {
        "Effect" : "Allow",
        "Principal" : { "Federated" : "arn:aws:iam::${local.aws_account_id}:oidc-provider/${local.oidc_provider}" },
        "Action" : "sts:AssumeRoleWithWebIdentity",
        "Condition" : {
          "StringEquals" : { "${local.oidc_provider}:sub" : "system:serviceaccount:${var.namespace}:${var.service_account_name}" }
        }
      }
    ]
  })
  
  inline_policy {
    name = "apono-tagged-keys-access-policy"

    policy = jsonencode({
      Version = "2012-10-17"
      Statement = [
        {
          Effect = "Allow"
          Action = [ "kms:Sign" ]
          Resource = "*"
          Condition = { "StringEquals": {"aws:ResourceTag/apono-connector-read": "true"} }
        },
      ]
    })
  }
  
  inline_policy {
    name = "apono-tagged-secrets-access-policy"

    policy = jsonencode({
      Version = "2012-10-17"
      Statement = [
        {
          Effect = "Allow"
          Action = [ "secretsmanager:GetSecretValue", "secretsmanager:DescribeSecret"]
          Resource = "arn:aws:secretsmanager:*:${local.aws_account_id}:secret:*"
          Condition = { "StringEquals": {"aws:ResourceTag/apono-connector-read": "true"} }
        },
      ]
    })
  }

  // for IAM Managment
  inline_policy {
    name = "iam-access-policy"
    policy = jsonencode({
      Version = "2012-10-17"
      Statement = [
        {
            Effect = "Allow"
            Action = [
                "iam:ListPolicies",
                "iam:CreateInstanceProfile",
                "iam:ListGroups",
                "iam:ListInstanceProfiles"
            ],
            Resource = "*"
        },
        {
            Effect = "Allow"
            Action = [
                "iam:CreateInstanceProfile",
                "iam:GetRole",
                "iam:UpdateAssumeRolePolicy",
                "iam:ListRoleTags",
                "iam:TagRole",
                "iam:CreateRole",
                "iam:DeleteRole",
                "iam:AttachRolePolicy",
                "iam:PutRolePolicy",
                "iam:AddRoleToInstanceProfile",
                "iam:ListInstanceProfilesForRole",
                "iam:DetachRolePolicy",
                "iam:ListAttachedRolePolicies",
                "iam:DeleteRolePolicy",
                "iam:ListAttachedGroupPolicies",
                "iam:ListRolePolicies",
                "iam:GetRolePolicy",
                "iam:PassRole",
                "iam:GetInstanceProfile",
                "iam:CreateUser",
                "iam:CreateAccessKey",
                "iam:DeleteAccessKey",
                "iam:PutUserPolicy",
                "iam:DeleteUserPolicy",
                "iam:GetUser",
                "iam:GetUserPolicy",
                "iam:ListAttachedUserPolicies",
                "iam:ListUserPolicies",
                "iam:UpdateLoginProfile",
                "iam:ListAccessKeys",
                "iam:AttachUserPolicy",
                "iam:DetachUserPolicy",
                "iam:CreateLoginProfile"
            ]
            Resource = [
                "arn:aws:iam::*:instance-profile/*",
                "arn:aws:iam::*:role/*",
                "arn:aws:iam::*:group/*",
                "arn:aws:iam::*:user/*"
            ]
        }
      ]
    })
  }
  
  inline_policy {
    name = "ec2-policy"
    policy = jsonencode({
      Version = "2012-10-17"
      Statement = [{
        "Effect": "Allow",
        "Action": [ "ec2:DescribeInstances","ec2:DescribeTags","ec2:AssociateIamInstanceProfile" ],
        "Resource": "*"
      }]
    })
  }
}

data "aws_iam_policy" "SecurityAudit" {
  arn = "arn:aws:iam::aws:policy/SecurityAudit"
}

resource "aws_iam_role_policy_attachment" "connector-security-audit" {
  role       = "${aws_iam_role.apono-connector.name}"
  policy_arn = "${data.aws_iam_policy.SecurityAudit.arn}"
}

Step 6 - Deploy Apono Connector

locals {
  connector_helm_repo = "https://apono-io.github.io/apono-helm-charts/"
  connector_helm_chart = "apono-connector"
  connector_helm_chart_version = "<<helmVersion>>"
}

// agent deployment
resource "kubernetes_namespace_v1" "apono-namespace" {
  metadata {
    name = var.namespace
  }
}

resource "helm_release" "apono-connector" {
  name             = "apono-connector"
  repository       = local.connector_helm_repo
  chart            = local.connector_helm_chart
  version          = local.connector_helm_chart_version
  namespace        = kubernetes_namespace_v1.apono-namespace.metadata[0].name


  set {
    name = "serviceAccount.name"
    value = var.service_account_name
  }
  
  set {
    name = "serviceAccount.awsRoleAccountId"
    value = local.aws_account_id
  }
  
  set {
    name = "serviceAccount.awsRoleName"
    value = "${var.service_account_name}-${var.CONNECTOR_ID}"
  }

  set {
    name = "image.tag"
    value = "<<connectorVersion>>"
  }

  set {
    name  = "apono.token"
    value = var.APONO_TOKEN
  }

  set {
    name  = "apono.url"
    value = var.APONO_WEBSOCKET_URL
  }

  set {
    name  = "apono.connectorId"
    value = var.CONNECTOR_ID
  }
}

Validate the Connector is Connected

You can validate the Connector is installed in the Connector status page.

Apono Connector for AWS

How to install a Connector on an AWS account to integrate an AWS Account or Organization with Apono

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.
To manage access to all the accounts in the AWS organization:
- Install a connector on the management account. Follow this guide. OR
- Install a connector in any account with ECS or EKS and give it delegated permissions to the management account. Follow this guide.

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.

Read more about the recommended AWS Installation Architecture.

How to install the Connector

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

Now, follow one of 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

Login to the Apono platform
Go to the Apono Integrations page
From the Catalog, pick AWS
Pick Account
Install a new connector in AWS. Read more here.
Choose the desired deployment method

2. In CloudFormation

Choose Cloudformation
Click "Open Cloud Formation"
Sign in to your AWS user and click Next

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

AWS Organization Connector on the management account

Prerequisites

Administrator permissions to the AWS management account in the Organization.
VPC with outbound connectivity.

1. In Apono

Login to the Apono platform
Go to the Apono Integrations page
From the Catalog, pick AWS
Pick Organization
Choose Cloudformation

2. In CloudFormation

Click "Open Cloud Formation"
Sign in to your AWS user and click Next

The new stack should be installed in the management account (which manages the organization's Identity Center)
Within the AWS create stack page, scroll down
Make sure you pick at least one Subnet and one VPC from the dropdown lists
Tick the acknowledge box and then select Create Stack

Verify that "trusted access" is activated for your organization. Read more here.

Connector with delegated permissions to the AWS management account

Prerequisites

Administrator permissions to the AWS management account in the Organization
For EKS: admin permissions on the cluster

Step 1: Deploy a connector in an AWS account

Using CloudFormation (ECS)

Open the CloudFormation in the member account you want to deploy at.
Fill the SubnetIDs, VpcId parameters
Create stack, and wait to finish
Copy the connector role from the "Outputs" tab

Using Helm (EKS)

Create an AWS role for the connector. Follow step 3 in this guide.
Set the following environment variables, to set the AWS Role for the connector deployed in EKS.

export AWS_ACCOUNT_ID=  
export AWS_ROLE_NAME=
export CONNECTOR_TOKEN=
export CONNECTOR_ID=

Where:

AWS_ACCOUNT_ID is the account where the EKS deployment is hosted

AWS_ROLE_NAME is the role defined for the connector in step 1

CONNECTOR_TOKEN is the token generated in the Apono UI when creating a new connector

[block:image] { "images": [ { "image": [ "https://files.readme.io/78e94c2-image.png", null, "" ], "align": "center", "sizing": "300px" } ] } [/block]

CONNECTOR_ID is the connector name. Set any name of your choosing.

Run the following helm command to deploy the connector

helm install apono-connector apono-connector --repo https://apono-io.github.io/apono-helm-charts \
    --set-string apono.token=$CONNECTOR_TOKEN \
    --set-string apono.connectorId=$CONNECTOR_ID \
    --set serviceAccount.awsRoleAccountId=$AWS_ACCOUNT_ID \
    --set serviceAccount.awsRoleName=$AWS_ROLE_NAME \
    --set serviceAccount.manageClusterRoles=false \
    --namespace apono-connector \
    --create-namespace

Copy the role given to the connector (arn:aws:iam::$AWS_ACCOUNT_ID:role/$AWS_ROLE_NAME)

Interested in HA for the connector?

Add this variable to the Helm chart to create one or more replicas of the Apono connector instance:

--set-string replicaCount=<number_of_replicas>

Step 2: Deploy roles in the Management Account (assumable by the connector)

Open CloudFormation in the AWS Management account using this link.
In "ConnectorRoleArn" parameter, paste the connector role from the previous step.
Fill the "OrganizationalUnitId" parameter.
Create stack, and wait to finish.
Copy the Management Account Role ARN from the "Outputs" tab.

Results

Verify that the Stackset was created successfully and that Cloudformation finished.

Then, In the Apono app, you will see the connector was found and a green checkmark indication.

Hurray!

You can now integrate an AWS Account or Organization!

Installing a connector on AWS ECS using Terraform

Create a connector on Amazon Elastic Container Service

Connectors are secure on-prem components that link Apono and your resources:

No secrets are read, cached, or stored.
No account admin privileges need to be granted to Apono.
The connector contacts your secret store or key vault to sync data or provision access.

Once set up, this connector will enable you to sync data from cloud applications and grant and revoke access permissions through Amazon Elastic Container Service (ECS).

Prerequisites

Item

Description

Install a connector

Use the following steps to install an Apono connector for AWS on ECS:

At the shell prompt, define an environment variable named TF_VAR_APONO_TOKEN with your Apono token value.

export TF_VAR_APONO_TOKEN="<APONO_TOKEN>"
export TF_VAR_REGION="<AWS_REGION>"
export TF_VAR_CONNECTOR_ID="<APONO_CONNECTOR_NAME>"
export TF_VAR_VPC_ID="<AWS_VPC_ID>"
export TF_VAR_SUBNET_IDS="<["SUBNET_ID1","SUBNET_ID2"]>"
export TF_VAR_TAGS="<{tag1="value1"}>"

In a new or existing Terraform (.tf) file, add the following provider and module information to create a connector with permissions or without permissions.

When using the following snippets, be sure to use the correct value for assignPublicIp:

true: Set when a subnet has an Internet Gateway
false: Set shen a subnet has a NAT Gateway

Enables installing the connector in the cloud environment and managing access to resources, such as Amazon RDS, S3 buckets, EC2 machines, and self-hosted databases

Terraform

provider "aws" {
    region = "{var.REGION}"
}

module "apono-connector" {
    source = "github.com/apono-io/terraform-modules//aws/connector-with-permissions/stacks/apono-connector"
    connectorId = "{var.CONNECTOR_ID}"
    aponoToken = "{var.APONO_TOKEN}"
    vpcId = "{var.VPC_ID}"
    subnetIds = "{var.SUBNET_IDS}"
    assignPublicIp = true
    tags = "{var.TAGS}"
}

Enables installing the connector in the cloud environment but managing access to non-AWS resources, such as self-hosted databases

Terraform

provider "aws" {
    region = "{var.REGION}"
}

module "apono-connector" {
    source = "github.com/apono-io/terraform-modules//aws/connector-without-permissions/stacks/apono-connector"
    connectorId = "{var.CONNECTOR_ID}"
    aponoToken = "{var.APONO_TOKEN}"
    vpcId = "{var.VPC_ID}"
    subnetIds = "{var.SUBNET_IDS}"
    assignPublicIp = true
    tags = "{var.TAGS}"
}

At the Terraform CLI, download and install the provider plugin and module.

terraform init

Apply the Terraform changes. The proposed changes and a confirmation prompt will be listed.

terraform apply

Enter yes to confirm deploying the changes to your AWS account.
On the Connectors page, verify that the connector has been deployed.

FAQ

Can the Apono Terraform module be pinned to a version?

Yes. You can append the version number to the source location with the ?ref=vX.X.X query string.

The following example pins the version to 1.0.0 for a connector without permissions.

Terraform

provider "aws" {
    region = "{var.REGION}"
}

module "apono-connector" {
    source = "github.com/apono-io/terraform-modules//aws/connector-without-permissions/stacks/apono-connector"
    connectorId = "{var.CONNECTOR_ID}"
    aponoToken = "{var.APONO_TOKEN}"
    vpcId = "{var.VPC_ID}"
    subnetIds = "{var.SUBNET_IDS}"
    assignPublicIp = true
    tags = "{var.TAGS}"
}