Service Config Property Encryption

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

What properties should be encrypted

It is recommended that all sensitive properties be encrypted. Examples of properties that should be encrypted include API tokens, passwords, and secrets. If Hashicorp Vault is configured, all encrypted properties will be stored in Hashicorp Vault using this mechanism. These properties will be decrypted when used in runtime, but will never be stored on the MongoDB document for that service config. If Hashicorp Vault is not configured, no properties can be automatically encrypted.

How to set a property to automatically be encrypted

To set a property to be encrypted automatically when a service config is created or updated, first this property should exist in the propertiesSchema.json document. This property should be a string, and not a different data type.

To support any automatic property encryption, a propertiesDecorators.json document must be created at the same level as the propertiesSchema.json document. This json document must contain an Array type, and will default to [] if it is not explicitly defined.

Each element in the array must be an object, containing a type and a pointer. The type must be set to a value of encryption to work with the encryption set up for these properties decorators. The pointer must be a valid json pointer to a property within the propertiesSchema.json document.

Within the UI, any property that has an encryption pointer configured for it will display as ***** unless the user is actively editing that field.

Example propertiesDecorators.json files

Below is an example propertiesSchema.json file that will be referenced by the example propertiesDecorators.json files:

{
  "$id": "adapter-custom",
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "credentials": {
      "properties": {
        "user": {
          "type": "string"
        },
        "password": {
          "type": "string"
        }
      }
    },
    "api": {
      "properties": {
          "token": {
          "type": "string"
        },
      }
    },
    "url": {
      "type": "string"
    }
  }
}

Looking at this schema, it's likely that credentials.password and api.token are sensitive fields. If that's the case, then the propertiesDecorators.json should look like this:

[
  {
    "type": "encryption",
    "pointer": "/credentials/password"
  },
  {
    "type": "encryption",
    "pointer": "/api/token"
  }
]

However, if this assumption was wrong, and for some reason the url property includes credentials within the URL, and the api.token field actually contains a token's type instead of the actual token, the propertiesDecorators.json field might look like this:

[
  {
    "type": "encryption",
    "pointer": "/credentials/password"
  },
  {
    "type": "encryption",
    "pointer": "/url"
  }
]

Differences between applications and adapters

The propertiesDecorators.json works the same for applications and adapters; however, it is worth noting the pointer used in the array starts from a different location based on the type. On an adapter, the properties to encrypt are contained in the properties.properties of the service config whereas for an application they are stored in the properties of the service config. The json pointer starts from these locations within the service config. This is consistent with the way the propertiesSchema.json maps to properties within the service config.