Secretless Service Connectors

This topic describes how to connect and configure service connectors.

Overview

When Secretless Broker receives a new request, it automatically processes the request based on the specifications defined in its configuration.

The configuration defines a local port or socket file where new connections are received as well as any credentials needed to authenticate that connection.

For security reasons, credentials are generally not provided plain-text in the configuration. For example, in a production environment you would retrieve credentials from a vault. Secretless Broker currently supports multiple vault Secret Providers (Secretless).

When a service connector receives a new connection request, it retrieves the required credentials using the specified Provider(s), injects the correct authentication credentials into the connection request, and opens up a connection to the target service. From there, the service connector simply transparently shuttles data between the client and service.

When using Secretless Broker, your application locally connects to the Secretless sidecar rather than connecting to the backend service directly.

Configure Secretless to listen for new connections

Secretless Broker must be configured to listen for new connection requests on a specific socket for each backend service. Secretless supports listening for new connections on the following socket types:

For example, PostgreSQL clients can connect to the PostgreSQL server either via UNIX domain socket or over a TCP connection. Below, we share examples of what the Secretless configuration looks like with each option.

UNIX socket

Use the following to listen on a UNIX socket as usual (default: /var/run/postgresql/.s.PGSQL.5432):

version: "v2"
services:
  sample-service:
    connector: pg
    listenOn: unix:///sock/.s.PGSQL.5432
    ...

In this case, the client would be configured to connect to the database URL /sock.

TCP socket

Use the following to listen on a given port. This may be the PostgreSQL default 5432 or a different port to avoid conflicts with the actual PostgreSQL server.

version: "v2"
services:
  sample-service:
    connector: pg
    listenOn: tcp://0.0.0.0:5432

In this case, the client would be configured to connect to the database URL localhost:5432.

Redirect your client to Secretless

There are two main strategies to redirect your client to connect to the target service via the Secretless Broker:

Revise the connection URL

For clients that support specifying a connection URL, you can revise it to point to Secretless instead of the backend URL.

For example, the PostgreSQL client supports connection URLs such as postgres://user@password:hostname:port/database?sslmode=disable. If Secretless is configured to listen on localhost:5433 for new connections to the PostgreSQL backend, you can update the connection string your application uses to replace the old hostname:port with localhost:543.

If you configured the PostgreSQL service connector for Secretless to listen on the UNIX socket available at /sock/.s.PGSQL.5432 in the Secretless container, you can replace hostname:port in the connection string with the socket address /sock/.s.PGSQL.5432 to direct your application to the Secretless socket file for your PostgreSQL backend.

Specify a proxy (HTTP)

HTTP clients usually support an environment variable or configuration setting http_proxy which, when set, routes outbound traffic through the proxy URL on its way to the destination. The Secretless Broker can operate as an HTTP forward proxy and edit the outbound request to add the proper authorization header. It can also optionally forward the connection using HTTPS.

To route outgoing requests to an HTTP backend via Secretless Broker you can set the http_proxy environment variable directly in the request, for example by configuring Secretless to listen on port 8080 and calling http_proxy=localhost:8080 curl -i backend_url.

For more details on configuring Secretless Broker, see Secretless Configuration.

Service connector security

Regardless of the connection strategy, the operating system provides security between the client and Secretless. It's important to configure the OS properly so that unauthorized processes and clients can't connect to Secretless. With UNIX domain sockets, operating system file permissions protect the socket. With TCP connections, Secretless should be listening only on localhost.

The Secretless configuration governs the client to Secretless connection as well as the connection from Secretless to the PostgreSQL server, since the actual address and credential information for the connection to the PostgreSQL server are defined in the Secretless configuration.

Select the service connector you are interested in below to learn about its usage and configuration. Check our GitHub issues to see if the Target Service you are interested in is on our radar, and request it by opening a GitHub issue if not.