One-Time Access Token

The Keeper Secrets Manager One-Time Access Token is used for initializing devices

Overview

Keeper Secrets Manager uses a "One-Time Access Token" to perform a key exchange and initialize a new client device that will access the Secrets Manager API. Each client device should be initialized with its own, individual One-Time Access Token.

One time access tokens can be generated using Keeper Commander or in the Keeper Vault. One time access tokens are generated when a client device is created.

The purpose of the One Time Access Token is to generate a Configuration, which is made up of several encryption keys and identifiers. Configurations are stored either locally in the secure storage of the device (such as macOS Keychain), or stored within the target CI/CD platform secrets storage.

Using Commander To Generate a Token

The Keeper Commander CLI supports "secrets-manager" commands which can manage KSM applications, devices and permissions.

1. Create an Application

If you already have an application that you would like to use, skip to step 3

Use secrets-manager app create to create a new Secrets Manager application

My Vault> secrets-manager app create DevOps
Application was successfully added

secrets-manager app list can be used to see a list of available applications.

My Vault> secrets-manager app list

List all Secrets Manager Applications

Title              UID
-----------------  ----------------------
DevOps             fe6mv_ZBLqca35dBUTdNeQ
Examples           Xym5lhpSidvtk9VlmV_3dQ
Github Actions     L5FqK5DUJhxeCXp50nSkuw
Jenkind            R2jMVW_QwL3FsCJziotpLQ

2. Associate the Application to Shared Folders or Records

You need to assign Shared Folders or records with the application in order to give it access to the vault records.

From Commander, use the following command to share with an application:

secrets-manager share add --app <APPLICATION NAME> --secret <FOLDER OR RECORD UID>

Optionally use the --editable flag to give the application edit permissions.

In the example below, "XXX" would be replaced by a record or shared folder UID

My Vault> secrets-manager share add --app DevOps --secret XXX --editable

Successfully added secrets to app uid=XXX, editable=True:
        RpdmKFgF5lpsaID3TcHu8A Shared Folder

To locate a Record UID or Folder UID, The ls -l command can be used to see a list of records, and folders with the corresponding UIDs

3. Create a Client Device

An application is made up of one or more Client Devices. At least one client device is required to access vault records.

Use the command secrets-manager client add --app <APPLICATION NAME> to create a new client device.

Optionally, --name <NAME> can be used to set a client device name and --unlock-ip can be used to allow any authenticated device to connect. By default, access is locked down based on external IP address of the client device.

My Vault> secrets-manager client add --app DevOps --name server1

Successfully generated Client Device
====================================

One-Time Access Token: US:19-V--cbg8P-o9OVDzMl_hWnrt-QE1eAMQHgSkQMUi0
Name: server1
IP Lock: Enabled
Token Expires On: 2021-10-01 11:14:18
App Access Expires on: Never

Note the One-Time Access Token is displayed when the client device is created.

Copy the one time access token from the output and use it to initialize a device from the Keeper Secrets Manager SDKs or integrations. Once the token is used on a target device, it cannot be used again. You can generate as many client devices as you need to access the records associated to the application.

Using The Keeper Vault to Generate a Token

1. Navigate to Secrets Manager

In the Keeper Vault, select Secrets Manager from the navigation menu.

2. Create a New Application or use Existing App

To create a new Secrets Manager Application and generate a one time token, first select "Create Application" from the Secrets Manager tab.

Assign a name for the new application (e.g. "Github Action") and select which folder(s) the application will have access to. Multiple folders can be selected.

You will be able to add additional folders and records to the application after it is created.

You can choose to give this application read-only or edit permissions. Optionally, check "Lock external WAN IP Address of device for initial request" to restrict the application's first client device to the first IP Address that connects to it.

3. Generate a One Time Access Token

Once the application exists, click "Generate Access Token" to generate the first client device and receive a one time token.

Copy the one-time access token from the output and use it to initialize a device from the Keeper Secrets Manager SDKs or integrations. Once the token is used on a target device, it cannot be used again. You can generate as many client devices as you need to access the records associated to the application.

Creating Additional Device Tokens

Devices are managed from the Secrets Manager > Applications > Devices tab. In order to create a new client device, click "Add Device". From this screen, you can select the 3 options for initializing the device.

• One-Time Access Token

• Base64 Configuration

• JSON Configuration

If you select the One-Time Access Token option, the target SDK or integration must use this token to generate the local configuration which is used for subsequent API calls. Alternatively, you can select the pre-built configuration in either base64 or JSON format.

Generating Configurations

Some of the 3rd party Keeper Secrets Manager integrations require pre-built configurations, instead of creating the configuration from a one-time access token.

The next section reviews how to create a Secrets Manager Configuration.