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.

Amazon EC2 Discovery

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": "*"
        }
    ]
}

Add permissions

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.

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.