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:
Rotation Use CasesThe following are supported configurations for the Keeper Gateway:
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:
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.
Note:
The custom fields values are not case-sensitive.