Gateway Configuration with AWS KMS
Storing Keeper Gateway Configuration in AWS KMS
Overview
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 Key Management Service (KMS) Key
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.
Create Keeper Gateway Configuration
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.
Creating Secrets in AWS Secrets Manager
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.
Creating an AWS EC2 Instance
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.
Creating an IAM Role
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-2for 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".
Attaching the IAM Role to the EC2 Instance
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.
Testing EC2 Instance Access to the Secret
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.
Specifying the AWS Secrets Manager Key
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.
How to Specify the SM Key
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.
Configure Linux Service
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.
Last updated
