Secrets Plugins

Extension Information

Introduction

The Secrets endpoints are GoCD extensions which allows looking up for secrets defined outside of GoCD. Secrets can be configured and managed outside of GoCD in an external Secrets Manager with the plugins providing an ability to lookup for these secrets.

If you’re looking to start away with a basic template for secrets plugins, we recommend forking this github repository.

Requests from the GoCD server

In order to implement a secrets extension point the following messages must be implemented by the plugin.

• Get Plugin Icon
• Get Metadata
• Get View
• Validate
• Lookup

Get Plugin Icon

This call is expected to return the icon for the plugin, so as to make it easy for users to identify the plugin.

Request name

cd.go.secrets.get-icon

Request body

The server will not provide a request body.

Response code

The plugin is expected to return status 200 if it can understand the request.

Response Body

An example plugin response body:

{
  "content_type": "image/svg+xml",
  "data": "PHN2ZyB2ZXJzaW9u..."
}

The plugin is expected to return an image object.

Get Secret Configuration Metadata

This is a message that the plugin should implement. The response should be a JSON which lists the required configuration and its metadata to connect to an external Secrets Manager. Users would rely on this configuration to configure the Secret Configuration (<secretConfig>) through the Secret Management View in GoCD.

Request name

go.cd.secrets.get-metadata

Request body

The server will not provide a request body.

Response Body

An example response body:

[
  {
    "key": "FilePath",
    "metadata": {
      "required": true,
      "secure": false
    }
  }
]

The response body will contain the following JSON elements:

The plugin is expected to return status 200 if it can understand the request.

Get Secret Configuration View

This is a message that the plugin should implement, to allow users to configure secret configuration (<secretConfig>) from the Secret Management View in GoCD.

Request name

go.cd.secrets.get-view

Request body

The server will not provide a request body.

Response code

The plugin is expected to return status 200 if it can understand the request.

Response Body

An example response body:

{
  "template": "<div>some html</div>"
}

A JSON config view object

Validate Secret Configuration

This message must be implemented in order to validate the configuration. The plugin would receive this message from GoCD server during config save.

Request name

go.cd.secrets.validate

Request body

An example validation request body for File based secret plugin

{
  "SecretsFilePath": "path\to\test_secrets.db"
}

The request body will contain the JSON array with the keys and values that form the part of the Secret Configuration.

Response code

The plugin is expected to return status 200 if it can understand the request.

Response Body

The plugin should respond with JSON array response for each configuration key that has a validation error

[
  {
   "key": "SecretsFilePath",
   "message": "No file exists at the given path"
  }
]

If any of the input keys have a validation error on them, the plugin is expected to return a list of validation error objects. If the configuration is valid, the plugin should return an empty JSON array.

Lookup secrets

This message is a request to the plugin to look up for secrets for a given list of keys.

The plugin would receive this message from GoCD when it tries to resolve a secret param. Apart from the list of keys in the JSON request, the request body will also have the configuration required to connect and lookup for secrets from the external Secret Manager.

Request name

go.cd.secrets.secrets-lookup

Request body

An example lookup request body for File based secret plugin

{
  "configuration": {
    "SecretFilePath":"path\to\test_secrets.db"
  },
  "keys": [ "key1", "key2" ]
}

The request body will contain the following JSON elements:

Response code

The plugin is expected to return status 200 if it can understand the request and is able to resolve all the given lookup keys.

If the plugin is unable to resolve all the keys it should return status 404, for any other errors during lookup return 500.

Response Body

The response body should contain a JSON array with the following JSON elements:

The error response body should contain the following JSON elements:

The plugin should respond with JSON array response containing the list of resolved key-value pair

[
  {
    "key": "key1",
    "value": "value1"
  },
  {
    "key": "key2",
    "value": "value2"
  }
]

The plugin should respond with JSON object with a proper error message if it fails to resolve any lookup key(s)

{
 "message": "Unable to resolve lookup key(s) [key1, key2]"
}

Request/Response JSON Objects

The Config View Object

Here’s an example of the config view object:

{
  "template": "<div class=\"form_item_block\">...</div>"
}

The Image Object

Here’s an example of the image object:

{
  "content_type": "image/svg+xml",
  "data": "...."
}

The Validation Error Object

Here’s an example of the validation error object:

[
  {
    "key": "SecretFilePath",
    "message": "No file exists at the given path"
  }
]