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 → Network Devices in CertForge
A connector API key (see below)
TCP access from the connector host to the device management IP on its configured port (default 443)

Step 1 — Create a connector API key

The connector authenticates to CertForge with a scoped API key. These keys can only reach the /api/v1/connector/ endpoints.

Go to Settings → API Keys
Click New API Key
Give it a descriptive name (e.g. office-connector)
Check the connector scope
Click Create
Copy the key — it is shown once only

Store it in an environment variable, not in the YAML config file:

# Linux / macOS
export CERTFORGE_API_KEY=<your-key>

# Windows (PowerShell)
$env:CERTFORGE_API_KEY = "<your-key>"

Step 2 — Register devices in CertForge

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

Go to Integrations → Network Devices
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. Once the connector is running, the Device Type dropdown is populated automatically from the types the connector reports — no manual entry required.

Step 3 — Install the connector

Binary (recommended)

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

# Force TLS 1.2 (required on older 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

Docker

docker run -d --restart unless-stopped \
  --network host \
  -e CERTFORGE_API_KEY=<your-key> \
  -v /etc/certforge-connector/certforge-connector.yaml:/etc/certforge-connector/certforge-connector.yaml:ro \
  ghcr.io/certforge-llc/certforge-connector:latest

--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 (F5 BIG-IP, Ribbon SBC, etc.), deploy the connector as an Azure Container Instance inside that VNet. No inbound ports are required. See Connector in Azure for the full step-by-step guide.

Step 4 — Configure

Create certforge-connector.yaml (start from certforge-connector.yaml.example in the release):

# URL of your CertForge instance
certforge_url: https://app.certgov.app

# API key from Settings → API Keys (connector scope)
# Always load from an environment variable
api_key: $CERTFORGE_API_KEY

# How often to poll for pending jobs (default 30s)
poll_interval: 30s

That’s the entire required config. Device topology — host, port, type, and credentials — is stored in CertForge and delivered with each renewal job automatically.

Local credential override (optional)

If you store device credentials in a local secrets manager rather than in CertForge, you can supply them via the devices: block. List one entry per device with the CertForge device UUID, username, and password. All other details come from CertForge automatically.

devices:
  - id: "00000000-0000-0000-0000-000000000000"  # UUID from CertForge → Network Devices
    username: admin
    password: $SBC1_PASSWORD
  - id: "11111111-1111-1111-1111-111111111111"
    username: admin
    password: $SBC2_PASSWORD
  - id: "22222222-2222-2222-2222-222222222222"
    username: readonly
    password: $F5_PASSWORD

Most deployments can omit the devices: block entirely.

Step 5 — Run

Test (manual):

# Linux / macOS
CERTFORGE_API_KEY=<your-key> certforge-connector -config certforge-connector.yaml

# Windows
$env:CERTFORGE_API_KEY = "<your-key>"
.\certforge-connector.exe -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
EnvironmentFile=/etc/certforge-connector/env
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Put the API key in /etc/certforge-connector/env:

CERTFORGE_API_KEY=<your-key>

Windows service (NSSM): Download NSSM and from an elevated command prompt:

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 set CertForgeConnector AppEnvironmentExtra "CERTFORGE_API_KEY=<your-key>"
nssm set CertForgeConnector Start SERVICE_AUTO_START
nssm start CertForgeConnector

What the connector reports

Once running, the connector performs the following automatically:

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. CertForge uses this to populate the Expires, DTP, and Renewal in columns on the Network Devices page before any renewal job has run.

On-demand cert query

From the Network Devices 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 and you do not want CSRs leaving the network, you can configure the connector to sign locally while still enforcing your Domain Trust Policy through CertForge.

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.

Setup

Go to Settings → CA Connectors and add a Private / Internal CA (On-Prem Agent) connector. This automatically creates a CA record in CertForge that can be referenced in Issuance Profiles and Domain Trust Policies.
Create an Issuance Profile pointing to this CA, then assign it in a Domain Trust Policy covering your device domains.
Add the CA key and certificate to certforge-connector.yaml. Use the ca_connector_id from the CA connector record in CertForge:

private_ca:
  cert: /etc/certforge-connector/ca.crt   # PEM CA certificate
  key:  /etc/certforge-connector/ca.key   # PEM CA private key (RSA or ECDSA)
  validity_days: 365                       # fallback; DTP policy takes precedence
  ca_connector_id: 00000000-0000-0000-0000-000000000000  # from CertForge UI

ca_connector_id is required. The connector will refuse to start if a private_ca or private_cas entry is present without a ca_connector_id. Every local signing request must be authorized by CertForge (DTP validation, key policy) before the CA key is used — no exceptions.

CA key security: the CA private key is loaded from disk on the connector host. Restrict file permissions to the connector process user:

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

For higher-assurance environments, consider a passphrase-protected key or loading it from a local secrets manager (HashiCorp Vault, AWS Secrets Manager, etc.). If you manage multiple on-prem CAs, use private_cas: to list them:

private_cas:
  - ca_connector_id: 00000000-0000-0000-0000-000000000000
    cert: /etc/ca/internal.crt
    key:  /etc/ca/internal.key
  - ca_connector_id: 11111111-1111-1111-1111-111111111111
    cert: /etc/ca/devices.crt
    key:  /etc/ca/devices.key

CA inventory sync

When ca_connector_id is set, the connector can also push the CA’s issued certificate inventory into CertForge Discovery. Add an inventory source to the private_ca block: File-based CAs (OpenSSL, Easy-RSA, cfssl):

private_ca:
  cert: /etc/certforge-connector/ca.crt
  key:  /etc/certforge-connector/ca.key
  ca_connector_id: 00000000-0000-0000-0000-000000000000
  issued_certs_dir: /etc/pki/CA/newcerts   # directory of PEM cert files
  crl_file: /etc/pki/CA/crl.pem           # optional — revoked certs excluded

HashiCorp Vault PKI:

private_ca:
  cert: /etc/certforge-connector/ca.crt
  key:  /etc/certforge-connector/ca.key
  ca_connector_id: 00000000-0000-0000-0000-000000000000
  vault_pki:
    addr: https://vault.example.com
    token: $VAULT_TOKEN
    mount: pki

Inventory syncs on startup and every 6 hours. Pushed certs appear in Discovery with governance_status=tracked.

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`

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, each device shows:

Column	Source
Cert CN	Read from the device’s current certificate
DTP	Domain Trust Profile matched from the cert’s CN
Expires	Certificate notAfter date
Renewal in	Days until the DTP-configured renewal window opens
Last Seen	Timestamp of the connector’s most recent touchpoint
Status	Active / Inactive (toggled manually)

Inactive devices are excluded from connector job lists — the connector will not attempt renewal or query jobs for them.

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 Network Devices 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 app.certgov.app
API key has the connector scope
Device is set to Active in CertForge

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. Local signing denied by CertForge If you see local signing denied in the connector log, check:

The device domain matches a Domain Trust Policy
The DTP is linked to the on-prem CA connector record
The ca_connector_id in certforge-connector.yaml matches the record in CertForge

private CA has no ca_connector_id at startup The connector refuses to start if a private_ca or private_cas entry lacks ca_connector_id. Add the connector record in CertForge (Settings → CA Connectors), copy its ID, and add ca_connector_id: <id> to the YAML entry. See On-prem CA signing above.

Security

Firewall / egress requirements

The connector requires outbound HTTPS (port 443) only — no inbound ports are needed.

Destination	Port	Required when
`app.certgov.app` (US) or `eu.certgov.app` (EU)	443	Always
Your Vault address	443 (or custom)	Only if `vault_pki:` is configured
Device management IPs (private VLAN)	443 (default)	Always — stays on the local VLAN

Local credential overrides

If you supply device credentials via the devices: block in YAML (rather than storing them in CertForge), treat this 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) so only the connector process can read it.
The preferred path is to store credentials in CertForge, which encrypts them at rest (AES-256-GCM) and delivers them only at job time. YAML overrides are intended for environments where credentials must come from a local secrets manager.

TLS to devices

skip_verify: true disables TLS certificate checking for device management connections. It should only be used when the device uses a self-signed management certificate and you cannot install a trusted CA for it. Surface this prominently in device inventories and plan to replace self-signed management certs where possible.

​How it works

​Prerequisites

​Step 1 — Create a connector API key

​Step 2 — Register devices in CertForge

​Step 3 — Install the connector

​Binary (recommended)

​Windows

​Docker

​Azure Container Instances

​Step 4 — Configure

​Local credential override (optional)

​Step 5 — Run

​What the connector reports

​Background cert discovery

​On-demand cert query

​Certificate renewal

​On-prem CA signing (optional)

​How governed local signing works

​Setup

​CA inventory sync

​Supported device types

​Monitoring connector activity

​Troubleshooting

​Security

​Firewall / egress requirements

​Local credential overrides

​TLS to devices

How it works

Prerequisites

Step 1 — Create a connector API key

Step 2 — Register devices in CertForge

Step 3 — Install the connector

Binary (recommended)

Windows

Docker

Azure Container Instances

Step 4 — Configure

Local credential override (optional)

Step 5 — Run

What the connector reports

Background cert discovery

On-demand cert query

Certificate renewal

On-prem CA signing (optional)

How governed local signing works

Setup

CA inventory sync

Supported device types

Monitoring connector activity

Troubleshooting

Security

Firewall / egress requirements

Local credential overrides

TLS to devices