certforge-connector

certforge-connector is an open-source agent that automates certificate renewal for network devices — SBCs, voice gateways, load balancers — that live on private management VLANs unreachable by CertForge directly. GitHub: CertForge-LLC/certforge-connector

How it works

[CertForge cloud] ←── poll every 30s ──── [certforge-connector]
                                                    │
                                         reaches private VLAN
                                                    │
                                     [network device (SBC / F5 / gateway)]

The connector is stateless and requires no inbound firewall rules. It polls CertForge for pending renewal jobs, pulls a CSR from the device, has it signed (by CertForge or by your on-prem CA), and installs the certificate back on the device. Device credentials are not stored on the connector host. Username and password are entered in CertForge under Network Devices, stored AES-256-GCM encrypted, and delivered to the connector at job execution time — in memory, never written to disk.

Prerequisites

A CertForge account with at least one CA configured
The device registered under Integrations → Device Connectors in CertForge
TCP access from the connector host to the device management IP on its configured port (default 443)

Step 1 — Install the connector

Download the pre-built binary for your platform from the latest release:

Platform	File
Linux x86-64	`certforge-connector-linux-amd64`
Linux ARM64	`certforge-connector-linux-arm64`
macOS x86-64	`certforge-connector-darwin-amd64`
macOS Apple Silicon	`certforge-connector-darwin-arm64`
Windows x86-64	`certforge-connector-windows-amd64.exe`

# Linux
curl -LO https://github.com/CertForge-LLC/certforge-connector/releases/latest/download/certforge-connector-linux-amd64
chmod +x certforge-connector-linux-amd64
sudo mv certforge-connector-linux-amd64 /usr/local/bin/certforge-connector

# Windows (PowerShell)
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
New-Item -ItemType Directory -Force -Path C:\certforge-connector
Invoke-WebRequest -Uri https://github.com/CertForge-LLC/certforge-connector/releases/latest/download/certforge-connector-windows-amd64.exe `
    -OutFile C:\certforge-connector\certforge-connector.exe

Step 2 — Register devices in CertForge

Before the connector can renew a device cert, the device must be registered in CertForge:

Go to Integrations → Device Connectors
Click Register Device
Enter the device’s name, management IP, port, device type, and credentials
Click Save

The device UUID displayed on this page is what the connector uses to match renewal jobs.

Step 3 — Authenticate

The connector supports two authentication methods. mTLS is recommended — it connects directly to the CertForge agent endpoint, bypassing Cloudflare, and uses a pinned mutual-TLS certificate instead of a long-lived bearer token.

Option A — mTLS enrollment (recommended)

Generate an enrollment token in CertForge:

Go to Integrations → Connector Agents
Click + Enroll Agent and choose type Connector
Give it a label (e.g. office-connector)
Copy the one-time token

Run the enroll command on the connector host:

certforge-connector enroll \
  --token  <one-time-token>          \
  --url    https://app.certgov.app   \
  --label  office-connector          \
  --out    /etc/certforge-connector/creds

This writes three files to the --out directory:

File	Contents
`client.crt`	Client certificate — identifies this connector to CertForge
`client.key`	Client private key — keep this secret (mode 0600)
`server.crt`	Pinned CertForge agent CA certificate — no system trust store needed

The command also prints the exact mtls_* values to add to your config file.

# Secure the key file
chmod 600 /etc/certforge-connector/creds/client.key

Create certforge-connector.yaml:

certforge_url: https://app.certgov.app

# mTLS credentials (written by certforge-connector enroll)
mtls_host: usagent.certgov.app   # direct agent endpoint — printed by enroll
mtls_port: 8443                   # 8443 prod · 8444 preview/dev
mtls_cert: /etc/certforge-connector/creds/client.crt
mtls_key:  /etc/certforge-connector/creds/client.key
mtls_ca:   /etc/certforge-connector/creds/server.crt

poll_interval: 30s

When mtls_host / mtls_cert are set, api_key is not needed and is ignored. All traffic goes to port 8443 (or 8444 for preview environments) and bypasses Cloudflare.

Option B — API key (legacy)

Use an API key if mTLS enrollment is not available in your environment.

Go to Settings → API Keys
Click New API Key, choose the connector scope
Copy the key — shown once only

Store it in an environment variable:

export CERTFORGE_API_KEY=<your-key>

Create certforge-connector.yaml:

certforge_url: https://app.certgov.app

# API key from Settings → API Keys (connector scope)
api_key: $CERTFORGE_API_KEY

poll_interval: 30s

Step 4 — Run

Test (manual):

certforge-connector --config certforge-connector.yaml

Linux service (systemd):

[Unit]
Description=CertForge Connector
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/certforge-connector --config /etc/certforge-connector/certforge-connector.yaml
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Windows service (NSSM):

