AWS EC2 Discovery

Discover and connect to EC2 instances

Overview

Keeper Connection Manager integrates with Amazon AWS to perform automatic discovery and connection to EC2 instances. This makes it fast and easy to connect to any EC2 instance in your cloud environment without having to manually configure anything. Like other connections, the EC2 instance connections are privileged, which means that the end-user does not have access to the underlying credentials.

Once activated, the EC2 instances will appear on the home screen of Keeper Connection Manager as seen below.

Features of the Integration

  • Instant discovery of EC2 instances in your AWS environment

  • Restrict permissions to a defined User Group

  • PEM files can be managed either on the filesystem or Keeper Vault

AWS Setup

In order to integrate Keeper Connection Manager with Amazon AWS, you'll need to create a user and assign a role policy that has permission to read instance information. A sample policy with minimal permissions is below:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "ec2:DescribeImages",
                "ec2:GetPasswordData",
                "ec2:DescribeInstances",
                "ec2:DescribeInstanceStatus"
            ],
            "Resource": "*"
        }
    ]
}

Assign the permission to a user and then create access keys.

Installation

Create Group

Before configuring the environment, ensure that you have a Group called "AWS EC2 Administrators" that are assigned to the users who will have access to discovered instances. The group name can also be customized through the AWS_DISCOVERY_ADMIN_GROUP environmental variable.

Auto Docker Method

To update your Keeper Connection Manager environment to support this feature, you'll need to edit the Docker Compose file located at /etc/kcm-setup/docker-compose.yml

(1) Stop the Containers

Before making changes on the local instance, it is a good idea to stop the containers.

sudo ./kcm-setup.run stop

(2) Edit the Docker Compose

Now, edit the docker compose file /etc/kcm-setup/docker-compose.yml and add the necessary required environmental variables and volume property. For example, see below.

 guacamole:
        image: keeper/guacamole:2
        environment:
            ....
            ....
            AWS_DISCOVERY_ACCESS_KEY_ID: XXXXXXXXXXXXXXX
            AWS_DISCOVERY_SECRET_KEY: XXXXXXXXXXXXXXXXXXXXXXX
            AWS_DISCOVERY_REGIONS: us-east-1
            AWS_DISCOVERY_ADMIN_GROUP: MyDevOpsGroup
            AWS_DISCOVERY_RECORD_CONNECTIONS_BY_DEFAULT: "true"
        volumes:
            ....
            - "/var/lib/guac_keys/:/etc/guacamole/cloud-connector-secrets/aws/:ro"

Store Credentials in the Keeper Vault (optional)

If you are using the Secrets Manager Vault connection with KCM, pem files or private keys can be pulled in dynamically from the Keeper Vault. If using this method, a volume mount for pem files does not need to be created. See the EC2 Cloud Connector documentation for more details.

Environmental Variables

AWS_DISCOVERY_ACCESS_KEY_ID

The access key ID for the AWS account that should be used to authenticate with AWS (Required).

AWS_DISCOVERY_SECRET_KEY

The secret key associated with the access key (Required).

AWS_DISCOVERY_REGIONS

Comma-separated list of regions to query for EC2 instances, such as us-west-1,us-east-1 (Required).

AWS_DISCOVERY_INSTANCE_BASE_PATH

The name of the organizational connection group that should be used to house the EC2 instances for convenience. By default, this will be “Amazon EC2“ (Optional).

AWS_DISCOVERY_ADMIN_GROUP

The name of the User Group in Keeper Connection Manager to require for any user to see the discovered EC2 instances. By default, this will be a group called “AWS EC2 Administrators". This can also be assigned to a Group that has been provisioned from Azure AD or other directory integrations.

AWS_DISCOVERY_RECORD_CONNECTIONS_BY_DEFAULT

If set to "true", screen recording will be enabled by default on all connections. Connection session recording can also be set at an individual machine level using the "kcm:record" EC2 instance tag, which can be set to "true" or "false" to explicitly enable or disable connection recording.

AWS_DISCOVERY_KSM_CONFIG

This Keeper Secrets Manager configuration provides integration with the Keeper vault to store PEM files. See the EC2 Cloud Connector documentation for more details.

(3) Copy .pem files into the guac_keys folder

In the Docker Compose example, you can see a volume mapping in the local file location /var/lib/guac_keys/. This is the folder in the KCM host where you must place all of the SSH key files required to establish a connection to the target instances. Windows instances must also copy the .pem file which is used to decrypt the Administrator password. KCM will select the proper file for establishing a connection based on the EC2 instance metadata.

