# AWS Secrets Manager Sync

![](https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FmqGoDtyLNTaLkl9bVfCi%2Fdatasource-ksm-aws.jpg?alt=media\&token=2703ca39-f530-4afd-9319-e86f445225e8)

## About

The Keeper Secrets Manager CLI tool [`sync` command](https://docs.keeper.io/en/keeperpam/secrets-manager/secrets-manager-command-line-interface/sync-command) allows you to push secrets from the Keeper Vault to a target **AWS Secrets Manager** account, overwriting the existing values in the target location. This allows the Keeper Vault to be the single source of truth for any services or scripts in AWS that utilize AWS Secrets Manager.

## Features

* Use secrets from the Keeper Vault as the source of truth for AWS Secrets Manager
* Seamlessly start using secrets from the Keeper Vault with your existing AWS scripts and services

## Prerequisites

* Keeper Secrets Manager access (See the [Quick Start Guide](https://docs.keeper.io/en/keeperpam/secrets-manager/quick-start-guide) for more details)
  * Secrets Manager add-on enabled for your Keeper subscription
  * Membership in a Role with the Secrets Manager enforcement policy enabled
* A Keeper [Secrets Manager Application](https://docs.keeper.io/en/keeperpam/about/terminology#application) with secrets shared to it
  * See the [Quick Start Guide](https://docs.keeper.io/en/keeperpam/quick-start-guide#2.-create-an-application) for instructions on creating an Application
* An AWS account with AWS Secrets Manager, and the ability to create IAM security credentials

## Setup

### 1. Configure Keeper Secrets Manager CLI

{% hint style="info" %}
You can skip this step if the KSM CLI is already configured on your machine.
{% endhint %}

To configure the KSM CLI tool, a profile needs to be created with the Keeper Secrets Manager One Time Access Token.

The simplest way to do this is to initialize the default profile with the following command:

`ksm profile init <TOKEN>`

For information on creating multiple profiles and other options, see the [profile documentation](https://docs.keeper.io/en/keeperpam/secrets-manager/secrets-manager-command-line-interface/profile-command)

### 2. Set AWS Permissions

To use the KSM sync to AWS, AWS [Secrets Manager](https://console.aws.amazon.com/secretsmanager/) requires standard IAM security credentials with `SecretsManagerReadWrite` enabled for the entire vault or on individual keys to sync.

`arn:aws:iam::aws:policy/SecretsManagerReadWrite`

See the Amazon instructions for creating Access Keys:

<https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html>

### 3. Create AWS Credentials Record

The KSM CLI needs the credentials for the AWS account to set secrets. These credentials are stored in a Keeper record which the CLI tool can access using Keeper Secrets Manager.

Record fields with the following labels are required on the credentials record:

"AWS Access Key ID"\
"AWS Secret Access Key"\
"AWS Region Name"

#### (Method 1) Create an AWS Credentials Custom Record Type

A custom record type can be created with the required fields, which makes it easy and clean to create a record.

To create a custom record type, go to the "Custom Record Types" tab in the Keeper Vault and hit "Create Type". Create a new record type with hidden fields that have the correct field label, then click "Publish" to create the new record type.

![AWS Credentials Record Type Definition](https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FVNbvE6Xe70YThhK3JLKu%2Fimage.png?alt=media\&token=a3e7b13d-4bef-4cdb-8246-4902f0609a9f)

Then simply create a new record of the AWS Credentials type and enter the details into the corresponding fields.

![](https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FoOaFzhmKu1BkPYHb6Jvk%2Fimage.png?alt=media\&token=6a348507-805d-459f-961a-d1257e98a678)

Make sure this new record is moved to a Shared Folder that is associated with your Secrets Manager application.

#### (Method 2) Add Custom Fields

To create a credentials record without creating a new record type, the required fields can be added as custom fields to a standard record.

Create a new record of any type, then add Custom Fields of the 'Hidden Field' type for each required AWS field. Click "Edit Label" to change the labels to the corresponding field name.

{% hint style="info" %}
Any record type will work, but the "File Attachment" standard record type has no fields and will be cleaner looking when custom fields are added
{% endhint %}

![Credentials fields as custom fields](https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FS1qSqpXQ74npJ4ZMWwTP%2Fimage.png?alt=media\&token=99c001ae-982d-4d5c-b267-bd95cd6c9ab7)

Then fill in each custom field and hit "Save" to save the record.

### 4. Create Value Mappings

The KSM CLI `sync` command identifies which values to set using mappings that are defined on the command call. For each mapping passed to the command, a value with the given name will be populated with the given value from the Keeper Vault.

These mappings follow this format:

`--map "VALUE KEY" "KEEPER NOTATION"`

`VALUE KEY` is the key name that the value will be assigned in AWS Secrets Manager

`KEEPER NOTATION` is a Keeper notation query of a value from a keeper record to set to the key

Keeper notation is a query notation used by Keeper Secrets Manager to identify specific record values. The notation follows the general format of: `UID/[field|custom_field]/fieldname`\
for example: `ae3d[...]d22e/field/password`

See the [Keeper Notation documentation](https://docs.keeper.io/en/keeperpam/secrets-manager/about/keeper-notation) for more information

{% hint style="info" %}
Note that full record UIDs are not given in these examples
{% endhint %}

Full Mapping Example:\
`--map "MySQL_PWD" "jd3[...]i-fd/field/password"`

Multiple mappings can be added to a single `sync` command\
`--map "MySQL_PWD" "jd3[...]i-fd/field/password" --map "MySQL_Login" "jd3[...]i-fd/field/login"`

### 5. Create Record Mappings (JSON values)

AWS allows storing JSON values in its Secrets Manager. These could be achieved in multiple ways and you can mix all of these together as long as mapped AWS KMS keys don't overlap. When syncing records or folders the AWS key name is the record title and JSON keys are field types or labels.

Using extended mappings format:

`--map "AWS_KEY+JSON_KEY" "KEEPER NOTATION"`

```bash
# JSON format for multiple values in same KMS key
ksm sync -t aws -c <CRED_UID> \
  --map "my-app+db_password" "keeper://jd3[...]ifd/field/password" \
  --map "my-app+api_key" "keeper://jd3[...]ifd/field/api_key"
```

Using one of the following record and folder formats:

`--record`, `-r <RECORD>` Sync individual records by title or UID. Can be specified multiple times.\
`--folder`, `-f <FOLDER>` Sync all records from specified folder(s) - non-recursive.\
`--folder-recursive`, `-fr <FODLER>` Sync all records from specified folder(s) and all sub-folders recursively.

{% hint style="info" %}
KSM sync command will use record titles as key names so they must conform to AWS restrictions - AWS Secrets Manager key names must be unique, between 1 and 512 characters and must contain only alphanumeric characters and the characters /\_+=.\@-
{% endhint %}

```bash
# Sync single record with flattened JSON
ksm sync --type aws --credentials <CRED_UID> --record "Database Password"

# Sync multiple records with raw JSON
ksm sync -t aws -c <CRED_UID> -r "DB Password" -r "API Keys" --raw-json

# Sync all records from a single folder
ksm sync --type aws --credentials <CRED_UID> --folder "Production/Databases"

# Sync multiple folders recursively
ksm sync -t aws -c <CRED_UID> \
  --folder-recursive "Production" \
  --folder-recursive "Staging"

# Mixed map syntax
ksm sync -t aws -c <CRED_UID> \
  --map "text_key" "keeper://xxx/field/password" \
  --map "json_key+password" "keeper://xxx/field/password" \
  --map "json_key+api_key" "keeper://xxx/custom_field/api_key" \
  --record "Auto Record" \
  --folder "Production/Databases" \
  --folder-recursive "Staging"
```

{% hint style="warning" %}
By default AWS web UI works with very simple JSON format where both keys and values are simple strings and when using `--raw-json` option it will show it as plaintext and you'll have to use external functions or SDKs to parse and use the full record JSON. When that flag is not set the JSON keys are the field types or labels and the value is in `JSON.stringify()` format for complex fields like phone, address, etc.
{% endhint %}

{% hint style="warning" %}
Ensure that the records referenced by the Keeper Notation queries are in a shared folder that is shared with your Secrets Manager application
{% endhint %}

{% hint style="success" %}
KSM sync is now ready to run
{% endhint %}

## Run Sync

To run the sync, use the KSM CLI `sync` command with the credentials record and value mapping.

### 1. Construct the Command

Put together the KSM sync command with the AWS type. The format looks like the following:

```
ksm sync --type aws --credentials [UID] --map [...] --map [...]
```

### 2. Run a Dry-Run

The sync command supports running a dry-run which will identify all changes that will be made to your AWS Secrets Manager values without actually pushing the values or making changes. Use this to make sure your mapping queries are constructed properly.

```
ksm sync --type aws --credentials [UID] --map [...] --map [...] --dry-run
```

### 3. Run the Sync

When ready, run the sync command without the dry-run option. This will push values from your Keeper Vault to AWS Secrets Manager

{% hint style="info" %}
TIP: you can use `-m` as short hand for `--map`
{% endhint %}

```
ksm sync --type aws --credentials [UID] -m [...] -m [...]
```