Aidbox Docs

How to configure Aidbox to use a proxy for outgoing requests

Objectives

  • Route Aidbox outbound HTTP / HTTPS traffic through a corporate proxy.
  • Trust a corporate CA used for proxy SSL inspection.
  • Diagnose SSL errors when fetching FHIR packages from fs.get-ig.org.
  • Know which fallback to reach for in air-gapped environments.

Before you begin

  • You have a proxy host / port from your network team.
  • If the proxy performs SSL inspection, you have the corporate root CA certificate (.crt / .pem).
  • You can build a custom container image based on healthsamurai/aidboxone.

Configure the HTTP / HTTPS proxy

Aidbox uses Java's standard networking stack, so the proxy is configured through JAVA_OPTS. Set both https.* and http.* so package downloads, webhook deliveries, terminology lookups, and any other outbound calls go through the proxy.

# docker-compose.yaml
services:
  aidbox:
    environment:
      JAVA_OPTS: >-
        -Dhttps.proxyHost=proxy.corp.example.com
        -Dhttps.proxyPort=8080
        -Dhttp.proxyHost=proxy.corp.example.com
        -Dhttp.proxyPort=8080
        -Dhttp.nonProxyHosts=localhost|127.0.0.1|*.svc.cluster.local

This setting proxies all outbound requests from Aidbox, including AidboxTopicDestination webhook deliveries, GCP Pub/Sub clients, and external terminology calls. Add internal hosts you want to reach directly to http.nonProxyHosts.

See Java networking properties reference for the full property list.

Install a corporate CA certificate

If your proxy performs SSL inspection it presents an internally-signed certificate when Aidbox connects to https://fs.get-ig.org (or any other upstream). Java rejects it because the corporate root CA is not in the default truststore. Add the CA to the JVM's cacerts keystore at image build time:

FROM healthsamurai/aidboxone:edge

COPY corporate-ca.crt /tmp/corporate-ca.crt

RUN keytool -importcert -trustcacerts \
      -keystore "$JAVA_HOME/lib/security/cacerts" \
      -storepass changeit -noprompt \
      -alias corporate-ca \
      -file /tmp/corporate-ca.crt \
 && rm /tmp/corporate-ca.crt

If the proxy issues a chain (intermediate + root), import each certificate with a unique alias.

Verify the certificate was added: keytool -list -keystore "$JAVA_HOME/lib/security/cacerts" -storepass changeit -alias corporate-ca.

Troubleshooting SSL errors when fetching FHIR packages

Since Aidbox 2602 the HTTP client uses Java's standard JSSE SSL stack. JSSE is stricter than the previous client and surfaces certificate-chain problems that earlier versions silently tolerated.

Symptoms — startup fails to bootstrap BOX_BOOTSTRAP_FHIR_PACKAGES, or Artifact Registry package install errors with one of:

  • SSL peer shut down incorrectly
  • EOFException thrown from sun.security.ssl.SSLSocketInputRecord.read
  • unable to find valid certification path to requested target
  • PKIX path building failed

Root cause — corporate proxy SSL inspection presents a certificate signed by an internal CA that the JVM does not trust. The fs.get-ig.org certificate itself is healthy (Google Trust Services chain) — the failure is at the proxy hop, not at the upstream.

Fix order:

  1. Confirm whether you are behind a proxy with SSL inspection: openssl s_client -connect fs.get-ig.org:443 -servername fs.get-ig.org. If the issuer is not Google Trust Services, the proxy is intercepting.
  2. Configure the proxy via JAVA_OPTS (above).
  3. If SSL inspection is enabled, install the corporate CA (above).
  4. As a workaround for air-gapped or otherwise restricted environments, skip the network entirely — see Loading packages from local filesystem.
  5. Or point Aidbox at an internal package mirror (Verdaccio, Nexus, etc.) using BOX_FHIR_NPM_PACKAGE_REGISTRY.

Disabling SSL verification (-Dcom.sun.net.ssl.checkRevocation=false, custom permissive truststores, etc.) silences the symptom but exposes Aidbox to MITM attacks on every outbound call. Fix the trust chain instead.

See also

Last updated: