Gateway on AWS ECS

Instructions for installing Keeper Gateway on an AWS ECS

Overview

This document contains information on how to install, configure, and update your Keeper Gateway on an AWS ECS. The Keeper Gateway container is built upon the base image of Rocky Linux 9 and it is hosted in DockerHub.

Prerequisites

• VPC: A VPC with at least one Private Subnet

• Internet Access: The ECS host must have an outbound route to Keeper's endpoints via an Internet Gateway (IGW) or NAT Gateway. See the Gateway Network Configuration page.

• Instance Type: You must use an EC2 instance type with at least 8GB of RAM available. See sizing recommendations.

• Gateway scaling set to maximum instances: See below and Scaling and High Availability.

---

Create a Gateway

A new Gateway deployment can be created by clicking on Create New > Gateway from the Web Vault or Desktop App.

You can also create a Gateway and configuration file from the Commander CLI:

pam gateway new -n "<Gateway Name>" -a <Application Name or UID> -c b64

The Application names and UIDs can be found with secrets-manager app list

Download the Docker-compose YAML and save the Base64 configuration token.

---

AWS Infrastructure Setup

Create the Gateway Security Group

Navigate to EC2 > Security Groups > Create security group.

Name: [GATEWAY_SG_NAME] (e.g., keeper-gateway-sg).

Outbound Rules: HTTPS (443): Destination 0.0.0.0/0

Creating the Gateway Configuration Secret

Navigate to the AWS Secrets Manager console.

Choose "Store a new secret": Click the button to start the creation process.

Select Secret Type:

• Choose "Other type of secret".

Enter the Secret Value:

• Switch to the "Plaintext" tab.

• Delete any existing curly braces {} and paste your Base64 Configuration Token.

Encryption Key: Leave this as aws/secretsmanager

Click Next

Configure Secret Metadata:

• Secret name: Enter a descriptive name, such as keeper/gateway-config.

Store the Secret: Skip the optional rotation settings and click Store.

Copy the Secret ARN: Once saved, click on your new secret and copy the Secret ARN, we will require this later

• Example Format: arn:aws:secretsmanager:us-east-1:012345678901:secret:keeper/gateway-config-abc123

Create IAM Roles

ECS Instance Role

This role allows the EC2 instance to talk to the ECS cluster and enables AWS Systems Manager (SSM) for remote troubleshooting.

• Navigate to IAM > Roles > Create role.

• Select trusted entity: AWS Service.

• Service or use case: EC2.

• Add permissions (Attach these 2 Managed Policies):

  • AmazonEC2ContainerServiceforEC2Role

  • AmazonSSMManagedInstanceCore

• Role name: [INSTANCE_ROLE_NAME] (e.g., ecsInstanceRole).

• Create role.

Task Execution Role

This role is used by the ECS Agent to pull the image and decrypt the secret before the app starts

• Navigate to IAM > Roles and click Create role.

• Trusted entity type: Select AWS service.

• Service or use case: Select Elastic Container Service.

• Use Case: Search for and check:

  • AmazonECSTaskExecutionRolePolicy

• Click Next.

• Role name: e.g ecsgateway-execution-role.

• Click Create role.

• Add the Inline Policy for Secrets:

  • Find and click on your new ecsgateway-execution-role.

  • Click Add permissions > Create inline policy.

  • Switch to the JSON tab and paste the following (replacing YOUR_SECRET_ARN with the ARN that you copied earlier):

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "secretsmanager:GetSecretValue",
            "Resource": "YOUR_SECRET_ARN"
        }
    ]
}

• Click Review policy, name it KeeperSecretAccess, and click Create policy.

Task Role

This role is used by the application while it's running to manage your AWS resources.

• Navigate to IAM > Roles and click Create role.

• Trusted entity type: Select AWS service.

• Service or use case: Select Elastic Container Service, then Elastic Container Service Task. Click Next.

• Add permissions: Click Next (we will add a custom policy instead).

• Role name: e.g ecsgateway-task-role. Click Create role.

• Add the Inline Policy for Resource Management:

  • Click on the new ecsgateway-task-role.

  • Click Add permissions > Create inline policy.

  • Switch to the JSON tab and paste the following:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ec2:DescribeInstances",
                "iam:UpdateLoginProfile"
            ],
            "Resource": "*"
        }
    ]
}

---

Create the ECS Cluster

Navigate to ECS > Clusters > Create cluster.

Cluster name: [CLUSTER_NAME].

Select Fargate and Self-managed instances

Provisioning method: On demand

Container instance Amazon Machine Image (AMI): Amazon Linux 2023

Instance type: t3.large.

EC2 instance role: Select the ECS instance role you previously created

Desired Capacity: Set minimum 1 and desired maximum

Network settings: Select your VPC, Subnet and Security Group

Create: Click Create

---

Creating the Task Definition

• Open the ECS Console: Navigate to Amazon Elastic Container Service > Task Definitions.

