Docs · Administration

Network and certificates

When a company firewall inspects encrypted traffic, trust its certificate once and every connection out of Mosaic works again.

#The error this fixes

A call out of Mosaic fails with one of these:

self-signed certificate in certificate chain

unable to get local issuer certificate

It can be the agent drafting a query, a chat answer, a REST data source, a webhook. The browser on the same machine opens the same address without complaint.

The usual cause is a company firewall that inspects encrypted traffic: Zscaler, Netskope, Palo Alto Networks, Fortinet and others. It opens each HTTPS connection, reads it, and signs it again with the company's own root certificate. Windows and the browsers trust that root because IT installed it there. Mosaic runs on Node.js, which keeps its own list of trusted authorities and does not read the one in Windows — so to Mosaic, the firewall looks like somebody in the middle. It is right to refuse until told otherwise.

The other cause is a server inside your network with a certificate of its own, not one issued by a public authority.

Either way, the fix is to tell Mosaic to trust that one certificate. Owners do it under Tenancy → Network. It applies to every new connection straight away, with no restart.

#Trust it from a check

Open Tenancy → Network.
Under Check a connection, type the address that failed — for the agent, https://api.openai.com or your model's address — and press Check.
Mosaic opens a secure connection there and lists the certificates it was shown, the server's own first. Nothing is sent to the service.
When a certificate it was shown would fix it, that one has a Trust button: usually the last, marked Root, named after your company or its firewall.
Press Trust. Mosaic shows its SHA-256 fingerprint and asks you to confirm. Check it with your IT team if you are unsure — they can read it from the same certificate on their side.

The check runs again on its own and says This server accepts the connection. Run the agent, the source or the webhook again.

#Import a certificate file

Some firewalls and servers do not send their root with the connection. The check then says the connection is signed by a certificate that was not sent with it, and offers nothing to trust. Get the file instead:

From your IT team. Ask for the root certificate of the firewall or the internal authority.
From Windows yourself. Open certmgr.msc (or certlm.msc for the whole machine), go to Trusted Root Certification Authorities → Certificates, open the one your company installed, and on Details press Copy to File…. Choose Base-64 encoded X.509 (.CER).

Then press Import certificate… under Trusted certificates and choose the file. Mosaic reads .pem, .crt and .cer, as Base-64 text or binary DER, and a file holding several certificates. A .p7b bundle is not read: export the root on its own.

A file that also holds a private key is refused. Mosaic needs only the certificate, and the key should stay where it was.

#The list

Trusted certificates shows each one with who signed it, until when it is valid, its fingerprint, and who added it and when. Certificates added here are trusted on top of the public authorities Mosaic already trusts, never instead of them.

Remove stops trusting one. New connections that depended on it are refused again; connections already open finish what they are doing.

An expired certificate is marked Expired. Trusting a certificate never makes an expired one acceptable: if a server's own certificate has run out, it has to be renewed where it is installed.

#Who can, and what is recorded

Owners only. Where the licence names the installation's owner, only that person can add or remove certificates; other owners can still run a check.
Adding one asks for your password when you signed in more than ten minutes ago.
Each certificate trusted or removed is written to the audit trail, with its name and fingerprint. See Storage and the audit trail.
On Mosaic Cloud there is no Network part: connections leave from Mosaic's servers, which trust the public authorities. Contact support if a service of yours needs another.

A self-hosted installation that runs its web server and its workers as separate processes picks a change up in the other processes within a minute.

#Without the screen

NODE_EXTRA_CA_CERTS, Node's own setting, still works: set it to the path of a PEM file before starting Mosaic. It is read only at start-up, which is why the screen exists. A certificate given that way does not appear in the list.

For a single REST source with its own certificate, turning off Verify TLS certificate in its settings also gets past the error — for that source only, and without checking who is on the other end. Trusting the certificate here keeps the check.