Service config property encryption

This guide explains how to configure automatic property encryption in Hashicorp Vault for an application or adapter.

What properties to encrypt

All sensitive properties should be encrypted. Examples include API tokens, passwords, and secrets. If Hashicorp Vault is configured, all encrypted properties are stored there and decrypted at runtime. They are never stored in the MongoDB document for that service config. If Hashicorp Vault is not configured, no properties can be automatically encrypted.

Set a property for automatic encryption

To set a property to be encrypted automatically when a service config is created or updated, the property must exist in the propertiesSchema.json document as a string type.

To support automatic property encryption, create a propertiesDecorators.json document at the same level as the propertiesSchema.json document. This document must contain an array (defaulting to [] if not explicitly defined).

Each element in the array must be an object containing a type and a pointer. The type must be set to encryption. The pointer must be a valid JSON pointer to a property within the propertiesSchema.json document.

In the UI, any property with an encryption pointer configured will display as ***** unless the user is actively editing that field.

Example propertiesDecorators.json files

The following propertiesSchema.json will be referenced in the examples below:

1
{
2
  "$id": "adapter-custom",
3
  "type": "object",
4
  "$schema": "http://json-schema.org/draft-07/schema#",
5
  "properties": {
6
    "credentials": {
7
      "properties": {
8
        "user": {
9
          "type": "string"
10
        },
11
        "password": {
12
          "type": "string"
13
        }
14
      }
15
    },
16
    "api": {
17
      "properties": {
18
        "token": {
19
          "type": "string"
20
        }
21
      }
22
    },
23
    "url": {
24
      "type": "string"
25
    }
26
  }
27
}

Given that credentials.password and api.token are likely sensitive, the propertiesDecorators.json should look like this:

1
[
2
  {
3
    "type": "encryption",
4
    "pointer": "/credentials/password"
5
  },
6
  {
7
    "type": "encryption",
8
    "pointer": "/api/token"
9
  }
10
]

If instead the url property contains credentials within the URL and api.token contains only a token type rather than the actual token, the file might look like this:

1
[
2
  {
3
    "type": "encryption",
4
    "pointer": "/credentials/password"
5
  },
6
  {
7
    "type": "encryption",
8
    "pointer": "/url"
9
  }
10
]

Differences between applications and adapters

The propertiesDecorators.json works the same for applications and adapters. However, the pointer starts from a different location depending on the type:

• For adapters, the properties to encrypt are contained in properties.properties of the service config.
• For applications, they are stored in properties of the service config.

The JSON pointer starts from these respective locations within the service config, consistent with how propertiesSchema.json maps to properties within the service config.