One Time Access Token

Information about the One Time Access Token used to connect client devices to Keeper

About

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 create a "Configuration", which is made up of several encryption keys and identifiers. Configurations are stored either locally on the client device or within the target CI/CD platform.

Using Commander To Generate a Token

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

With a New Application

1. Navigate to Secrets Manager

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

2. Create a New Application

To create a new Secrets Manager Application and generate a one time token, first select "Create Application" from the Secrets Manager tab. The "Create Application" button appears on the top right side of the page, or in the middle if no Applications currently exist.

The Secrets Manager tab when no Applications exist yet

In the Add Application Form, create a name for the new application

The Add Application Form

Use the dropdown to select which shared folder to give the application access to. Multiple Folders can be selected.

Select one or more shared folders to give the application access to records

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 or edit permissions using the dropdown.

Choose Permissions and IP Lock options

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 you've configured the application, 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.

With an Existing Application

1. Navigate to Secrets Manager

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

2. Create a New Client Device on an Existing Application

To create a new client device and generate new one time tokens on existing Secrets Manager applications, first select the application to use from the list in the Secrets Manager tab.

The Secrets Manager tab with existing applications.

Selecting an application opens the details view, which shows the folders and records that this application has access to.

The shared folders and records that the application can access are listed

In order to create a new client device, first navigate to the "Devices" tab, and then click "Edit" and then the "+ Device" button.

The Device tab shows all the devices associated to this application

In the Add Device form, select a name for the new device. Optionally you can check "Lock external WAN IP Address of device for initial request" to restrict the client device to the first IP Address that connects to it.

The Add Device form

3. Generate a One Time Access Token

Click "Generate Access Token" to create the client device and see the one time token.

Copy the one time access token from this screen to use it with Keeper Secrets Manager SDKs and integrations, you will not be able to access this token in the future (but you can create additional client devices to generate more tokens).

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.