NAV Navbar
Logo
Switch version:

Secrets Plugins

Current Version

This document is for version 1.0 (the latest) of the secrets endpoint.

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

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:

Key Type Description
key String The name of the configuration property supported by an secret configuration.
metadata Object The metadata associated with the key used in the secret configuration. Valid keys are required and secure.

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:

Key Type Description
configuration Object The secret configuration associated with the plugin.
keys Array A list of keys which needs to be resolved with
actual secret defined in external Secret Manager

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:

Key Type Description
key String The secret key which has been resolved.
value String The value corresponding to the secret key.

The error response body should contain the following JSON elements:

Key Type Description
message String The error message with reason for error or list of keys
which could not be resolved.

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>"
}

Attribute Type Description
template String A string containing an HTML AngularJS based view.

The Image Object

Here’s an example of the image object:

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

Attribute Type Description
content_type String A valid content type for the image. Please make sure the content type is supported by most browsers.
data String A base-64 encoded (single-line non-chunking) byte array of the byte-sequence that composes the image.

The Validation Error Object

Here’s an example of the validation error object:

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

Attribute Type Description
key String The name of configuration key that has an error.
message String The error message associated with that key.