Using the secure store

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

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:

  1. cd to your project's root directory.
  2. 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
});