Profile Command
Setup and initialization of the Keeper Secrets Manager device profile
profile
command
profile
commandDescription: Initialize and switch between device profiles. In order to support multiple environments on the same device, you can also switch between Secrets Manager device profiles.
Parameters:
Sub-command and options to run
format: ksm profile <sub-command>
Sub-Commands:
Sub-Command
Description
init
Initialize a new client device profile
setup
Setup a new profile from 3rd party external secrets manager like AWS.
list
List profiles that have been created, and note active profile
export
Export a configuration profile
import
Create a new configuration from an exported encrypted profile
active
Sets the active configuration profile
init
Initialize a client device profile.
The file keeper.ini
file will be created in your current working directory. For the Windows or macOS binary applications, the keeper.ini
will be created in the users home directory (${HOME} or $env:USERPROFILE
environment variables). The keeper.ini
can be moved to the following locations:
The path defined by the environmental variable
KSM_INI_DIR
The current directory
The user's home directory
${HOME}
${HOME}/.config/ksm
$env:USERPROFILE
Various system directories
/etc
/etc/ksm
/etc/keeper
$env:APPDATA/Keeper
$env:ProgamData/Keeper
$env:ProgramFiles/Keeper
Parameters:
-t, --token <token>
one-time access token-h, --hostname <XX>
destination regionDefaults to US region. Customers hosted in other regions must set this value:
US
(United States)EU
(Europe)AU
(Australia)JP
(Japan)CA
(Canada)US_GOV
(GovCloud)
--ini-file <FILENAME>
save the new profile to this file-p, --profile-name <NAME>
set profile name If not provided, the profile will be set as "default"
Typically, you will be initializing the KSM CLI with a token created in the vault or in Keeper Commander. For example:
To avoid exposing the token on the command line use KSM_CLI_TOKEN
environment variable. For example:
Usage of KSM_CLI_TOKEN
environment variable to provide one-time token allows for selecting a custom INI file and custom profile (to create/overwrite) and can be overridden by --token
option from command line.
As described in the Quick Start Guide, you can create a token from the Commander CLI or from the Keeper Vault interface. For example:
setup
Setup a new profile to be loaded from external storage like the AWS Secrets Manager. This is ideal when using Keeper Secrets Manager CLI from a cloud instance. Using this method of authentication adds additional layers of security.
There are 3 ways of integrating with external storage providers like AWS:
EC2 instance role (recommended)
AWS profile credentials
AWS custom keys
Method 1: EC2 instance role
For this method, you need to install Keeper Secrets Manager CLI on a EC2 instance which has been configured with a role that has permission to read specific AWS Secrets Manager secrets. We recommend setting up an EC2 role policy that has the least permission available, to only read specific keys. Learn more about AWS Secrets Manager access controls.
To initialize the KSM CLI profile on an EC2 instance using the AWS EC2 instance role:
This creates a keeper.ini file which defines the secret key in AWS. For example:
By default, the secret key is assumed to be called ksm-config
. You can specify a different key value by editing the keeper.ini file or using the --secret
option. Example:
Method 2: AWS profile credentials
The KSM CLI can be configured to use a specific AWS profile that has been previously initialized on this device with the aws configure
command.
For this method, the AWS profile credentials should be assigned to a role which is limited to only read specific keys from the AWS Secrets Manager. Learn more about AWS Secrets Manager access controls.
For example:
Method 3: AWS custom keys
The KSM CLI can be configured to use a specific AWS Access Key / Secret Key pair. In this scenario, the Access Key and Secret Key will be stored locally in the keeper.ini
file.
For example:
An additional flag --fallback
allows you to specify falling back to the default profile (from the AWS local configuration) if the initial credentials fail.
Finishing the KSM CLI setup
To complete the setup, a base64 KSM configuration value must be generated from the Keeper Vault interface or the Keeper Commander CLI. This is described in the Quick Start Guide.
For example, using the Commander CLI, this can be generated using a command such as the one below:
Copy the provided configuration for use in the next step.
In order for this KSM device to authenticate against Keeper Secrets Manager, the KSM configuration value in base64 format must be populated into the AWS Secrets Manager. For example, using the AWS CLI:
Now, you can verify that KSM CLI works and can access secrets from your vault using:
Additional setup options
--ini-file <FILENAME>
save the new profile to this file instead of keeper.ini.
-p, --profile-name <NAME>
set profile name. If not provided, the profile will be set as "default"
list
List all available profiles for the current Client Device.
ksm profile list
Example:
export
Export the current profile into a base64-encoded string.
ksm profile export [--plain] [--file-format] [PROFILE NAME]
optional parameters:
--plain
Export profile without base64-encoding the string.--file-format
Export a profile to a specific file format. Available formats are:ini - To be used by another instance of the CLI.
json - Can be used by the CLI and other Developer SDKs.
Example
Note: When using an external storage provider for KSM configuration, the profile will not be exportable.
import
Import a client device profile from an encrypted base64-encoded string.
ksm profile import [--output-file "INI filename"] <BASE64 CONFIG>
optional parameters:
--output-file <INI filename>
Where to create the INI configuration file. If not set, will be create in current directory.
active
Set the currently active profile for this client device.
ksm profile active <PROFILE NAME>
Example:
Profiles within Containers
If you are running the CLI inside of a containerized environment, you might not have the ability to initialize a profile. If no INI config file is found and the environment variable KSM_TOKEN is found, a default profile will be auto-generated. A INI config file will be created and stored in the current working directory. That can be overridden with the environment variable KSM_INI_DIR.
Default INI Filename
The default name of the ini file is keeper.ini
, however this can overridden by using the KSM_INI_FILE
environment variable. By using KSM_INI_DIR
and KSM_INI_FILE
environment variables you can completely change the location and name of the INI configuration file.
Last updated