Envase Vault Developer’s Guide

This guide provides information about how Envase applications and services can integrate Envase Vault to manage the secrets they need. It provides examples of the API usage, as well as the usage of the AWS Lambda functions exposed by the service. It also provides guidance to developers about when to use the REST API vs. the exposed functions.

Index

• Envase Vault Developer’s Guide

  • Environments

    • Development/Test

    • Staging/Sandbox

    • Production

  • Overview

    • REST API vs. AWS Lambda Function Interfaces

    • Representation of A Secret

  • Creating Secrets

    • Create Secret API

    • Create Secret AWS Lambda

  • Retrieving Secrets

    • Get Secret API

    • Get Secret AWS Lambda

  • Updating Secrets

    • Update Secret API

    • Update Secret AWS Lambda

  • Deleting Secrets

    • Delete Secret API

    • Delete Secret AWS Lambda

Environments

The Envase Vault service is deployed to three separate environments with different purposes. Client applications using the API will need to register a client in the appropriate environment to access Envase Vault. Applications and services using the exposed functions can access any environment, but it’s recommended that you keep your code separated by environment.

This separation comes in two forms. The API has a separate URL for each of the environments. The functions have different prefixes depending on the environment (see below for more information).

The following are the different environments where Envase Vault is deployed:

Development/Test

This environment is used for testing purposes of development teams. It’s the environment applications and services should use while testing code that is being developed. Secrets can be created, deleted, and manipulated in all sorts of ways in this environment to insure applications and services functionality works properly.

The base URL for this environment is:

url

https://vault-dev.envaseconnect.cloud

Functions in this environment use the following prefix:

prefix

vault-dev

Staging/Sandbox

This environment is used to test applications and services when they are ready to get into production. It is used to insure all the functionality that is going to be release is stable before it is released. Applications and services should point to this environment in Envase Vault to verify they are managing their secrets correctly.

The base URL for this environment is:

url

https://vault-stg.envaseconnect.cloud

Functions in this environment use the following prefix:

prefix

vault-stg

Production

This environment is used for production applications and services. Applications and services that are released must point to this environment to manage secrets. Secrets stored in this environment should be managed by an approved client application, and there should be no manual interaction with AWS Secrets Manager to change these secrets.

The base URL for this environment is:

url

https://vault.envaseconnect.cloud

Functions in this environment use the following prefix:

prefix

vault-prd

Overview

The Envase Vault service exposes two type of services. The secrets service should be used to manage secrets that relate to applications and services to interact with other services. The organizations service is used when an application or service needs to manage individual secrets for a specific customer. The API and functions provided are very similar, so they are documented together. You can check the Envase Vault Specification for more information about the REST API.

Important

This guide will show production URLs when showing examples of the REST API, and it will refer to functions using their name without the prefix. For example, this guide will refer to the function get-secret, but the function should be prefix with the environment prefix as in vault-prd-get-secret You should make sure you use the correct URLs or prefixes when working with Envase Vault.

REST API vs. AWS Lambda Function Interfaces

Envase applications and service must decide how they will interact with Envase Vault. This decision should be based on the type of application or service is being implemented.

Desktop applications or services hosted externally to Envase should use the REST API. The API provides an additional layer of security because Envase Vault requires Authentication/Authorization from those applications in order to access/manage secrets.

The REST API is the preferred method to access Envase Vault. However, full cloud applications or services deployed to the Envase AWS account may decide to use the AWS Lambda function interface. This interface does not require authentication because security can be achieve by other means within AWS.

Warning

Applications and services should settle on a single interface whether is the REST API or the AWS Lambda functions. It is not a good idea to mix and match these interfaces.

Representation of A Secret

A secret is represented as a JSON object. There are no structure enforced by Envase Vault for the secrets stored. An application can decided the structure of the secret that is going to store, and provide it as a JSON object.

The only limitation enforce by Envase Vault is that the attribute names in the JSON object should be specified in camelCase. If they attribute names are stored using other type of capitalization, the names are converted; therefore when retrieving secrets, you will always retrieve camelCase.

Note

We can write a book about why camelCase was selected, but the most important reason is that we wanted a single representation of a secret for consistency and camelCase won.

The following are valid secret representations:

{
    "user": "username",
    "password": "the-user-password#1"
}

{
    "clientId": "the-client-id",
    "clientSecret": "the-client-secret"
}

The attribute names of the JSON object do not matter, just make sure they are camelCase. Also, insure that all attributes are at the root of the object. Nested JSON object might not be handled properly in AWS Secrets Manager.

Creating Secrets

The Envase Vault service allows Envase applications and services to create new secrets to be retrieved later on when needed. These secrets can be standard secrets or organization secrets. The service provides two sets of APIs and Functions to create secrets.

Create Secret API

To create a secret through the API, a POST request is required. The payload will require a key to identify the secret, and the JSON object to be stored as a secret. The payload can also include a description for the secret. This comes handy when trying to identify the purpose of a secret.

Secret API

POST https://vault.envaseconnect.cloud/secrets

Organization Secret API

POST https://vault.envaseconnect.cloud/organizations/{organizationId}

The appropriate API should be used based on the secret type. The payload for both APIs is identical:

{
    "key": "secret-identifier-key",
    "secret": {
        "user": "me@mycompany.com",
        "pwd": "a-password"
    },
    "description": "Credentials for my service."
}

The response from the service will be 200 OK if the secret is stored successfully, and it will have the following structure:

{
    "id": "secret-identifier-key",
    "description": "Credentials for my service",
    "organizationId": "the-organization-id",
    "ern": "ern:vault:prd:the-organization-id:secret-identifier-key",
    "arn": "arn:generated-by-aws-secret-manager"
}

The response will return the specified key as the id of the secret. A ARN (Amazon Resource Name) is generated and returned. A ERN (Envase Resource Name) is also generated and return.

The description is returned if provided on the request. The organizationId will also be provided if the secret created is an organization secret.

The actual secret value is omitted to avoid transmitting secrets back and forth.

The APIs may return a 400 BAD REQUEST if there is a problem with the request. Usually, this is caused by a duplicate key specified. Regardless, the response will have a message attribute with information about what went wrong.

{
    "message": "Secret key already exists"
}

Warning

Do not rely on specific messages to handle errors. These messages can change at any time, and some of them are not controlled by the service. Instead, use the response status code to make decisions about the error. The message comes handy to use in logs.

Create Secret AWS Lambda

Envase Vault provides two functions to create secrets: create-secret and create-organization-secret. The payload for these functions are similar to the payloads for the API. The main difference is that create-organization-secret will require an additional attribute organizationId, which is specified in the URL when using the API.

Secret Function

create-secret

{
    "key": "secret-identifier-key",
    "secret": {
        "user": "me@mycompany.com",
        "pwd": "a-password"
    },
    "description": "Credentials for my service."
}

Organization Secret Function

create-organization-secret

{
    "key": "secret-identifier-key",
    "organizationId": "the-organization-id",
    "secret": {
        "user": "me@mycompany.com",
        "pwd": "a-password"
    },
    "description": "Credentials for my service."
}

The responses from the functions are identical to the API with the addition of the statusCode provided in the body of the response:

{
    "id": "secret-identifier-key",
    "description": "Credentials for my service",
    "organizationId": "the-organization-id",
    "ern": "ern:vault:prd:the-organization-id:secret-identifier-key",
    "arn": "arn:generated-by-aws-secret-manager",
    "statusCode": 200
}

Notice that the specified key has now become the id (identifier) of the secret. You’ll use the same key/id to access and manage the secret.

Retrieving Secrets

Once you have secrets stored in Envase Vault, you can retrieve them using their key/id. The APIs and AWS Lambda functions exposed work the same for secrets and organization secrets. The following sections show how to use them.

Get Secret API

The API to get a secret is exposed in the secrets service and uses the key/id of the secret to retrieve it.

Secret API

GET https://vault.envaseconnect.cloud/secrets/{secretId}

The secretId is tokenized so you can specify the key/id of the secret you need to retrieve. The response will have the following structure:

{
    "id": "secret-identifier-key",
    "ern": "ern:vault:prd:secret-identifier-key",
    "arn": "arn:generated-by-aws-secret-manager",
    "secret": {
        "email": "user@company.com",
        "password": "the-password"
    }
}

The API will return a 404 NOT FOUND if the specified key/id is not found.

Organization Secret API

GET https://vault.envaseconnect.cloud/organizations/{organizationId}/{secretId}

The organizationId and secretId are tokenized. You need to specify them in the URL for the secret you want to retrieve. The response has a similar structure but includes the organizationId:

{
    "id": "secret-identifier-key",
    "organizationId": "the-organization-id",
    "ern": "ern:vault:prd:the-organization-id:secret-identifier-key",
    "arn": "arn:generated-by-aws-secret-manager",
    "secret": {
        "email": "user@company.com",
        "password": "the-password"
    }
}

The API will return a 404 NOT FOUND if either the organization id or the secret key/id are not found.

Get Secret AWS Lambda

Envase Vault also exposes AWS Lambda to retrieve the secrets. They work similarly as the API but the parameters are specified through the payload.

Secret Function

get-secret

{
    "key": "secret-identifier-key"
}

The response is identical to the one from the API but includes the status code.