nssm install CertForgeConnector "C:\certforge-connector\certforge-connector.exe"
nssm set CertForgeConnector AppParameters "--config C:\certforge-connector\certforge-connector.yaml"
nssm set CertForgeConnector AppDirectory "C:\certforge-connector"
nssm start CertForgeConnector

Docker

docker run -d --restart unless-stopped \
  --network host \
  -v /etc/certforge-connector:/etc/certforge-connector:ro \
  ghcr.io/certforge-llc/certforge-connector:latest \
  --config /etc/certforge-connector/certforge-connector.yaml

--network host is required so the connector can reach devices on private management VLANs.

Azure Container Instances

To reach devices on a private Azure VNet, deploy the connector as an Azure Container Instance inside that VNet. See Connector in Azure.

Optional configuration

Local credential override

If you store device credentials in a local secrets manager rather than in CertForge, supply them via the devices: block. All other details come from CertForge automatically.

devices:
  - id: "00000000-0000-0000-0000-000000000000"  # UUID from CertForge → Device Connectors
    username: admin
    password: $SBC1_PASSWORD
  - id: "11111111-1111-1111-1111-111111111111"
    username: admin
    password: $SBC2_PASSWORD

Most deployments can omit the devices: block entirely.

No device jobs

Set no_device_jobs: true when this connector instance is dedicated exclusively to CA signing (no network devices to manage). Device job polling, cert reads, and version checks are skipped; CA inventory sync and approval-flow signing still work normally.

no_device_jobs: true

What the connector reports

Background cert discovery

On startup and every 6 hours, the connector TLS-dials each registered device and reads the leaf certificate — no device credentials needed. It reports the cert’s expiry date, Common Name, and SANs back to CertForge.

On-demand cert query

From the Device Connectors page, clicking Query Cert creates a pending_query job. The connector picks it up on its next poll and immediately reads and reports the current certificate.

Certificate renewal

When a cert enters its renewal window (configured in the matching Domain Trust Profile), CertForge creates a renewal job:

Connector polls GET /api/v1/connector/jobs and receives the job with device connection details and credentials
Connector authenticates to the device and pulls the CSR
CSR is submitted to CertForge; CertForge signs it with the configured CA
Connector installs the signed certificate on the device
Connector posts job completion; CertForge schedules the next renewal

All steps appear in the CertForge audit log.

On-prem CA signing (optional)

By default, CSRs are sent to CertForge for signing. If your signing CA is on-prem, you can configure the connector to sign locally while still enforcing your Domain Trust Policy through CertForge.

Vault PKI (server-configured)

The simplest setup: configure the Vault address, token, mount, and role in the CertForge UI under Integrations → CA Connectors, and assign the CA connector to this connector agent. The connector receives Vault credentials with each sign request — no local YAML needed for the CA config.

Vault PKI (YAML override)

Use the YAML block when you need to inject the Vault token from a local secrets manager or environment variable rather than storing it in CertForge:

private_ca:
  ca_connector_id: 00000000-0000-0000-0000-000000000000  # UUID from CertForge UI
  vault_pki:
    addr:  https://vault.example.com   # omit if set in CertForge UI
    token: $VAULT_TOKEN                # env var override
    mount: pki
    role:  certforge                   # optional signing role

File-based CA (OpenSSL, Easy-RSA, cfssl)

private_ca:
  ca_connector_id: 00000000-0000-0000-0000-000000000000
  cert: /etc/certforge-connector/ca.crt
  key:  /etc/certforge-connector/ca.key
  validity_days: 365                        # fallback; DTP policy takes precedence
  issued_certs_dir: /etc/pki/CA/newcerts    # for CA inventory sync
  crl_file: /etc/pki/CA/crl.pem           # optional

Multiple CAs

private_cas:
  - ca_connector_id: 00000000-0000-0000-0000-000000000000
    vault_pki:
      token: $VAULT_TOKEN_1
  - ca_connector_id: 11111111-1111-1111-1111-111111111111
    cert: /etc/ca/devices.crt
    key:  /etc/ca/devices.key

ca_connector_id is required for every private_ca or private_cas entry. Every local signing request is authorized by CertForge (DTP validation, key policy) before the CA key is used — the connector will refuse to start if this field is missing.

CA key security:

chmod 600 /etc/certforge-connector/ca.key
chown certforge-connector:certforge-connector /etc/certforge-connector/ca.key

How governed local signing works

Before signing any certificate, the connector calls CertForge to validate:

The device’s domain matches a Domain Trust Policy
The DTP is linked to the correct on-prem CA
Key strength and wildcard policy are satisfied

CertForge records the authorization server-side. If CertForge is unreachable, the connector will not sign — it is fail-closed. The signed certificate is reported back to CertForge for audit and inventory.

Supported device types

Type	Driver
AudioCodes Mediant (VE/E/SW/HW)	`audiocodes`
F5 BIG-IP (iControl REST, TMOS 11.6+)	`f5`
Ribbon SWe-Lite SBC (REST API)	`ribbon`

