Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Installation and setup of the Keeper Gateway
The Keeper Gateway is a lightweight service that is installed on any Windows, Linux or macOS machine in order to execute rotation, discovery and connection tasks. A single Gateway can be used to communicate with any target infrastructure, both on-prem and cloud. For example, to rotate Active Directory accounts, the Gateway can be installed on any machine which can communicate to AD.
The Gateway preserves zero knowledge by performing all encryption and decryption of data locally. The Gateway uses Keeper Secrets Manager APIs to communicate with the Keeper cloud. A full description of the security architecture can be found here.
Windows (minimum OS version: Server 2016+ 1803 and newer)
Linux: Ubuntu, CentOS, and RedHat
macOS: 12+
Disk space required: 50MB
Memory: 1GB+
The Keeper Gateway generates encryption keys and a local Secrets Manager configuration that is used to authenticate with the Keeper cloud. The location depends on the context in which the Gateway is being run. It can be installed to the local user or installed as a service.
Login to the Keeper Web Vault or Desktop App
Create a Secrets Manager Application or select existing application
Click on the "Gateways" tab and click "Provision Gateway"
Select Windows, Mac or Linux install method
Install the Keeper Gateway using the provided method
During the creating of a Keeper Gateway, you have the choice to select "Lock external WAN IP Address of device for initial request". This will additionally IP lock the Gateway in addition to the authentication and encryption built into the service. This option is recommended as long as the external IP of your gateway machine is static.
Based on your Operating System, refer to the corresponding guide on installing the Keeper Gateway:
If you are installing on an EC2 instance in AWS, the Keeper Gateway can be configured to use the instance role for pulling its configuration from AWS Secrets Manager. Detailed instructions on this setup can be found here.
Keeper Admins can view and monitor all Gateways created under the enterprise environment. In the Secrets Manager section of the Keeper Admin Console, visit the "Gateways" tab.
Admins can see the status, creation date, and node assignment for all gateways. By clicking the Edit button, the Gateway name and Node can be modified, and a list of attached configurations and rotation history can be viewed.
Creating a one-time access token for installing the Keeper Gateway
In order to successfully install and setup up the Keeper Gateway, you need the Keeper Gateway's One Time Access Token. In order to generate this token, you will need to:
Prior to working with this guide, make sure that:
Keeper Secrets Manager is enabled for your enterprise and your role
Keeper Rotation is enabled for your role
Follow these steps to create a KSM Application:
In the Keeper Web Vault or Desktop App user interface, create a shared folder. This shared folder will contain the PAM records you will create as you are working through the use-case guides.
Navigate to the "Secret Managers" tab on the left and click on "Create Application" to create a KSM application
In the prompted window:
Enter the name of your KSM application
Choose the shared folder you have created in Step 1
Set the Record Permissions for Application to "Can Edit"
Click on "Generate Access Token" and then click on "OK"
You can safely ignore the first One-Time Access Token generated for the newly created KSM application. When creating a Keeper Gateway device, a different One-Time Access Token will be created.
For more information on KSM, visit:
Follow these steps to generate the Keeper Gateway's One Time Access Token:
After creating your KSM Application, select it, and navigate to the Gateways tab
In the Gateways tab, click on Provision Gateway
In the prompted screen do the following:
Enter your desired Gateway Name
Choose the operating system where this Gateway will be installed
After clicking Next, you will get a confirmation screen as shown in the screenshots below.
For Gateways that will be installed on windows, just the One-Time Access Token is shown:
For Gateways installed on Mac or Linux, you have the option of choosing one of the following:
New Gateway: This gives you the installation command with the One-Time Access Token
Existing Gateway: This gives you just the installation command
Important: Make sure to store this One Time Access Token for your records as this code is necessary to complete your Keeper Gateway Installation
Instructions for installing Keeper Gateway on Linux
This document contains information on how to install, configure, and update your Keeper Gateway on Linux.
Prior to proceeding with this document, make sure you generated a Keeper Gateway One-Time Access Token in your Vault. For more information, visit the following page:
Executing the following command will install the Keeper Gateway:
Executing the following command will install, initialize the Keeper Gateway, and run it as a service:
The gateway will be installed in the following location:
An alias gateway
is also created in the same directory
For managing the Keeper Gateway as a service, the following are created during the Gateway installation:
A keeper-gateway
folder
A keeper-gw
user
keeper-gateway folder
The keeper-gateway
folder contains the gateway configuration file and is created in the following location:
keeper-gw user
During the gateway installation, a new user, keeper-gw
, is created and added to the sudoers list in /etc/sudoers.d/.
The keeper-gw
user is the owner of the keeper-gateway folder and runs the gateway service. This is required when performing rotations on the gateway service and performing post-execution scripts.
The following commands can be executed to start, restart, or stop the Keeper Gateway as a service:
If the Keeper Gateway is installed and running as a service, the gateway configuration file is stored in the following location:
If the Keeper Gateway is installed locally and not running as a service, the gateway configuration file is stored in the following location:
Logs that contain helpful debugging information are automatically created and stored on the local machine.
If the gateway is running as a service, the gateway log files are stored in the following location:
If the gateway is not running as a service, the gateway log files are stored in the following location:
To add verbose debug logging, modify this file:
and add the -d
flag to the "gateway start" command, e.g:
Apply changes to the service:
Executing the following command will upgrade the Keeper Gateway:
Configure your Keeper Gateway installation to automatically check for updates, ensuring it stays up-to-date with the latest version. For more information, refer to the following:
Executing the following command will uninstall the Keeper Gateway:
Note: Replace XXXXX with the One-Time Access Token supplied by the Vault screen, more information
The Keeper Gateway configuration file contains a set of tokens that includes encryption keys, client identifiers, and destination server information used to authenticate and decrypt data from the Keeper Secrets Manager APIs. This configuration file is created from the Gateway and have a one to one relationship with .
Instructions for installing Keeper Gateway on Windows
This document contains information on how to install, configure, and update your Keeper Gateway on Windows.
Prior to proceeding with this document, make sure you generated a Keeper Gateway One-Time Access Token in your Vault. For more information, visit the following page:
https://keepersecurity.com/pam/keeper-gateway_windows_x86.exe
Upon installation of the service, select "Enter a Keeper One-Time Access Token" and supply the token provided by the Gateway setup screen on the Vault. After installation, the service will automatically start up and register with the Keeper cloud.
For information on how to generate the Keeper One-Time Access Token for the gateway, visit this page
The default installation location is the following:
Keeper recommends that the Keeper Gateway is installed as a service.
After selecting the installation location, you will be prompted with the following:
Setup Options Details:
Install Windows service - Installs the gateway as a window service
Use service account - If checked, use the specified service account, otherwise the account installing the gateway will be used
Start Windows service - if checked, start the Keeper Gateway service immediately after installation
Turn on debug logging - Enable verbose logging on the gateway log files
If "Use service account" is specified you will be prompted to enter the valid credentials of the desired service account:
The final step prior to successfully installing the Keeper Gateway as service is to enter the One-Time Access Token:
After clicking "Next", click "Install" in the prompted screen to successfully install the Keeper Gateway.
After installing and running the Keeper Gateway as a service, this service can be accessed and easily managed within the Windows Services Manager as "Keeper Gateway"
The Keeper Gateway configuration file contains a set of tokens that includes encryption keys, client identifiers, and destination server information used to authenticate and decrypt data from the Keeper Secrets Manager APIs. This configuration file is created from the Gateway One Time Access Tokens and have a one to one relationship with client devices.
If the Keeper Gateway is installed and running as a service, the gateway configuration file is stored in the following location:
If the Keeper Gateway is installed locally and not running as a service, the gateway configuration file is stored in the following location:
Logs that contain helpful debugging information are automatically created and stored on the local machine.
If the gateway is running as a service, the gateway log files are stored in the following location:
If the gateway is not running as a service, the gateway log files are stored in the following location:
To activate verbose logging:
Go to Windows Services > Keeper Gateway > Properties
Stop the service
Set the "Start parameters" to: --debug
or -d
Start the service by clicking on "Start" Do not click "OK" without first starting the service as it will not persist the Parameter setting
To upgrade, stop the service, install the latest executable and then start the service.
Back up your configuration .json file
Uninstall Keeper Gateway from "Add and remove programs"
Install Keeper Gateway (do not select "Enter a Keeper One-Time Access Token")
Configure your Keeper Gateway installation to automatically check for updates, ensuring it stays up-to-date with the latest version. For more information, refer to the following:
This section provides instructions for performing a silent installation of the Keeper Gateway on Windows systems. Silent installation allows the setup process to run in the background without displaying any user interface or messages.
To install Keeper Gateway silently, use the following command in your command prompt or script:
Replace <YOUR ONE-TIME ACCESS TOKEN>
with the actual token generated for your Keeper Gateway installation.
Existing Configuration: If you have previously installed Keeper Gateway and wish to use the existing configuration, you can bypass the token entry by using:
The following other options may be used:
Installation Log File: To generate a log file during the installation process, use the following option and specify the desired log file path:
If you prefer to run the Keeper Gateway under a specific Windows service account, use the following options to specify the account details:
Replace <ACCOUNT USERNAME>
and <ACCOUNT PASSWORD>
with the credentials of the service account you intend to use.
To enable the Auto Updater feature, allowing Keeper Gateway to automatically check for and apply updates, use the following option:
To uninstall the service:
Uninstall Keeper Gateway from "Add and remove programs"
If desired, delete the private configuration .json file
Advanced Keeper Gateway Configurations
This section will cover additional configurations users can make to modify the Keeper Gateway's default behavior.
Prior to proceeding with this guide, Keeper highly recommends you go over and setup one of the many supported Rotation use cases with Keeper Rotation:
The following are supported configurations for the Keeper Gateway:
Instructions for installing Keeper Gateway on MacOS
This document contains information on how to install, configure, and update your Keeper Gateway on MacOS.
Prior to proceeding with this document, make sure you generated a Keeper Gateway One-Time Access Token in your Vault. For more information, visit the following page:
Note: On macOS, the Gateway can only be installed as the local user and not as a service
Executing the following command will install the Keeper Gateway:
Executing the following command will install and initialize the Keeper Gateway:
The gateway will be installed in the following location:
An alias gateway
is also created:
After installation, To start the gateway on the local Terminal, type:
The gateway configuration file is stored in the following location:
Logs that contain helpful debugging information are automatically created and stored on the local machine.
The gateway log files are stored in the following location:
To upgrade the Keeper Gateway service:
Stop the current Gateway service
Install the new binary by executing the following command:
Executing the following command will uninstall the Keeper Gateway:
Instructions for installing and configuring the Auto Updater for the Keeper Gateway.
Auto Updater is supported only on Versions 1.4.0 or later of the Keeper Gateway
This document contains information on how to install & configure the Auto Updater for your Keeper Gateway installation. The Auto Updater makes periodic checks to update your Keeper Gateway to the latest version.
By default, the Auto Updater is disabled to prevent unexpected updates.
However, Keeper recommends enabling the Auto Updater to ensure you receive the most recent security and functionality enhancements. The Auto Updater verifies all Keeper Gateway downloads by checking the GPG signature of hash value, which are then utilized to checksum each file.
Ensure that you have administrative privileges on the system.
Version 1.4.0 or later of Keeper Gateway is required.
Execute the following command to download and run the installer. The --autoupdate
parameter is necessary for installing the auto updater in addition to Keeper Gateway.
Click the following link for details on other Linux installation options:
Install Auto Updater on existing installation by executing the following Keeper Gateway command:
Verify Installation (Optional)
Verify that the Auto Updater has been installed successfully by executing the following Keeper Gateway command:
Download the latest version of the Gateway installer which includes the Auto Updater from the official website.
Double-click the installer file to launch the installation wizard and follow the on-screen instructions. Click the following link for details on other Windows installation options:
During installation, check the box "Enable automatic updates". This setup option will create a new Task Scheduler task for auto updating the Gateway.
Install with existing Keeper Gateway
Open a command prompt as Administrator.
Install Auto Updater with the following Keeper Gateway command:
Verify Installation (Optional)
Open a command prompt as Administrator.
Verify that Auto Updater has been installed successfully by executing the following Keeper Gateway command:
Ensure that you have administrative privileges on the system.
Version 1.4.0 or later of Keeper Gateway is required.
Check the Auto Updater status by executing the following Keeper Gateway command:
Open a command prompt as Administrator
Check the Auto Updater status by executing the following Keeper Gateway command:
Ensure that you have administrative privileges on the system.
Version 1.4.0 or later of Keeper Gateway is required.
Check that Auto Updater is enabled using the steps in the Status section:
Edit the crontab that runs Auto Updater.
Here is an example of the default crontab entry that checks for updates every hour:
The first part 0 * * * *
is the crontab expression which will cause execution to occur every hour at 0 minutes.
The second part is the update command keeper-gateway-update
The option --trust
causes explicit trust of the Keeper Gateway GPG public key for verification of downloaded install files.
Configure the update frequency and other settings with the following steps:
Run taskschd.msc
to open Windows Task Scheduler.
In the left pane double-click on Task Scheduler Library -> Keeper -> Gateway -> AutoUpdate to show the Auto Updater Task.
In the upper middle pane double-click on the AutoUpdate Task with the name of the current version and click on the Triggers menu tab.
Click Edit...
to change when the Auto Updater checks for a new update to install. The default is to "Repeat task every 1 hour indefinitely" as shown below.
Ensure that you have administrative privileges on the system.
Version 1.4.0 or later of Keeper Gateway is required.
Remove Auto Updater by executing the following Keeper Gateway command:
Remove Auto Updater with the following steps:
Open a command prompt as Administrator.
Remove Auto Updater with the following Keeper Gateway command:
To assist with diagnosing issues or monitoring the status of updates, the Gateway Auto Updater generates two types of logs. These logs are subject to rotation policies to avoid overuse of disk space.
Log Location
All log files for Linux are located in /var/log/keeper-gateway
Log Files
Update Logs:
Any logs generated during an update will be timestamped and stored as update_YYYY-MM-DD_HH-MM-SS.log
.
Last Update Check:
The file last-update-check.log
contains information regarding the most recent check for updates.
The log files for the Gateway Auto Updater are located in \ProgramData\KeeperGateway\install
Log Files
Update Logs:
Any logs generated during an update will be timestamped and stored as YYYY-MM-DD_HH-MM-SS.log
Last Update Check:
The file last-update-check.log
contains information regarding the most recent check for updates.
Note: Replace XXXXX with the One-Time Access Token supplied by the Vault screen, more information
If the Gateway was never initialized, you will be prompted for an One-Time Access Token, more information
The Keeper Gateway configuration file contains a set of tokens that includes encryption keys, client identifiers, and destination server information used to authenticate and decrypt data from the Keeper Secrets Manager APIs. This configuration file is created from the Gateway and have a one to one relationship with .
Storing Keeper Gateway Configuration in AWS KMS
If the Keeper Gateway is installed on an Amazon Web Services (AWS) Elastic Compute Cloud (EC2) Instance, the corresponding Gateway configuration file can be stored in your AWS Key Management Service (KMS). This can be done by creating an Identity Access Management (IAM) Role Policy and assigning it to the EC2 Instance in order to provide the Keeper Gateway service with the required permissions to retrieve the necessary configuration from the AWS KMS. This method eliminates the need for storing a configuration file on the disk, and instead stores the configuration file in your AWS KMS.
AWS KMS is a fully managed service that makes it easy for you to create and control the cryptographic keys used to encrypt and decrypt your data. The service is integrated with other AWS services, making it easier to encrypt data and manage keys. You will need a AWS KMS key as part of this process, and it is recommended that you follow the principle of least privilege when assigning permissions to this key.
AWS Secrets Manager stores a base64 configuration string that is generated from a One-Time Token in Keeper Vault. In the Vault, generate a One-Time Token by creating new Gateway. Then convert the generated One-Time Token into a configuration using the Gateway command ott-init
. For example:
gateway ott-init [ONE-TIME-TOKEN]
Securely keep the output of this command. This value will be later entered into the AWS Secrets Manager as a value for a secret.
A. Navigate to the AWS Secrets Manager
Log in to your AWS Management Console. In the 'Services' dropdown, select 'Secrets Manager'. This will direct you to the AWS Secrets Manager home page.
B. Start the Process of Creating a Secret
On the AWS Secrets Manager home page, click on 'Store a new secret'. This will take you to a new page where you'll initiate the creation of a new secret.
C. Input Secret Details
Select 'Other type of secrets (e.g. API key)' as the secret type. Now, it's crucial to note that your Gateway Configuration in Base64 string format should be directly entered into the 'Plaintext' text box. This is important because AWS Secrets Manager supports both key/value and plaintext secret formats, but in this case, the plaintext format type will be used.
In the "Encryption Key" section, select the KMS key that will be used to encrypt the secret. If you don't have a KMS key already, AWS Secrets Manager can create one for you.
D. Secret Name and Description
Once Value of the "Plaintext" field is entered, click "Next" button. Provide a unique name for your secret. This name serves as the identifier for finding it within AWS Secrets Manager and will be used later when we will be configuring Gateway to use AWS Secrets Manager secret. Optionally provide a description that details the purpose of this AWS Secrets Manager secret or other related information.
E. Review and Store the Secret
Review all the details of the secret. Once everything is accurate, click on 'Store'. You have now successfully created a new secret in AWS Secrets Manager.
The EC2 instance you create should be a standard type that can have an IAM role assigned to it. There are various types of instances, each suited to different use cases, so choose one that fits your needs. The Gateway tool is compatible with any standard configurations, which gives you flexibility in your instance selection.
Create an IAM role that can be used by your EC2 instance to make API requests on your behalf. This IAM role should be configured with the least privileges necessary, allowing it to read only the necessary values from AWS Secrets Manager. This helps to reduce the potential for accidental exposure of sensitive information.
Navigate to IAM Dashboard - https://console.aws.amazon.com/iam/
Create new role
Type: "AWS service"
Common use case: EC2
Go to Step 2 and click on "Create policy" which should open a new tab.
Select "JSON" policy and enter the following:
Be sure to replace placeholders like "[REGION]", "[ACCOUNT ID]", and "[SECRET NAME WITH RAND]" with your actual AWS account details.
secretsmanager
: This is the specific AWS service that the resource belongs to. In this case, the resource is managed by AWS Secrets Manager.
[REGION]
: The region is the geographical AWS region where the resource is located. For example, us-west-2
for the US West (Oregon) region.
[ACCOUNT ID]
: This is the AWS account ID of the account that owns the resource. It's a 12-digit number unique to your AWS account.
secret
: This indicates the type of resource. In this case, the resource is a secret stored in AWS Secrets Manager.
[SECRET NAME WITH RAND]
: This is the name that you gave the secret when you created it in AWS Secrets Manager. Make sure that the name is the one found in the secret ARN, it should include random characters after a dash. Example: arn:aws:secretsmanager:us-east-1:134301558361:secret:keeperRotationGatewayConfig-Vwt7zX
Name the policy and click on "Create policy"
The last step is to attach this policy to the newly created role. Navigate back to the previous tab, refresh list of roles then attach this new policy to the role.
And lastly, on the last page give a name to the new role, make sure Step 2 has policy attached, and hit "Create role".
Now that your IAM role is properly configured, the next step is to attach it to your EC2 instance. This process involves standard AWS procedures to start an AWS EC2 Instance and attach a policy to it. For detailed steps, refer to the AWS EC2 documentation.
With the IAM role attached to your EC2 instance, it's important to validate that the setup has been done correctly. You can do this by running the AWS CLI command inside the EC2 instance to verify it has access to the secret:
Note: This command will output secret to the screen.
If you received successful output then that means that the EC2 instance was configured successfully and we are ready to configure the Keeper Gateway.
The AWS Secrets Manager Key is an identifier that is specified when starting the Gateway. It's used to enable the Gateway to access the secret from AWS Secrets Manager. If this key is not specified, the Gateway will not start. It's important to handle this key value securely and keep it confidential. Make sure that in this case the secret name will be the one that the key is named in AWS Secrets Manager, ie. without random characters that you specified before in the ARN.
A. Using Command Line Parameter: Here's a command that starts the Gateway in debug mode, logging all outputs to the log file. It uses the secret name provided:
B. Using Environment Variable: This is a method particularly useful when running the Gateway in a containerized environment. You set the environment variable AWS_KMS_SECRET_NAME
to [SECRET NAME] before starting the Gateway. This allows your application to read the SM Key directly from the environment variable.
Open the Keeper Gateway service unit file /etc/systemd/system/keeper-gateway.service
file and modify line that starts with ExecStart
change --config-file /etc/keeper-gateway/gateway-config.json
to --aws-kms-secret-name="[SECRET NAME]"
where [SECRET NAME]
is a name of the AWS KMS Secret.
The line should look like this:
Apply changes to the service:
Always adhere to the principle of least privilege when granting access permissions. This principle ensures that only the minimum necessary access is granted to perform an action.
Advanced configuration of the Keeper gateway with Keeper Vault custom fields
These configuration capabilities are functional and currently in an experimental phase, and we invite users to actively explore and utilize them. We are actively evaluating their functionality and performance, with the intention of considering them for official integration into our product in the future.
When setting up Rotation in your Keeper Vault, you store the credentials of your assets involved in rotation on their corresponding PAM Record Types. On these record types, you are able to create custom fields.
The additional gateway configurations will be defined with these custom fields on the PAM Record Types. The Keeper Gateway will then adjust its behavior based on the defined configurations.
The following tables lists all the possible configurations with custom fields:
Note:
The custom fields values are not case-sensitive.
Custom Field Name | Type | Default Value | Description |
---|---|---|---|
Shell
Text
None
Allows you to specify a custom shell path that the Gateway will use when executing rotation and post-rotation scripts. This gives you control over the environment in which these scripts run.
Example Value: C:\MY\SHLL
NOOP
Text
False
Allows you to control whether the Gateway performs the primary rotation operation or proceeds directly to execution of the post-rotation script.
If set to True
the Gateway will skip the rotation process and proceed directly in executing the post-rotation script(s).
Example Value: True
Kerberos
Text
False
Specifically designed for WinRM connections using Kerberos authentication.
By default, the Gateway automatically decides whether to use Kerberos based on certain rules, and If these conditions are met, the Gateway will attempt to use Kerberos for WinRM. However, if you encounter issues with this automatic detection, setting this field to True
will override the default behavior and force the Gateway to use Kerberos for WinRM.
Example Value: True
Private Key Type
Text
ssh-rsa
Gateway Version 1.3.4+
This custom field pertains to the type or algorithm of the private key stored in a record.
When adding a private key to a record, users do not need to take any additional action regarding its type or algorithm. The system is designed to automatically recognize and use the same algorithm as the existing private key during the rotation process. If the algorithm in use is ECDSA, the key size will also be preserved during the rotation.
Available Options if needed to overwrite the key type:
ssh-rsa
(Note: 4096 bits)
ssh-dss
(Note: 1024 bit, obsolete) ecdsa-sha2-nistp256
ecdsa-sha2-nistp384
ecdsa-sha2-nistp521
ssh-ed25519
Private Key Rotate
Text
True
Gateway Version 1.3.4+
TRUE
- (Default) If the custom field doesn't exist, the private key will be rotated if it exists.
FALSE
- The private key won't be rotated, even if it exists. Users should pick this if they wish to retain the private key in the record without any rotations.