{
    "id": "secret-identifier-key",
    "ern": "ern:vault:prd:secret-identifier-key",
    "arn": "arn:generated-by-aws-secret-manager",
    "secret": {
        "email": "user@company.com",
        "password": "the-password"
    },
    "statusCode": 200
}

The function will return a status of 404 NOT FOUND if the specified secret is not found. It can also return a 400 BAD REQUEST if the key/id is not specified in the payload.

Organization Secret Function

get-organization-secret

{
    "key": "secret-identifier-key",
    "organizationId": "the-organization-id"
}

The response is identical to the one from the API, and it includes the status code.

{
    "id": "secret-identifier-key",
    "organizationId": "the-organization-id",
    "ern": "ern:vault:prd:the-organization-id:secret-identifier-key",
    "arn": "arn:generated-by-aws-secret-manager",
    "secret": {
        "email": "user@company.com",
        "password": "the-password"
    },
    "statusCode": 200
}

The function will return a status of 404 NOT FOUND if the specified key/id or organization are not found. It can also return a 400 BAD REQUEST if either those parameters are missing.

Updating Secrets

Envase Vault allows you to update the value of an existing secret. It also allows you to update the description when the secret is also updated. Trying to update only the description is an error due to the way that AWS Secrets Manager works. Both APIs and functions have been exposed to update secrets.

Update Secret API

You can update secrets by specifying their key/id and their organization id for organization secrets.

Secret API

POST https://vault.envaseconnect.cloud/secrets/{secretId}

The payload must specify the new secret, and you can also change the description.

{
    "secret": {
        "user": "updated@company.com",
        "pwd": "another-password"
    },
    "description": "Updated description"
}

Organization Secret API

POST https://vault.envaseconnect.cloud/organizations/{organizationId}/{secretId}

{
    "secret": {
        "user": "updated@company.com",
        "pwd": "another-password"
    },
    "description": "Updated description"
}

The response will have a status of 200 OK and contain the secret metadata as the response when creating a secret.

{
    "id": "my-service-credentials",
    "description": "Credentials for my service",
    "organizationId": "the-organization-id",
    "ern": "ern:vault:prd:the-organization-id:my-service-credentials",
    "arn": "arn:generated-by-aws-secret-manager"
}

The API can also return 404 NOT FOUND if the secret doesn’t exist, or 400 BAD REQUEST if a new secret object is not specified.

Update Secret AWS Lambda

Secrets can also be updated through AWS Lambda functions. It works the same as the API, but the parameters are specified in the event payload.

Secret Function

update-secret

{
    "key": "secret-identifier-key",
    "secret": {
        "user": "updated@company.com",
        "pwd": "another-password"
    },
    "description": "Updated description"
}

Organization Secret Function

update-organization-secret

{
    "key": "secret-identifier-key",
    "organizationId": "the-organization-id",
    "secret": {
        "user": "updated@company.com",
        "pwd": "another-password"
    },
    "description": "Updated description"
}

The response will match that of the API but the status code will be specified in the response payload:

{
    "id": "my-service-credentials",
    "description": "Credentials for my service",
    "organizationId": "the-organization-id",
    "ern": "ern:vault:prd:the-organization-id:my-service-credentials",
    "arn": "arn:generated-by-aws-secret-manager",
    "statusCode": 200
}

The function can also return 404 NOT FOUND if the specified secret or organization for organization secrets are not found, and 400 BAD REQUEST if the event payload is missing any required parameters as the key/id, the secrete, and the organization id for organization secrets.

Deleting Secrets

Envase Vault allows you to delete stored secrets. The delete functionality is very permissive, and it doesn’t cause an error if you try to delete a secret that doesn’t exist.

Delete Secret API

To delete a secret through the API, you need to specify its key/id.

Secret API

DELETE https://vault.envaseconnect.cloud/secrets/{secretId}

Organization Secret API

DELETE https://vault.envaseconnect.cloud/organizations/{organizationId}/{secretId}

The API returns 204 NO CONTENT if the secret is found and deleted or 205 RESET CONTENT if the secret is not found. Both cases indicate that the specified secret doesn’t exist any more.

Delete Secret AWS Lambda

The functions to delete secrets work in the same way as the API, but the parameters are specified in the event payload. The parameters must be specified; otherwise, the function will return an error. The responses will contain the status code.

Secret Function

delete-secret

{
    "key": "secret-identifier-key"
}

Organization Secret Function

delete-organization-secret

{
    "key": "secret-identifier-key",
    "organizationId": "the-organization-id"
}

The response from the function will contain the status code.

{
    "statusCode": 204
}

Like the API the functions return 204 NO CONTENT if the secret is found and deleted or 205 RESET CONTENT if the secret is not found. Both cases indicate that the specified secret doesn’t exist any more.

The functions can return a status of 400 BAD REQUEST if the required parameters are not specified.