• Start Creation: Click Create new task definition and select Create new task definition with JSON

• Paste & Edit: Paste the following template. Ensure sizing of CPU and memory meets your needs.

{
  "family": "[TASK_FAMILY_NAME]",
  "taskRoleArn": "arn:aws:iam::[ACCOUNT_ID]:role/ecsgateway-task-role",
  "executionRoleArn": "arn:aws:iam::[ACCOUNT_ID]:role/ecsgateway-execution-role",
  "networkMode": "bridge",
  "containerDefinitions": [
    {
      "name": "keeper-gateway",
      "image": "keeper/gateway:latest",
      "cpu": 2048,
      "memory": 8192,
      "essential": true,
      "privileged": true,
      "linuxParameters": {
        "sharedMemorySize": 2048
      },
      "environment": [
        { "name": "ACCEPT_EULA", "value": "Y" }
      ],
      "secrets": [
        {
          "name": "GATEWAY_CONFIG",
          "valueFrom": "arn:aws:secretsmanager:[REGION]:[ACCOUNT_ID]:secret:[SECRET_NAME]"
        }
      ],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/[TASK_FAMILY_NAME]",
          "awslogs-create-group": "true",
          "awslogs-region": "[REGION]",
          "awslogs-stream-prefix": "ecs"
        }
      }
    }
  ],
  "requiresCompatibilities": [
    "EC2"
  ]
}

Parameters

Update the sizing to your required Gateway size.

privileged: true: Required for Remote Browser Isolation (RBI). Chromium needs elevated permissions to manage the "sandboxed" browser namespaces.

sharedMemorySize: 2048: Docker only gives 64MB of shared memory; modern web pages require at least 2GB to render without crashing.

secrets block: This maps the GATEWAY_CONFIG environment variable to your AWS Secrets Manager ARN. The ECS agent handles the decryption automatically at runtime.

network Use bridge Mode to allow the container to share the host's networking stack for internal VPC discovery, but if your instances are in a private subnet, ensure your VPC Route Table directs outbound traffic to a NAT Gateway for secure internet connectivity to the Keeper Cloud and use awsvpc in the JSON.

---

Deploy & Verify

Create the ECS Service

The Service ensures that your Task Definition stays running.

• Open the ECS Console: Go to Clusters and select your cluster (e.g., Keeper-Cluster).

• Create Service: Under the Services tab, click Create.

• Environment Configuration:

  • Compute options: Select Launch type.

  • Launch type: Select EC2.

• Deployment Configuration:

  • Family: Select the ecsgatewaytask you created.

  • Revision: Select the latest revision.

  • Service name: keeper-gateway-service.

  • Desired tasks: Set to 1.

• Networking:

  • Security Group:

    • If Bridge Mode: Networking settings are inherited from the EC2 host. Skip SG selection in this wizard.

    • If awsvpc Mode: Select your VPC, Subnets, and the Gateway Security Group.

• Review and Create: Click Create.

---

Scaling and High Availability

Before deploying additional containers, you must configure the Gateway for scaling and high availability. Match this to your maximum defined instances in your Cluster configuration.

After logging into Keeper Commander, get a list of gateways from this command:

pam gateway list

Run the following command for the gateway being configured for scaling:

pam gateway set-max-instances -g <GATEWAY_UID> -m <MAX_INSTANCES>

• <GATEWAY_UID> is the UID of the Gateway you are scaling.

• <MAX_INSTANCES> is the maximum number of Gateway instances you want to allow.

Example: The following example allows up to 5 Gateway instances to run concurrently:

pam gateway set-max-instances -g Dmg5bh63p3Yj7ov738BTAw -m 5

For further information on gateway scaling and high availability

• Scaling and High Availability

---

Network Configuration

The Keeper Gateway establishes outbound-only connections and does not require any inbound firewall rules. The following outbound connections must be allowed:

Destination Endpoint	Ports Needed	More Info
Keeper Cloud keepersecurity.[x] Endpoints: US: .com EU: .eu AU: .com.au JP: .jp CA: .ca US_GOV: .us	TLS Port 443	Communicates with Keeper Cloud to access target infrastructure via native protocols (e.g., SSH, RDP)
Keeper Router connect.keepersecurity.[x] Endpoints: US: .com EU: .eu AU: .com.au JP: .jp CA: .ca US_GOV: .us	TLS Port 443	Communicates with Keeper Router to establish secure, real-time WebSocket connections
Keeper Stun/Turn Service krelay.keepersecurity.[x] Endpoints: US: .com EU: .eu AU: .com.au JP: .jp CA: .ca US_GOV: .us	TCP and UDP opened on Port 3478 Outbound access to TCP and UDP ports 49152 through 65535	Facilitates secure and encrypted WebRTC connections between end-user's vault and target systems via the Gateway

The Gateway preserves zero knowledge by performing all encryption and decryption of data locally. Keeper Secrets Manager APIs are used to communicate with the Keeper cloud.