Create Secretless Connector Plugins

This topic describes how to create Secretless Connector Plugins using the Secretless Plugin Interface SDK.

To simplify this process, the SDK includes standalone, fully annotated templates for HTTP and TCP Plugins that are pre-populated with all of the required functions.

Areas of the template that require your input are described in detail in this topic.

Overview

This section provides a summary of the steps you need to complete to create a plugin. Before you begin, you should familiarize yourself with these steps, the structure of the Plugin Template files (see Template organization), and the prequisites listed in the topic, Secretless Plugin Interface (SDK).

To create a Plugin:

  1. Determine the type of service to which you need to connect. The SDK currently allows you to author two types of Connector Plugins: HTTP for APIs and TCP for databases.

     

    If you aren't sure which option to choose, or need additional information, contact us via our Community page. Also, if you want to create a plugin for a target service that doesn't fit the documented use cases, create a GitHub issue so we can assist you in determining the correct path to take.

  2. Copy the appropriate templates (either from secretless-broker/examples/connector_templates/http/template/ or secretless-broker/examples/connector_templates/tcp/template/) to a new folder on your local machine.

  3. Complete the step-by-step instructions contained in either: Create an HTTP Secretless Connector Plugin or Create a TCP Secretless Connector Plugin.

  4. After you've edited the template files, follow the instructions described in Build and Secure Secretless Connector Plugins.

Template organization

Secretless Plugin Templates are located in GitHub at: secretless-broker/examples/connector_templates/. Use templates in either http/template or tcp/template depending on the type of service to which you'll connect. 

Each folder contains two templates: plugin.go and connector.go.

Template

Description

plugin.go

Contains the logic to implement the Secretless Connector Plugin Interface. In this file, you'll fill in the Plugin metadata.

connector.go

Contains the logic to implement the Connector Plugin Interface. In this file, you'll define the method that carries out the authentication to the back-end service.

  • For an HTTP connector, this method takes an input http.Request and alters the request so that it contains the necessary authentication information.

  • For a TCP connector, the method receives the client’s net.Conn and negotiates the authentication handshake to return an authenticated net.Conn to the target service.

Create an HTTP Secretless Connector Plugin

 

Before you begin, check whether your target service is compatible with our Generic HTTP Connector. If it is compatible, you can specify your target by configuring the generic connector rather than writing a new plugin.

  1. Copy the contents of secretless-broker/examples/connector_templates/http/template/ to a new folder on your local machine.

  2. Open plugin.go and add the following metadata for PluginInfo():

    Map field

    Required edit

    pluginAPIVersion

    The version of the Secretless Plugin API for which your plugin is written. This allows the Secretless Plugin API to change over time without breaking plugins. The current Plugin API version can be found in the GitHub Secretless broker repository.

    type

    This must have the string connector.http.

    id

    A short, clear, unique name for use in logs and the secretless.yml config file. Allowed characters are: lowercase letters, _, : , - , and ~ .

    For more information on the secretless.yml config file, see Secretless Configuration.

    description

    A short summary of the plugin, up to 100 characters.

  3. Open connector.go and edit the Connect() function as described below:

    Function

    Required edit

    Connect()

    Define the method that carries out the authentication to the back-end service. This method takes an input http.Request and alters the request so it contains the necessary authentication information.

    An example of this function written for AWS can be found in the Secretless Broker GitHub repository.

Create a TCP Secretless Connector Plugin

  1. Copy the contents of secretless-broker/examples/connector_templates/tcp/template/ to a new folder on your local machine.

  2. Open plugin.go and add the following metadata for PluginInfo():

    Map field

    Required edit

    pluginAPIVersion

    The version of the Secretless Plugin API for which your plugin is written. This allows the Secretless Plugin API to change over time without breaking plugins. The current Plugin API version can be found in the Secretless Broker GitHub repository.

    type

    This must have the string connector.tcp.

    id

    A short, clear, unique name for use in logs and the secretless.yml config file. Allowed characters are: lowercase letters, _, : , - , and ~ .

    For more information on the secretless.yml config file see Secretless Configuration.

    description

    A short summary of the plugin, up to 100 characters.

  3. Open connector.go and edit the Connect() function as described below:

    Function

    Required edit

    Connect()

    Define the method that carries out the authentication to the back-end service. This method receives the client’s net.Conn and negotiates the authentication handshake to return an authenticated net.Conn to the target service.

    An example of this function written for PostgreSQL can be found Secretless Broker GitHub repository.

See also

Build and Secure Secretless Connector Plugins

Test Secretless Connector Plugins

Deploy Secretless Connector Plugins

Secretless Plugin Interface SDK Reference