See the Key File Permissions section below to review the file permissions and ensure that the key files are readable by the container.

If you are using the Secrets Manager Vault connection with KCM, pem files or private keys can be pulled in dynamically from the Keeper Vault. See the EC2 Cloud Connector documentation for more details.

(4) Upgrade the Container

To update all of the underlying software when using the Docker Automated Install method, run the below command:

sudo ./kcm-setup.run upgrade

This should automatically start the containers after the update.

Docker Compose Method

To update your Keeper Connection Manager environment to support this feature, you'll need to edit the "guacamole" section of your custom Docker Compose file.

(1) Stop the Containers

Before making changes on the local instance, it is a good idea to stop the containers, as you normally would do with docker-compose.

sudo docker-compose stop

(2) Edit the Docker Compose

Now, edit your docker compose file and add the necessary required environmental variables and volume property to the guacamole section. For example, see below.

 guacamole:
        image: keeper/guacamole:2
        environment:
            ....
            ....
            AWS_DISCOVERY_ACCESS_KEY_ID: XXXXXXXXXXXXXXX
            AWS_DISCOVERY_SECRET_KEY: XXXXXXXXXXXXXXXXXXXXXXX
            AWS_DISCOVERY_REGIONS: us-east-1
            AWS_DISCOVERY_ADMIN_GROUP: MyDevOpsGroup
            AWS_DISCOVERY_RECORD_CONNECTIONS_BY_DEFAULT: "true"
        volumes:
            ....
            - "/var/lib/guac_keys/:/etc/guacamole/cloud-connector-secrets/aws/:ro"

Environmental Variables

AWS_DISCOVERY_ACCESS_KEY_ID

The access key ID for the AWS account that should be used to authenticate with AWS (Required).

AWS_DISCOVERY_SECRET_KEY

The secret key associated with the access key (Required).

AWS_DISCOVERY_REGIONS

Comma-separated list of regions to query for EC2 instances, such as us-west-1,us-east-1 (Required).

AWS_DISCOVERY_INSTANCE_BASE_PATH

The name of the organizational connection group that should be used to house the EC2 instances for convenience. By default, this will be “Amazon EC2“ (Optional).

AWS_DISCOVERY_ADMIN_GROUP

The name of the User Group in Keeper Connection Manager to require for any user to see the discovered EC2 instances. By default, this will be a group called “AWS EC2 Administrators". This can also be assigned to a Group that has been provisioned from Azure AD or other directory integrations.

AWS_DISCOVERY_RECORD_CONNECTIONS_BY_DEFAULT

If set to "true", screen recording will be enabled by default on all connections. Connection session recording can also be set at an individual machine level using the "kcm:record" EC2 instance tag, which can be set to "true" or "false" to explicitly enable or disable connection recording.

(3) Copy .pem files into the guac_keys folder

In the Docker Compose example, you can see a volume mapping in the local file location /var/lib/guac_keys/. This is the folder in the KCM host where you must place all of the SSH key files required to establish a connection to the target instances. Windows instances must also copy the .pem file which is used to decrypt the Administrator password. KCM will select the proper file for establishing a connection based on the EC2 instance metadata.

See the Key File Permissions section below to review the file permissions and ensure that the key files are readable by the container.

(4) Upgrade the Container

To update all of the underlying software when using the Custom Docker Install method, upgrade your containers (assuming docker-compose.yml is in the current directory):

sudo docker-compose up -d

This should automatically start the containers after the update.

Advanced Linux Method

If you have installed Keeper Connection Manager using the Advanced Linux Install method, follow the steps below to activate the AWS EC2 discovery feature.

(1) Install the KCM Cloud Connector package

If you are using the Advanced Linux Install method, you can use yum install to install the KCM Cloud Connector package:

sudo yum install kcm-cloud-connector-aws

(2) Edit the Guacamole Properties File

Edit /etc/guacamole/guacamole.properties to include the mandatory and optional properties for the AWS Cloud Connector feature.

Available Properties

aws-discovery-access-key-id

The access key ID for the AWS account that should be used to authenticate with AWS (Required).

aws-discovery-secret-key

The secret key associated with the access key (Required).

aws-discovery-regions

Comma-separated list of regions to query for EC2 instances, such as us-west-1,us-east-1 (Required).

aws-discovery-instance-base-path

The name of the organizational connection group that should be used to house the EC2 instances for convenience. By default, this will be “Amazon EC2“ (Optional).

aws-discovery-admin-group

