Integrating to internal infrastructure with Broker
Published on December 20th, 2022Introduction
The Broker connection is designed to connect Roadie and its plugins to integration targets that are located on self-hosted infrastructure and therefore not publicly available via the internet.
Overview
The broker is a Node.js service that you run inside your infrastructure to provide a secure tunnel for Roadie traffic. It was originally created by security company, Snyk. The code is open-source. We are actively using it with existing customers for Kubernetes API access and other Backstage and Roadie plugins. You don’t need to be a Snyk user to use the broker.
The benefits of the broker include:
- You can allow list what Roadie can access using a config file.
- Any tokens for the internal endpoints stay in your infra. They are not shared with Roadie.
- The broker maintains an audit log of what we access.
- The connection is established outbound from your side. We cannot re-establish the connection on our own if you kill it.
The Broker feature is available on our Growth Plan - see pricing page for more information.
Broker Architecture
Broker connection consists of two similar services called broker server and a corresponding broker client
Client
A node.js application creating a websocket connection to its counterpart, broker server hosted in Roadie infrastructure.
Server
A tenant specific broker server accepting websocket handshakes and directing traffic through from Roadie instance via the socket to the broker client
The broker connection itself keeps an open websocket identified by a broker token which can be specified by the client trying to establish a connection. The traffic flows through this websocket and is filtered on both ends, broker server and broker client, using an ‘accept.json’ configuration file. This configuration file also determines where requests are forwarded to and if they need additional headers to be injected to the request.
This way Roadie does not need to have knowledge or access of your infrastructure endpoints nor authorization tokens.
Configuration
Enabling broker connection
The broker server instance is not enabled by default on tenants and thus needs to be requested to be enabled.
You can visit the settings page fro the broker at the following url in the application. https://<your-tenant>.roadie.so/administration/settings/integrations/broker
The broker endpoint server is secured by allow listing IP addresses. You can configure the list of IP addresses in the settings page mentioned above.
You can also test the broker client connections mentioned below from the settings page.
Configuring Broker client
There are three ways to run the broker client application:
- Run one of the pre configured docker containers provided by roadie
- Run the broker client nodejs application
- Build a custom docker container
Roadie Docker Containers
Roadie provides pre configured docker containers containing pre-configured broker clients for use with backstage. At time of writing, we are providing a container image for kubernetes and sonarqube.
You can configure them with environment variables containing authentication credentials for the brokered service as well as the broker endpoint and the broker client token.
e.g. To run the kubernetes client you can run the docker container as follows:
docker run \
-v "$(pwd)"/certs:/var/lib/certs:ro \
--env CA_CERT=/var/lib/certs/ca.cert \
--env K8S_SERVICE_ACCOUNT_TOKEN=service-account-token \
--env BROKER_TOKEN=kube-api \
--env BROKER_SERVER_URL=https://<TENANT_NAME>.broker.roadie.so \
roadiehq/broker:kubernetes
Snyk Broker CLI application
The broker client is published as an npm package available to be downloaded, installed on run on a machine configured to run nodejs packages. You can install and run it directly or use the npx command:
npm install --global snyk-broker
BROKER_TOKEN=test \
BROKER_SERVER_URL=https://<TENANT_NAME>.broker.roadie.so \
PREFLIGHT_CHECKS_ENABLED=false \
broker --disableBodyVarsSubstitution --disableHeaderVarsSubstitution
BROKER_TOKEN=test \
BROKER_SERVER_URL=https://<TENANT_NAME>.broker.roadie.so \
PREFLIGHT_CHECKS_ENABLED=false \
npx snyk-broker --disableBodyVarsSubstitution --disableHeaderVarsSubstitution
In order to do something meaningful with the broker client you will need to configure and accept.json
file documented in a section below.
To provide the accept.json
ACCEPT=accept.json
BROKER_TOKEN=test \
BROKER_SERVER_URL=https://<TENANT_NAME>.broker.roadie.so \
PREFLIGHT_CHECKS_ENABLED=false \
broker --disableBodyVarsSubstitution --disableHeaderVarsSubstitution
Custom docker container
You could also build your own container that builds the accept.json
and broker client into. This is out of the scope of this document. But you can take inspiration from the roadiehq/broker
container images on docker hub.
Broker client application configuration
Broker client is configured via an accept.json
configuration file and environment variables based on the content of the said accept.json
file. The file contains endpoint routing paths definitions determining where the requests coming from Roadie should be forwarded to. The configuration file also acts as a filtering mechanism to block non-allowed requests and as a request decorator to enhance request headers with possible auth information.
Roadie can provide configuration files for plugins which can be used to forward traffic to endpoints the plugins are using. You can find a broker configuration file section on each of the plugins documentation pages. If some plugin is missing a configuration file, you can request the support to provide you with one.
Configuration file structure
An example accept.json
looks like the following:
{
"private": [
{
"//": "Show results of my plugins API",
"method": "GET",
"path": "/api/show",
"origin": "${MY_PLUGIN_REST_ENDPOINT}",
"auth": {
"scheme": "bearer",
"token": "${MY_PLUGIN_AUTH_TOKEN}:"
}
}
],
"public": [
{
"//": "Get broker connection status",
"method": "GET",
"path": "/healthcheck"
}
]
}
The file is divided into 2 parts, public and private.
The public configuration block defines what endpoints can be called when calling the broker client endpoint directly. This would be for cases where an internal infrastructure would need to send data via the broker client toward Roadie instances. This is rarely used since most Backstage and Roadie plugins make requests and expect a response.
The private configuration block defines what requests are allowed to come through via the connected broker websocket connection and where they are forwarded to. In the example above we are allowing traffic to flow to a single endpoint matching an imaginary service we have developed. We are hosting this custom imaginary service in our own infrastructure behind a corporate firewall in a private network and it’s APIs are accessible when using bearer token authentication. The service exposes a single GET endpoint with a path /api/show. With this configuration the broker client would allow Roadie plugins to contact the imaginary service, via the broker connection, in cases where the request is going to the defined endpoint using a GET request and nothing else.
The best way to configure endpoints and tokens via environment variables. In the above example the accept.json
file is expecting two env variables, MY_PLUGIN_REST_ENDPOINT
and MY_PLUGIN_AUTH_TOKEN
.
Configuration options
Below you can find a table of configuration options available in the accept.json
file.
Key | Example values | Description |
---|---|---|
// | Any string | Denotes a comment on the configuration file |
method | HTTP Methods (GET, POST, PUT, DELETE, etc.) or any | HTTP Method to be used as a filter on the request |
path | /my-plugin/endpoint | Endpoint path to accept requests to. Only request going to these endpoints are forwarded. You can use * as a wildcard, e.g. /my-service/components* |
origin | https://my-service.myinternaldomain.com | The origin host to forward the request to. This is only available on the private configuration block. |
auth | {“scheme”: “bearer”, “token”: “my-secret-token” } | Auth scheme and value to use to overwrite any auth header coming from the original request. See auth scheme options from the table below. This is only available on the private configuration block. |
Auth Scheme options
Scheme value | Value input key | Example | End result |
---|---|---|---|
token |
token |
{ "scheme": "token", "token": "my-secret-token" } |
Authorization: Token my-secret-token |
bearer |
token |
{ "scheme": "bearer", "token": "my-secret-token" } |
Authorization: Bearer my-secret-token |
basic |
token or username and password |
{ "scheme": "basic", "token": "my-secret-token" } or { "scheme": "basic", "username": "user", "password": "pass" } |
Authorization: Basic bXktc2VjcmV0LXRva2Vu (base64 encoded token) or Authorization: Basic dXNlcjpwYXNz (base64 encoded user:pass ) |
An additional filtering based on any header can be achieved by using valid
configuration block in the configuration file.
"valid": [{
"header": "my-header-key",
"values": ["my-super-secret-header-key-value"]
}]
Troubleshooting
Error: self-signed certificate in certificate chain
- If the services you are directing traffic to are using self-signed certificates you might face an issue where the broken healthcheck does not respond correctly, varying between 403 and 404 error codes. To fix this, you can eitherprovide the certificate to the broker manually so it understand that or alternatively disable certification verification altogether.