AudioCodes Mediant on firmware 7.60A or later with the ACME license option can request certificates directly from CertForge via the ACME protocol — no connector required. If your Mediant is running 7.60A+ and the ACME feature is licensed, see ACME Setup instead. The audiocodes connector driver is the right choice for devices without the ACME license, regardless of firmware version.

The Device Type dropdown in CertForge is populated automatically from the types the running connector reports — no manual entry and no CertForge update required to support a new driver. Additional drivers can be added by implementing the Device interface. See Adding a device type in the connector README.

Monitoring connector activity

In CertForge under Integrations → Connector Agents, each agent shows version, last seen timestamp, poll interval, number of CA connectors assigned, and number of devices connected.

Security

Firewall / egress requirements

The connector requires outbound HTTPS only — no inbound ports are needed.

Destination	Port	Required when
`app.certgov.app` / `eu.certgov.app`	443	Always (API key auth or Cloudflare-proxied)
`usagent.certgov.app` / `eu-agent.certgov.app`	8443	mTLS auth — direct agent endpoint
Your Vault address	443 (or custom)	Only if `vault_pki:` is configured
Device management IPs	443 (default)	Always — stays on the local VLAN

mTLS certificate rotation

The mTLS client certificate has a fixed validity period. When it nears expiry, re-run certforge-connector enroll with the same --label to issue a new credential set. The old certificate continues to work until the new one is deployed. To revoke a certificate immediately: go to Integrations → Connector Agents, find the agent, and click Revoke Cert.

Local credential overrides

Treat devices: YAML entries as an advanced, higher-risk configuration:

Use environment variable expansion ($SBC1_PASSWORD) — never hardcode secrets in the file.
Restrict YAML file permissions (chmod 600 certforge-connector.yaml).
The preferred path is to store credentials in CertForge, which encrypts them at rest (AES-256-GCM) and delivers them only at job time.

TLS to devices

skip_verify: true disables TLS certificate checking for device management connections. Use only when the device uses a self-signed management certificate and you cannot install a trusted CA for it.

Troubleshooting

Connector connects but devices show no cert data

Verify TCP access from the connector host to the device management IP and port
Check the device is set to Active on the Device Connectors page
Run manually (certforge-connector --config certforge-connector.yaml) to see log output

tls: internal error on cert read The device management interface may use a self-signed certificate. Set skip_verify: true in the device registration form in CertForge for that device. Jobs are created but never picked up The connector polls every poll_interval (default 30s). If jobs remain pending after a few cycles, check:

Connector is running and can reach CertForge
Connector is connected (check Integrations → Connector Agents)
Device is set to Active in CertForge

error: mTLS handshake failed

Confirm mtls_cert, mtls_key, and mtls_ca paths are correct and readable by the connector process
Confirm mtls_host matches the hostname printed by certforge-connector enroll
Confirm mtls_port is 8443 (prod) or 8444 (preview/dev)

Renewal completed but cert wasn’t installed Check the audit log in CertForge for connector.cert_signed events. If the CSR was submitted and signed but install failed, the connector log will show the device API error. CA signing — sign request never picked up If a CA connector is configured via the CertForge UI (not via YAML private_ca), ensure the CA connector is assigned to this connector agent in Integrations → CA Connectors → Edit. The agent only picks up sign requests for CA connectors explicitly assigned to it.

​How it works

​Prerequisites

​Step 1 — Install the connector

​Step 2 — Register devices in CertForge

​Step 3 — Authenticate

​Option A — mTLS enrollment (recommended)

​Option B — API key (legacy)

​Step 4 — Run

​Docker

​Azure Container Instances

​Optional configuration

​Local credential override

​No device jobs

​What the connector reports

​Background cert discovery

​On-demand cert query

​Certificate renewal

​On-prem CA signing (optional)

​Vault PKI (server-configured)

​Vault PKI (YAML override)

​File-based CA (OpenSSL, Easy-RSA, cfssl)

​Multiple CAs

​How governed local signing works

​Supported device types

​Monitoring connector activity

​Security

​Firewall / egress requirements

​mTLS certificate rotation

​Local credential overrides

​TLS to devices

​Troubleshooting

How it works

Prerequisites

Step 1 — Install the connector

Step 2 — Register devices in CertForge

Step 3 — Authenticate

Option A — mTLS enrollment (recommended)

Option B — API key (legacy)

Step 4 — Run

Docker

Azure Container Instances

Optional configuration

Local credential override

No device jobs

What the connector reports

Background cert discovery

On-demand cert query

Certificate renewal

On-prem CA signing (optional)

Vault PKI (server-configured)

Vault PKI (YAML override)

File-based CA (OpenSSL, Easy-RSA, cfssl)

Multiple CAs

How governed local signing works

Supported device types

Monitoring connector activity

Security

Firewall / egress requirements

mTLS certificate rotation

Local credential overrides

TLS to devices

Troubleshooting