Using the secure store

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

Deprecated feature: The Edge secure store (vault) is deprecated (as described on the Deprecations and retirements page) and will be retired in the future.

The Edge secure store (vault) was created to provide an encrypted data store for sensitive information. After you create a vault, you can retrieve vault data only with Node.js. As of Edge for Public Cloud release 160921, you can create encrypted key value maps (KVMs) to store sensitive data. Encrypted KVMs have an advantage over the Edge vault, because encrypted values can be retrieved with the Key Value Map Operations policy as well as with Node.js (using the apigee-access KVM functions), giving you more flexibility in your API proxies or Node.js apps. For more information on KVMs, see Long-term persistence caching.

Private Cloud Deprecation Notice:

Support for Node.js proxies and secure vaults

Since 2013, Apigee has supported the use of Node.js proxies within Apigee Edge through the use of Trireme, which enables you to run your Node.js code within Apigee Edge for Private Cloud and expose it as an API.

Apigee recommends Private Cloud customers take the following steps:

Migrate data in secure vaults to Encrypted Key Value Maps (KVM) to access sensitive data from an API proxy.
Migrate Trireme (Node.js) based API proxies to a native Node.js environment outside of Apigee.

Using the secure store service APIs

The secure store service lets you store sensitive data, such as security credentials for back-end services, in encrypted format so that they are protected from unauthorized use. These secure storage areas are called "vaults", and can be scoped to either the organization or environment levels on Apigee Edge.

For example, the secure store may be used to store a password required by a Node.js application in order to reach a protected resource, such as a database server. You can store the password in the secure store through an API before deployment, and the application can look up the value at runtime.

By doing this, there is therefore no need to include the password in the source code control system, or to deploy it alongside the Node.js source code to Apigee Edge. Instead, the value is stored by Apigee in encrypted form and it will only be retrieved when the application needs it.

For documentation on the secure store APIs, see Vaults. The following sections also provide an overview of using the secure store API.

Storing data by organization

Each Apigee Edge organization has a set of secure stores, and each environment has an additional store. That way organizations that have different security requirements for different back ends can store different secure values. This section describes storing by organization.

Usage

Retrieve the names of all the secure stores:

GET /o/{organization}/vaults

Retrieve a list of entries (but not their encrypted values) from a named vault.

GET /o/{organization}/vaults/{name}

Retrieve a single entry (but not its encrypted value).

GET /o/{organization}/vaults/{name}/entries/{entryname}

Create a new vault named "name" with no values:

POST /o/{organization}/vaults

{ "name": "{name}" }

curl https://api.enterprise.apigee.com/v1/o/testorg/vaults
  -H "Content-Type: application/json"
  -d '{"name": "test2" }' -X POST

Place a new entry in the vault with the specified name and secure value.

POST /o/{organization}/vaults/{vaultname}/entries

{ "name": "{entryname}", "value": "{securevalue}" }


curl https://api.enterprise.apigee.com/v1/o/testorg/vaults/test2/entries
  -H "Content-Type: application/json"
  -d '{"name": "value1", "value": "verysecret" }' -X POST

Replace the value of the specified entry with a new value:

PUT /o/{organization}/vaults/{vaultname}/entries/{entryname}

curl https://api.enterprise.apigee.com/v1/o/testorg/vaults/test2/entries/value1

  -d 'verymoresecret' -X PUT

Return "true" if the specified value matches what is already in the store, and "false" if it does not. In both cases, an HTTP status code of 200 is used. This may be used to validate the contents of the store. Note that once stored, there is no API to retrieve the unencrypted value:
```
POST /o/{organization}/vaults/{vaultname}/entries/{entryname}?action=verify

curl https://api.enterprise.apigee.com/v1/o/testorg/vaults/test2/entries/value1?action=verify
  -d 'verymoresecret'  -X POST
```
Delete the specified vault entry:

DELETE /o/{organization}/vaults/{vaultname}/entries/{entryname}

Delete the entire vault.
```
DELETE /o/{organization}/vaults/{name}
```

Storing data by environment

You can also store data by Apigee Edge environment. In this case, the data is scoped to an environment (such as "prod"). With this feature, at runtime different values can be stored depending on where the Node.js script is running.

Usage

GET /o/{organization}/e/{env}/vaults

GET /o/{organization}/e/{env}/vaults/{name}

GET /o/{organization}/e/{env}/vaults/{name}/entries/{entryname}

POST /o/{organization}/e/{env}/vaults

POST /o/{organization}/e/{env}/vaults/{vaultname}/entries

PUT /o/{organization}/e/{env}/vaults/{vaultname}/entries/{entryname}

POST /o/{organization}/e/{env}/vaults/{vaultname}/entries/{entryname}?action=verify

DELETE /o/{organization}/e/{env}/vaults/{vaultname}/entries/{entryname}

DELETE /o/{organization}/e/{env}/vaults/{name}

Retrieving values from the secure store in Node.js

Installing apigee-access

To use apigee-access in your Node.js code, you need to install it first. For example:

cd to your project's root directory.
Execute: npm install apigee-access --save

Functions

The apigee-access getVault() function is used to retrieve a particular vault, either per organization or based on the current environment where the Node.js code is running.

getVault() takes two parameters:

The name of the secure store to retrieve.
The scope, which may be organization or environment. If not specified, then organization is assumed.

The object returned by getVault() has two functions:

getKeys(callback): Return an array containing the names of all the keys in the specified vault. The callback function will be called with two arguments: An error if the operation fails, or "undefined" if it does not, and the actual array as the second argument.
get(key, callback): Return the secure value associated with a particular key. The callback function will be called with two arguments: An error if the operation fails, or "undefined" if it does not, and the actual value as the second argument.

Example

Here's a Node.js sample that demonstrates how to get a value from a vault. The apigee-access module is installed for this code to work, as explained previously.

var apigee = require('apigee-access');
   var orgVault = apigee.getVault('vault1', 'organization');
   orgVault.get('key1', function(err, secretValue) {
   // use the secret value here
});