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:
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.
(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.
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:
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.
(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.
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):
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:
(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.
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
kcm:organizeThe 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
kcm:recordFlag 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.
In the container the files may show owned by "1000" or some other user ID.
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.
This change has the following result:
Updates the ownerships of existing files from the old UID of the
guacamoleuser to the specified value.Updates the UID of the
guacamoleuser 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
