Use secrets in a custom app

Prior reading: Use custom apps

Purpose: This document explains how Workbench's centralized secret management works and how to create a custom app containing secrets.

Introduction

For many Workbench user apps to function, they require sensitive credentials such as license keys, database passwords, and API tokens. Workbench offers centralized secret management so that apps can securely consume these credentials without exposing them to end users. Users can define these secret variables and attach them to a custom cloud app.

Step-by-step guide

Prerequisites

To use secret variables in a custom app, you'll first need your Workbench contact or Workbench Support to add your secret resource to your workspace and grant you access.

Step 1: Create a secrets.yml file

1. In your devcontainer configuration, create a file called secrets.yml. This file should specify all of the secrets you want attached to your app. It should live in the same folder as your .devcontainer.json file.

It must contain the following fields:

• name: A unique identifier for your secret

• Delivery method: How the secret is delivered to your app. It must be one of the following values:

  • pipeVar: Path to a named pipe (most secure, read once only)

  • pathVar: Path to a file descriptor (secure)

  • valueVar: Direct environment variable name value (less secure, not the actual value)

  • dockerRegistry: URL for Docker registry authentication

Your secrets.yml file can also specify an optional allowedSecrets field to restrict which secret resources can be used. Each allowed secret must have a workspaceId and resourceId value. If the allowedSecrets field is omitted, the user can use any secret in the workspace that they have access to.

The following is an example of a secrets.yml file:

secrets:
  - name: "secret-1-name"
    allowedSecrets:
      - workspaceId: "WORKSPACE_1_UUID"
        resourceId: "RESOURCE_1_UUID"
      - workspaceId: "WORKSPACE_2_UUID"
        resourceId: "RESOURCE_2_UUID"
    pipeVar: "SECRET_1_PATH"
  - name: "secret-2-name"
    pathVar: "SECRET_2_PATH"
    valueVar: "SECRET_2_VARIABLE_NAME"
  - name: "secret-3-name"
    dockerRegistry: "secret.docker.registry"
  - name: "secret-4-name"
    gitRepository: "secret.git.repository"

Step 2: Create a custom app

Follow the steps in Create and launch a custom app in Workbench. In the Container setup step, specify the repository URL, branch, and folder path where the .devcontainer.json and secrets.yml files live.

Troubleshooting

When creating a custom app, the specified devcontainer will be checked for secrets. If a secret is required and the user doesn't have access to the secret, a warning will be displayed.

If you see "This app is not allowed to use your secrets matching "{secret.name}," it means the secret has an app constraint policy that blocks that specific app.

If you see "You don't have access to a secret named "{secret.name}," it means you don't have any secrets matching the required secret name in your accessible workspaces.

Contact workbench-support@verily.com for assistance.