The name of the User Group in Keeper Connection Manager to require for any user to see the discovered EC2 instances. By default, this will be a group called “AWS EC2 Administrators". This can also be assigned to a Group that has been provisioned from Azure AD or other directory integrations (Optional).

aws-discovery-record-connections-by-default

If this property is set to "true", screen recording will be enabled by default on all connections (Optional).

Connection session recording can also be set at an individual machine level using the "kcm:record" EC2 instance tag, which can be set to "true" or "false" to explicitly enable or disable connection recording.

(3) Copy .pem files into the guac_keys folder

Add any required PEM files for private keys used to access Linux instances or decrypt Windows passwords to /etc/guacamole/cloud-connector-secrets/aws/

(4) Restart the Guacamole service

The new package will not take effect until the web application is restarted.

sudo systemctl restart guacamole

Instance Configuration with Tags

Connections can be configured using AWS EC2 tags assigned to each instance, in order to override and customize defaults and metadata.

Available Tags

kcm:username

The username that should be used when connecting to that instance.

This tag defines the login username for the instance, such as "centos" or "ec2-user". KCM attempts to select the correct username based on the AMI of the instance, but this can be used to correct a wrong assumption.

kcm:organize

The full path of the connection groups that should be used to organize the instance among other connections.

This tag Allows EC2 instances to be further organized beyond the connection group containing all instances. By default, all discovered instances will be placed within one top-level group of connections called "Amazon EC2", but will not be further organized. For example, if you set kcm:organize to something like "Databases", that instance will be located within a "Databases" connection group beneath "Amazon EC2". If you set kcm:organize to "Databases/MySQL", that instance will be within a "MySQL" connection group beneath "Databases", which itself would be beneath the main "Amazon EC2" group.

These connection groups do not need to already exist, and they actually exist only in memory (dynamically maintained by the EC2 support).

kcm:record

Flag to indicate if the instance connection sessions should be recorded.

This tag will override the default screen recording configuration of the KCM environment property aws-discovery-record-connections-by-default . If this tag exists with the value "true", the connection will be recorded, if "false", the connection will not be recorded. If the tag does not exist, or is set to any other value, the configured default recording behavior will be used.

Key File Permissions

Filename

  • The key files must be named exactly as referenced in the EC2 console, e.g. MyServer

  • The key files must be named with a .pem file extension, for example MyServer.pem

Permissions

The service in the "guacamole" docker container is run by the "guacamole" user. File permissions must be configured properly in the volume mount to ensure that the "guacamole" user has read access to the shared key files.

Example: On the host under /var/lib/guac_keys/ the files may be owned by ec2-user or whatever you have set up.

[root@xxx guac_keys]# ls -l
-rw------- 1 ec2-user ec2-user 1674 Jul 29 18:30 KCMDemoMac.pem
-rw------- 1 ec2-user ec2-user 1678 Jul 29 18:31 kcmdemo.pem
-rw------- 1 ec2-user ec2-user 1674 Jul 29 18:30 KCMDemoUbuntu.pem
-rw------- 1 ec2-user ec2-user 1674 Jul 29 18:30 KCMDemoWindows.pem
-rw------- 1 ec2-user ec2-user 1678 Jul 29 18:30 KCMKaliLinux.pem

In the container the files may show owned by "1000" or some other user ID.

[root@1dd8996db434 aws]# ls -l
-rw------- 1 1000 1000 1674 Jul 29 18:30 KCMDemoMac.pem
-rw------- 1 1000 1000 1674 Jul 29 18:30 KCMDemoUbuntu.pem
-rw------- 1 1000 1000 1674 Jul 29 18:30 KCMDemoWindows.pem
-rw------- 1 1000 1000 1678 Jul 29 18:30 KCMKaliLinux.pem
-rw------- 1 1000 1000 1678 Jul 29 18:31 kcmdemo.pem

There are two ways of solving the file permissions between the host and the guacamole container.

(1) You may use the environmental variables GUACAMOLE_UID and GUACAMOLE_GID in the guacamole docker definition to map the permission.

            GUACAMOLE_UID: 1000
            GUACAMOLE_GID: 1000

This change has the following result:

  • Updates the ownerships of existing files from the old UID of the guacamole user to the specified value.

  • Updates the UID of the guacamole user in the container to match that value.

(2) You can set wider group or world read permissions on the files from the host, but this is a decision based on your environment and security settings.

Ensure that you upgrade the containers for the change to take effect.

(kcm-setup.run upgrade or docker-compose up -d)

Key Files with Passphrases

If the .pem key is encrypted with a passphrase, you will be prompted for this when establishing the connection to the target.

Last updated