Synqly Bridge
/
Getting Started

Synqly Bridge Agent

Synqly Bridge Agent is a new Synqly service.

A Bridge Agent is a Synqly container that gets run in the customer's datacenter. The Bridge Agent connects to a Synqly SaaS or Embedded service. A Bridge Group represents the connection between the Synqly SaaS or Embedded service and a Bridge Agent. Synqly SaaS and Embedded services propagate integration requests across the bridge to the Bridge Agent where they get executed and responses are sent back to the originating Synqly service.

  1. A customer can define multiple Bridge Groups (e.g: to support multiple datacenters).
  2. Multiple integrations can be configured to use the same Bridge Group.
  3. Multiple instances of the same Bridge Agent can be started in the customer datacenter and Synqly SaaS and Embedded services will load-balance requests between those Bridge Agents.
  4. Customers can use BridgeCredentials to identify integration credentials that are stored locally at the Bridge Agent
  5. Customers can configure an network address whitelist limiting what the bridge agent can access for additional security.

This document contains instructions for getting started with the Synqly Bridge Agent.

Synqly Bridge topology

The Synqly SaaS global system is composed of disjoint geo-political areas broken into regions.

global network topology

Each Synqly bridge region contains a synqly bridge server cluster and multi-region areas contain a synqly bridge super cluster. This topology gives fast failovers on regional node failures and provides full regional failover capabilities in areas with multiple regions.

bridge server cluster

Set the --bridge-server-address to either a synqly bridge global cross-region load balancer address or a synqly bridge regional address. We recommend organizations use one of the synqly bridge global cross-region load balancer addresses. These cross-region endpoints use geo-routing to automatically select the nearest regional cluster to the bridge agent.

tls://bridge.synqly.com and tls://bridge-eu.synqly.com are the global cross-region load balancer addresses. tls://bridge-east.synql.com, tls://bridge-central.synqly.com, tls://bridge-west.synqly.com and tls://bridge-eu-central.synqly.com are the regional addresses.

Setup Steps

Create Synqly Bridge group and save bridge credentials and id

# SYNQLY_ORG_TOKEN = organization token
# SYNQLY_ACCOUNT = account name or id
# BRIDGE_NAME = bridge name

