Skip to main content

Support On-Prem Connections in Custom Connectors

Prismatic provides several built-in connectors that connect to systems that are often on-prem (like PostgreSQL, MySQL, and MS SQL databases, SFTP file systems, SMTP and IMAP email servers, etc.). Those built-in connectors support on-prem connections out of the box.

If you've built a connector that connects to a system that is often hosted on-prem, you can add support for on-prem connections as well.

Add on-prem support to a connection​

Within your custom connector, change your connection() invocation to an onPremConnection invocation. The onPremConnection function takes the same arguments as connection but requires that your connection include inputs named host and port. Additionally, update your host and port to have the property onPremControlled: true.

For example, here is a basic auth on-prem connection for a custom connector:

import { onPremConnection } from "@prismatic-io/spectral";

export const basicAuth = onPremConnection({
  key: "basicAuth",
  display: {
    label: "Username, password and endpoint",
    description: "Basic auth username and password and endpoint",
  },
  inputs: {
    username: {
      label: "Username",
      placeholder: "Username",
      type: "string",
      example: "john.doe",
      required: false,
      shown: true,
    },
    password: {
      label: "Password",
      placeholder: "Password",
      type: "password",
      example: "p@s$W0Rd",
      required: false,
      shown: true,
    },
    host: {
      label: "Host",
      placeholder: "Name of the host",
      type: "string",
      required: true,
      comments:
        "The address of the Acme server. This should be an IP address or hostname.",
      example: "server.example.io",
      onPremControlled: true,
    },
    port: {
      label: "Port",
      placeholder: "Port of the host",
      default: "1234",
      required: true,
      comments: "The port of the Acme server.",
      type: "string",
      onPremControlled: true,
    },
  },
});

For a full example of a connector that supports on-prem connections, see our SFTP connector source code in GitHub. src/connections.ts contains the connection definitions for the connector.

SFTP component source code

When an execution is run, the instance will provide the connection with the host and port of the on-prem agent to connect to.

Support connections that don't have host and port inputs

What if your custom connector doesn't have host and port inputs? You might have an input called endpoint for example that represents your customer's (generally publicly available) app endpoint that is a URL like https://my-customer-id.example.com.

Add host and port inputs but set them to required: false, shown: false. Then, in your connector's code, you can check if yourConnection.fields.host has a value. If it does, construct the endpoint from https://${yourConnection.fields.host}:${yourConnection.fields.port}.

Handle servers that use host-based routing​

Some HTTP servers use host-based routing to determine which site to serve. For example, a server with IP 10.1.2.3 might serve both your app and a different app on port 80, and determine which app to serve based on the Host header in the HTTP request. When using the on-prem agent, the Host header in your HTTP request will default to the IP address of the on-prem service. You can override the Host header in your HTTP client to match the hostname of the service you want to connect to.

For example, you could specify the Host header as the endpoint input of your connection:

const response = client.get(
  `https://${yourConnection.fields.host}:${yourConnection.fields.port}`,
  { headers: { Host: yourConnection.fields.endpoint } },
);

A full example connector that supports on-prem connections with host-based routing can be found in the GitHub examples repo.

Example on-prem-compatible component

Handle HTTPS-based connections​

If the service that you are connecting to uses HTTPS on the private network, you will need to make sure that your HTTP client in your connector is configured to trust (or ignore) the SSL certificate of the service. The HTTPS client that the custom connector SDK provides is an instance of Axios, which uses the https module from Node.js. You can ignore SSL certificate errors by setting the rejectUnauthorized option to false in the https module's global agent:

const https = require("https");

const agent = new https.Agent({
  rejectUnauthorized: false,
});

const response = client.get(
  `https://${yourConnection.fields.host}:${yourConnection.fields.port}`,
  {
    headers: {
      Host: yourConnection.fields.endpoint,
    },
    httpsAgent: agent,
  },
);