Connect an external broker
In v3.0.2 and later, a broker on another host can create and check in Bridge checkouts over HTTPS. A deployment operator must enable this feature. It is disabled by default.
Before you begin
- Serve Bridge over HTTPS and allow the external broker to reach that address.
- Keep the colocated broker available for initial admin access and recovery if it issues your admin checkouts.
- Install the latest bsh on each external broker that can run the permission.
- Provide a secret manager or a protected credential file readable by the broker’s operating-system user.
External brokers use the public checkout API. An internet-facing Bridge address
also makes those routes internet-reachable. Use private ingress or firewall rules
if broker traffic must remain private. Keep port 8081 on loopback.
Set up checkout management
Obtain a checkout token
Follow Checkout tokens to enable API access and create a token. Restrict it to the roles, protocols, and source networks this broker needs. Save the token in the broker’s secret store or protected file.
Configure the permission scripts
Set the API URL, public Bridge URL, and checkout token for bsh. This example reads a token stored as a string in AWS Secrets Manager:
export BSH_BRIDGE_BROKER_API_URL=https://bridge.example.com
export BSH_BRIDGE_BROKER_API_TOKEN='aws-sm://prod/bridge-checkout-token?region=us-east-1'
export BSH_BRIDGE_URL=https://bridge.example.comThe broker’s AWS identity needs permission to read that secret.
BSH_BRIDGE_BROKER_API_TOKEN also accepts the token itself or another
external value reference.
bsh sends the resolved credential in X-Bridge-Broker-Token.
To use a protected file instead, leave BSH_BRIDGE_BROKER_API_TOKEN unset and
set its file alternative:
export BSH_BRIDGE_BROKER_API_TOKEN_FILE=/run/secrets/bridge-checkout-tokenThe broker’s operating-system user must be able to read the file. A nonempty
BSH_BRIDGE_BROKER_API_TOKEN takes precedence over the token-file setting.
If Bridge uses a private CA, set BSH_BRIDGE_CA_CERT_PATH to a trusted CA bundle
on the broker host. Certificate verification is enabled by default.
Configure the common permission variables,
including the same BSH_TRANSACTION_ID for checkout and checkin. Then choose
matching bsh scripts from the protocol examples.
Those methods provision target access and register it with Bridge.
Verify
With the permission variables set, run a probe for the selected method. For example, an SSH permission using an existing target account runs:
bsh probe ssh --method existing-user-key --mode bridge
bsh doctor --protocol ssh --method existing-user-key --mode bridgeThese checks do not create a checkout. doctor checks local Bridge client
configuration but does not authenticate against the Bridge API. It can also
connect to the target to check the administrative transport.
Request the configured permission through Britive. Confirm that bsh returns the user’s connection details and that the user can connect through Bridge. Check in the permission and confirm that access ends.
The checkout and checkin requests verify the token’s API access. If a creation
response is lost, inspect the transaction with
GET /api/transactions/{id} before retrying. Existing IDs cannot be overwritten.
See the checkout API reference
for inspection and token-validation routes.
Replace or revoke a token
Follow token replacement to preserve access to existing checkouts. Update the token source used by bsh, then repeat the verification before revoking the old token.
Revoking a token stops API requests but does not end existing checkouts. Check those in first if access must end immediately.
Troubleshoot
| Symptom | Check |
|---|---|
| Checkout tokens are disabled | Enable server.checkout_api_tokens.enabled on every serving replica. |
| Creation controls are unavailable | Obtain active admin access and reopen the panel. |
| Authentication fails | Check the token source, secret-store access, expiration, revocation status, and HTTPS URL. |
| Network restriction denies the caller | Match the broker’s source address to the token’s CIDRs. Configure only actual forwarding proxies in server.trusted_proxies. |
| A trusted proxy still receives a network denial | It must supply valid client-address information. Missing or malformed forwarding information fails a network-restricted request. |
| A checkout is absent or creation is refused | Check the token’s checkout group, role scope, and protocol scope. Network restrictions filter broker callers, not targets. |
Next steps
See the checkout API reference for routes and authentication, or the network architecture for firewall planning.