Skip to content

Add Countersign to a service

Suppose an analyst starts a reconciliation job in your application. The job needs to read a statement from ledger.partner.example:443 using the analyst's client certificate. Treat the reconciliation as the Context, the job process as the Workload, and the analyst's existing application account as the owner. Your backend already knows who may start that job and which ledger it may contact.

Put the integration on your origin

Run your own Broker and Gateway. Configure the same protected destination and policy version on both. Serve the widget on your authenticated application and expose the Broker's WebSocket upgrade at wss://portal.example/v1/companion on that same origin. The Companion will open /countersign/pair?attempt=… in the user's browser. Provide that page and an authenticated /countersign/devices page for managing a lost or retired pairing. The Broker backend and administrator routes are for your servers. Configuration · Broker API

  1. Offer a Pair Companion action that shows the HTTPS origin the analyst should enter in the installed Companion, here https://portal.example.
  2. When the analyst pairs, the Companion displays a code and opens your pairing page. Authenticate the analyst, show their account, and ask them to enter the code from the Companion. After they confirm, your backend checks the session, request Origin and CSRF token and posts the attempt, code and session-derived user ID to /v1/backend/pairings/confirm.
  3. The Companion shows the verified origin and account for a second confirmation. After the analyst confirms there, its protected pairing key signs a fresh challenge. The Broker records the pairing and the Companion shows Connected. The analyst can use the same Companion with another Integrator. Pairing and device controls

Bind a job to its owner

The examples use Broker Integrator ID finance. Give every running instance an opaque ID. For example, user u-42 owns Context close-q3, and your scheduler assigned Workload export-981, generation 1. Bind those values on your backend when the job starts. Use a higher generation when replacing the instance.

The following Node example runs on the backend. brokerBase is your private HTTPS Broker origin and backendToken comes from your backend's secret store. The host's TLS client must trust the Broker's issuing CA.

async function brokerPost(path, body) {
  const response = await fetch(new URL("/v1/backend/" + path, brokerBase), {
    method: "POST",
    redirect: "error",
    signal: AbortSignal.timeout(10000),
    headers: {
      "Content-Type": "application/json",
      Authorization: "Bearer " + backendToken
    },
    body: JSON.stringify(body)
  });
  if (!response.ok) throw new Error("Broker returned HTTP " + response.status);
  return response.status === 204 ? null : response.json();
}

const job = {
  user: "u-42", context: "close-q3",
  workload: "export-981", workload_generation: 1
};
const issued = await brokerPost("workloads", { ...job, mode: "sidecar" });

Store issued.binding with the job. Configure the sidecar with that binding and deliver issued.token through a private credential file. Refresh the token for the same running generation before expires_at_ms and replace the file atomically. The demo refreshes every 60 seconds. Give the Workload the proxy settings and the sidecar's public CA certificate. Runnable sidecar demo · Token delivery in the demo backend

Make the first protected request

From the job environment configured with HTTPS_PROXY and the sidecar's public CA bundle, run a normal HTTPS request.

curl --fail --show-error https://ledger.partner.example/statements/latest

First protected request in three phases. Request and approval: the Workload's CONNECT waits while the Broker notifies the Companion and the user picks a certificate. Upstream handshake: the Gateway verifies the site, then gets the handshake signed by the Companion through the Broker. Application traffic: the request and response flow through the Gateway.First protected request in three phases. Request and approval: the Workload's CONNECT waits while the Broker notifies the Companion and the user picks a certificate. Upstream handshake: the Gateway verifies the site, then gets the handshake signed by the Companion through the Broker. Application traffic: the request and response flow through the Gateway.

With two or more eligible identities the analyst must select one before Approve becomes available. A wildcard destination normally prompts for the exact requested host. If the administrator enables whole-wildcard approval, the prompt shows both the initiating host and the broader scope. The certificate's private key stays on the analyst's machine. Companion approval screen

For an explicit Request access action, your authenticated page calls your backend. Resolve the job from the session and Context, then call the Broker with the stored binding and server-selected host.

const { id, state } = await brokerPost("requests", {
  binding: issued.binding,
  host: "ledger.partner.example:443"
});

Return the approval ID to the page. An explicit request joins a matching pending approval or returns its current approved record. After denial, cancellation or expiry, an explicit request starts a fresh approval. If the original CONNECT timed out, the Workload must deliberately issue another request after approval. Widget adapter and notification handlers

The demo Integrator's page beside the Countersign widget, which shows Request access, an Open Companion link for the pending request and a Pair another computer link.The demo Integrator's page beside the Countersign widget, which shows Request access, an Open Companion link for the pending request and a Pair another computer link.

The widget draws only the pairing, request and launch controls in its own Countersign card. Your page explains the job, the pairing and what happens next. Restyle the widget

Show progress and end access

Query status with the session-derived user ID and the approval ID. Show “Approved” for a committed decision, “Ready for handshakes” when ready is true, and “Upstream accepted mTLS” only after upstream_mtls_accepted is true. Closing the Companion can leave an existing leased connection usable until its authority expires. A fresh handshake needs the winning Companion online. Status fields and failure handling

The demo Integrator's access page with the three progress steps Approved, Ready for handshakes and Upstream accepted mTLS, and Renew and Revoke access controls.The demo Integrator's access page with the three progress steps Approved, Ready for handshakes and Upstream accepted mTLS, and Renew and Revoke access controls.

Retire the Workload when the job exits. Close the Context when the reconciliation itself ends. To withdraw one grant earlier, revoke its approval ID. After a denial, expiry or revocation, say how access ended and offer a fresh request.

The demo Integrator's page after revocation, explaining that open connections close by their lease deadline and pointing to the widget's Request access button for a fresh approval.The demo Integrator's page after revocation, explaining that open connections close by their lease deadline and pointing to the widget's Request access button for a fresh approval.

In the demo, the upstream requires a client certificate and returns the leaf fingerprint it actually received. Compare it with the identity selected in the Companion. Demo upstream