RES=$(curl -X POST https://api.synqly.com/v1/bridges/$SYNQLY_ACCOUNT -H "Content-Type: application/json" -H "Authorization: Bearer $SYNQLY_ORG_TOKEN" -d "{\"name\":\"$BRIDGE_NAME\", \"labels\": [\"test\", \"us-east\"]}")
BRIDGE_ID=$(echo $RES | jq -r '."result"["bridge"]["id"]')
BRIDGE_CREDENTIAL=$(echo $RES | jq -r '."result"["credential"]')

printf "%b" "$BRIDGE_CREDENTIAL" > $BRIDGE_NAME.creds

Run bridge container in customer datacenter

The Bridge agent accesses the Synqly SaaS or Embedded service. Synqly SaaS requires egress access to bridge.synqly.com:4222 or bridge-eu.synqly.com:4222.

The Bridge agent blocks access to local non-routable addresses. If your integration provider is being hosted on a local address, add --allow-address=host:port to the docker command line. The host portion must match the host name or ip address specified in the integration.

docker run -v  $(pwd):/creds quay.io/synqly/bridge --bridge-creds=/creds/$BRIDGE_NAME.creds --bridge-id=$BRIDGE_ID --bridge-server-address=tls://bridge.synqly.com:4222 --allow-address=10.200.21.55:8088

Create integration that uses bridge group

The Synqly SaaS or Embedded service forwards the integration request to the Bridge Agent specified by the bridge selector parameter. The Bridge Agent makes the local integration request (specified in the provider_config) and propagates the response back to the Synqly SaaS or Embedded service.

# sample splunk siem integration (requires SPLUNK_TOKEN and SPLUNK_URL)
export SPLUNK_TOKEN="your-splunk-token"
export SPLUNK_URL="https://10.200.21.55:8088"

# create integration with 'bridge_selector' that matches to exact bridge by 'id'.
RES=$(curl -X POST https://api.synqly.com/v1/integrations/$SYNQLY_ACCOUNT -H "Content-Type: application/json" -H "Authorization: Bearer $SYNQLY_ORG_TOKEN" -d "{\"name\":\"integration5\", \"provider_config\":{\"type\": \"siem_splunk\", \"hec_url\": \"$SPLUNK_URL\", \"input_format\": \"JSON\", \"hec_credential\": {\"type\": \"token\", \"secret\": \"$SPLUNK_TOKEN\"}}, \"bridge_selector\": {\"type\": \"id\", \"value\": \"$BRIDGE_ID\"}}" 2>/dev/null)
printf "\nCreate integration: $RES"
ITOK=$(echo $RES | jq -r '."result"["token"]["access"]["secret"]')

Exercise the bridge

curl -X POST https://api.synqly.com/v1/siem/events -H "Content-Type: application/json" -H "Authorization: Bearer $ITOK" -d '[{"class_name": "API Activity", "category_uid": 6, "type_uid": 600304, "activity_id": 4, "raw_data": "test message 5"}]'

BridgeGroup Security

Treat the BridgeGroup credential securely. It contains a secret. The BridgeGroup credential needs to be rotated periodically. The BridgeGroup credential can only be used to receive integration requests for the specific BridgeGroup.Id

The Authentication Process

When the Bridge Agent connects to the Synqly server, it presents the Bridge Group JWT. The Bridge Agent proves its identity by signing a Synqly server-issued cryptographic challenge with its private key. The JWT signature verification validates that the JWT signature was generated by the Synqly service.

Revoke or Rotate Bridge Agent credentials

Bridge Group credentials are valid for 1 year from creation. Credentials must be rotated prior to expiration.

  1. Create a new Bridge Group with same labels (if using labels) as existing Bridge Group (to create a new credential)
  2. Start a new Bridge Agent with that credential.
  3. Patch existing Integration BridgeSelector.Id(s) to contain the new BridgeGroup.Id. (if using BridgeSelector Id(s))
  4. Wait 2 minutes for the new integration configurations to propagate through the Synqly caches.
  5. Delete original Bridge Group configuration.
  6. Stop original BridgeAgents.
  7. Delete the original bridge group credential file.

Bridge Agent command line options.

Run the following command to get the bridge options.

bridge --help

Debugging

  1. Check 'bridge' output for any errors.
  2. Check the integration status and Synqly audit log.
  3. Check $(BRIDGE_NAME).creds syntax (see sample). Must be multi-line no embedded \n (newlines).
  4. Use https://jwt.io debugger to view the JWT

Sample credential file:

-----BEGIN NATS USER JWT-----
eyJ0eXAiOiJqd3QiLCJhbGciOiJlZDI1NTE5In0.eyJqdGkiOiJXNkFYSFlSS1RHVTNFUklQM0dSRDdNV0FQTzQ2VzQ2Vzc3R1JNMk5SWFFIQ0VRQ0tCRjJRIiwiaWF0IjoxNjAzNDczNzg4LCJpc3MiOiJBQUFYQVVWU0dLN1RDUkhGSVJBUzRTWVhWSjc2RVdETU5YWk02QVJGR1hQN0JBU05ER0xLVTdBNSIsIm5hbWUiOiJzeXMiLCJzdWIiOiJVRE5ZMktLUFRJQVBQTk9OT0xBVE5SWlBHTVBMTkZXSFFQS1VYSjZBMllUQTQ3Tk41Vk5GSU80NSIsInR5cGUiOiJ1c2VyIiwibmF0cyI6eyJwdWIiOnt9LCJzdWIiOnt9fX0.ae3OvcapjQgbXhI2QbgIs32AWr3iBb2UFRZbXzIg0duFHNPQI5LsprR0OQoSlc2tic6e3sn8YM5x0Rt34FryDA
------END NATS USER JWT------

************************* IMPORTANT *************************
NKEY Seed printed below can be used to sign and prove identity.
NKEYs are sensitive and should be treated as secrets.

-----BEGIN USER NKEY SEED-----
SUAAZU5G7UOUR7VXQ7DBD5RQTBW54O2COGSXAVIY
------END USER NKEY SEED------

*************************************************************

Run Synqly Bridge Agent in trace mode to see traffic traces

bridge --bridge-creds=$BRIDGE_NAME.creds --bridge-id=$BRIDGE_ID --bridge-server-address=tls://bridge.synqly.com:4222 --level=-1
 
Next page