11436 SSO

Storing Sensitive Data with Encrypted KVMs

A powerful feature of the latest Apigee Edge cloud release
Oct 28, 2016

We’re pleased to announce the general availability of encrypted KVMs. This capability is available as part of the Apigee Edge Cloud 16.09.21 release, which we detailed in a previous blog post.

What are KVMs?

Key value maps are routinely used by Apigee Edge customers to store various kinds of lookup information. For example, you can use KVMs to store:.

  • Code tables
  • Back-end target URLs
  • Environment properties

KVMs can be scoped at the API proxy level, the environment level, and at the org level. This tiered approach can be used to store information that’s accessible only by a specific proxy, by all proxies deployed in an environment, or by all proxies inside an org. The information stored within the KVM can be accessed by the API proxies during runtime.

Apigee Edge provides policies & RESTful management APIs that can be used to create, populate, and lookup entries from KVMs. One of the limitations of the KVMs, however, has been that the information stored inside them is unencrypted. So they weren’t suitable for storing sensitive information such as service accounts or system credentials.

Encrypted KVMs

Enter encrypted KVMs. They give you the ability to securely store sensitive information, and the contents (the value component) of these KVMs are automatically encrypted for you by the platform. You specify that the KVM is encrypted during creation time via a flag.

This information (the “value” held inside the KVM for a specific “key”) is available to API proxies during runtime, but is otherwise obfuscated when you turn on the trace mode for a proxy or use management API calls to interact with the KVM. Encrypted KVMs have the same characteristics as general KVMs such as the different scoping levels and access via policies and management APIs—the only difference is that their contents are encrypted.

Some common use cases for encrypted KVMs include:

  • Storing security credentials of third party systems and services that you may connect to SaaS applications and identity providers
  • Storing credentials / sensitive information for back-end target endpoints

A service account information example

Lets walk through a simple use case in which you need to store service account information securely (to connect to a third-party API). For this you’ll create an environment-level KVM called “service-accounts”:

  • Log in to Apigee Edge and select your org; in this case, it’s “pbhogill.” From the menu click on “APIs → Environment Configuration.” Select the “Key Value Maps” tab and click on the “+ Key Value Map” button. On the pop-up window enter “service-accounts” for the KVM name and check the “Encrypted” check-box, then hit “Add”



  • Add a couple of key-value pairs by clicking the “Edit” button. In the UI the values of the Encrypted KVM are displayed in text, so you can manipulate them easily.



  • If you make a management API call to query the contents of the encrypted KVM, the value component of entries in the map are masked. Your management API endpoint may be different, byut for Apigee Edge Cloud your endpoint would be: 



When you use an encrypted KVM in an API proxy, its contents are also masked in the trace tool, so sensitive information is not visible in the clear at run-time (see the “Using Encrypted KVMs” section of the release notes).

Additionally, as it works today for existing KVMs,  you can also access the decrypted value using the apigee-access module in Node.js code:

var apigee = require('apigee-access');

 var encryptedKVM = apigee.getKeyValueMap('service-accounts', 'environment');

 encryptedKVM.get('system1', function(err, secretValue) {

 // use the secret value here

Hope you’re as excited about this new feature as we are. We strongly encourage customers to use this feature, ask questions, and provide feedback on the Apigee Community.


Creating World-Class Developer Experiences