Broker Integration

Britive Bridge ships with the Britive Broker built into its container image. The broker is Britive’s lightweight agent that makes outbound connections to your tenant and lets the platform reach on-premises resources without any inbound firewall openings. Running it alongside Bridge lets the Britive platform drive Bridge - creating and revoking checkouts as users request access - over that same outbound channel.

External brokers in v3.0.2

A broker on another host can manage checkouts over Bridge’s HTTPS API when server.checkout_api_tokens.enabled is true. Create its credential in Admin > API Tokens > Checkout tokens. Tokens can restrict checkout roles, protocols, and source networks. External broker access is disabled by default.

Follow Connect an external broker for bsh setup and verification. Checkout tokens covers token scope, creation, rotation, and revocation. The colocated broker continues to use its private loopback API.

How it fits together

• The broker binary is bundled in the Bridge image and runs as a supervised process next to the Bridge - on the orchestrator in a cluster, or in the single container in standalone mode. You deploy nothing extra.
• On startup, when a broker token is present, Bridge writes the broker’s config and starts it. The broker registers with your tenant’s broker pool and opens its outbound connection.
• When a user requests access in Britive, the platform routes the request to the pool; the broker calls the Bridge admin API (create the checkout), and the user then connects through Bridge as normal - recorded and time-boxed.
• The same token authenticates Bridge’s automatic license fetch, so a broker-connected deployment also keeps its license current on its own.

For every port and channel this adds — the traffic planes, the checkout and session lifecycle, and a firewall map — see Bridge & Broker Network Architecture.

    flowchart LR
  P["Britive platform"] <-->|"outbound, TLS"| B["Britive Broker<br/>(in the Bridge container)"]
  B -->|"Bridge admin API"| BR["Bridge"]
  U["User"] -->|"connect: SSH / RDP / …"| BR --> T[("Target")]
  

Enabling it

Set these on the Bridge container (the orchestrator in a cluster, or the single container in standalone mode):

When the token is set, Bridge renders the broker config to /opt/britive-broker/config/broker-config.yml and supervises the broker process for you - there is nothing else to install or run.

In v3.0.1, the entrypoint exports the private API URL, token-file path, and TLS-verification defaults to broker scripts. Nonempty overrides are preserved. These defaults do not enable platform telemetry, which is disabled by default in v3.0.1 and later.

Private checkout credential

Bridge creates the private API credential file when the single or orchestrator process starts. The file has mode 0600. The broker and its scripts run as the same operating-system user as Bridge and can read it. Root can also read it. Treat permission scripts and access to that user as privileged, because the credential authorizes checkout creation and deletion.

bsh reads the host’s broker API URL and credential file. Use bsh for supported permission methods. To supply the credential through a secret manager, use BSH_BRIDGE_BROKER_API_TOKEN with an external value reference. BRIDGE_CLUSTER_TOKEN does not authenticate checkout or checkin requests in v3.

Use bsh in permission scripts

Bridge includes bsh from v3.0.1. Use the latest bsh for these examples.

Configure the common Bridge variables and a supported target method. For an existing Unix account, the scripts are:

#!/bin/sh
exec bsh checkout ssh --method existing-user-key --mode bridge

#!/bin/sh
exec bsh checkin ssh --method existing-user-key --mode bridge

The SSH example supplies the target and administrative settings. bsh installs a generated key, registers the Bridge checkout, and returns connection details. Checkin ends the checkout and removes the key.

Where the broker-pool token comes from

In the Britive console, create (or open) a broker pool and copy its authentication token. Treat it as a secret - provide it through your platform’s secret mechanism, never in plaintext in a committed file.

Examples

Standalone (docker-compose)

    environment:
      BRIDGE_CONFIG: /etc/britive-bridge/config.yaml
      BRIDGE_ENCRYPTION_KEY_B64: "${BRIDGE_ENCRYPTION_KEY_B64:?}"
      # Broker integration + automatic license retrieval:
      BRITIVE_BROKER_AUTH_TOKEN: "${BRITIVE_BROKER_AUTH_TOKEN:?}"
      BRITIVE_BROKER_TENANT_SUBDOMAIN: "acme"
      BRIDGE_BROKER_API_URL: "http://127.0.0.1:8081"            # private checkout API

Kubernetes

Add the broker values to the bridge-secrets Secret in the Kubernetes manifest before you apply it, or patch the Secret in an existing deployment:

stringData:
  BRITIVE_BROKER_AUTH_TOKEN: "<broker-pool-token>"
  BRITIVE_BROKER_TENANT_SUBDOMAIN: "acme"
  BRIDGE_BROKER_API_URL: "http://127.0.0.1:8081"

AWS ECS (CloudFormation)

The CloudFormation template exposes BrokerAuthToken and BrokerTenantSubdomain for the bundled broker. It sets BRIDGE_BROKER_API_URL inside the orchestrator task to http://127.0.0.1:8081. The separate BridgeUrl parameter is the public browser address used for the OAuth callback.

Verifying

Confirm the broker came up next to Bridge:

• Logs - the Bridge container’s log stream includes the broker process; look for it registering with the pool on startup. In a cluster, this is on the orchestrator task/pod.

• Run bsh probe inside the broker’s container to list the available methods. Then request and check in a configured permission through Britive. Confirm that bsh returns connection details and that checkin ends the user’s access.

• In the console - the broker pool shows the broker as connected, and access requests to the targets Bridge fronts begin to succeed.

Existing shell integrations

The legacy checkout API helper still ships with Bridge. Its reference covers existing scripts and direct JSON operations. Use bsh for new permissions with a supported provisioning method.