HTTPS, Certificates, and Browser Trust

Browser-based transform setup can only call your transform server after the browser trusts the server's HTTPS certificate. This is separate from SDK authentication and separate from CORS.

Use this checklist before debugging SDK behavior:

1. Open https://<server-url>/swagger#/ in the same browser used for setup.
2. Confirm that Swagger loads without a certificate warning.
3. Call https://<server-url>/seed only after the browser trusts the HTTPS certificate.
4. Debug CORS or SDK authentication only after HTTPS trust works.

If the browser shows a certificate error such as ``ERR_CERT_AUTHORITY_INVALID``, the browser rejected the TLS connection before the SDK received the request. Changing CORS headers, SDK auth settings, or transform code will not fix that error. If Chromium shows ``ERR_SSL_KEY_USAGE_INCOMPATIBLE``, regenerate the certificate with ``digitalSignature`` included in ``keyUsage``.

Choosing a Certificate Setup

For production and hosted customer deployments, prefer a certificate from a publicly trusted certificate authority or terminate HTTPS at a reverse proxy that presents a publicly trusted certificate.

For internal, lab, or local development deployments, you may use an internal CA or self-signed certificate. In that case, every user who accesses the transform server from a browser must trust the relevant certificate material:

• If your server certificate is signed by an internal or local root CA, install and trust that root CA certificate. This is the preferred internal setup because the server certificate can be renewed or replaced without asking users to trust each new leaf certificate.
• If you only have a single self-signed server certificate, install and trust that server certificate. If the server certificate changes, users must trust the new certificate again.

The certificate must also match the hostname users open in the browser. The hostname must be present in the certificate's Subject Alternative Names (SANs), for example localhost, 127.0.0.1, or transforms.example.com.

Localhost Development

For local HTTPS development, generate a local certificate and key as shown in the "Installing and Setting Up the SDK" article's SSL Certificate Generation section. If your tool created a local root CA, trust the root CA. If it created only a self-signed server certificate, trust the server certificate.

Then verify the browser path:

https://localhost:3000/swagger#/

The local server URL, certificate SANs, and the hostname in the browser must match. A certificate for localhost does not automatically cover a custom hostname, and a certificate for a custom hostname does not automatically cover 127.0.0.1.

Installing Trust on User Machines

Exact steps vary by operating system and company policy. The certificate file is usually a root CA certificate from your organization or local development tool. If you only have a self-signed server certificate, use that certificate instead.

macOS

Install the certificate into the System keychain:

sudo security add-trusted-cert -d -r trustRoot \
    -k "/Library/Keychains/System.keychain" <certificate-file>

Verify that it is present:

security find-certificate -a -c "<certificate-name>" \
    /Library/Keychains/System.keychain

Windows

Import the certificate into the trusted root store for the machine:

1. Open mmc.exe.
2. Add the Certificates snap-in for Computer account.
3. Open Trusted Root Certification Authorities -> Certificates.
4. Import the root CA certificate, or the self-signed server certificate if no root CA exists.
5. Restart the browser.

Debian and Ubuntu

Copy the certificate to the system CA directory using a .crt destination filename, then update the CA store:

sudo cp <certificate-file> /usr/local/share/ca-certificates/<certificate-name>.crt
sudo update-ca-certificates

Restart the browser after updating the trust store.

Firefox

Firefox may use its own certificate store depending on browser and enterprise configuration. If the certificate is trusted by the operating system but Firefox still shows a certificate warning, import the same root CA certificate into:

Settings -> Privacy & Security -> Certificates -> View Certificates -> Authorities

Trust it for websites, then restart Firefox.

Reverse Proxies and Ingress

If a reverse proxy or ingress terminates HTTPS, the browser validates the proxy certificate. The transform server can listen on HTTP or use an internal certificate behind the proxy; that backend connection is controlled by your infrastructure. From the browser's point of view, the public proxy certificate is what must be trusted.

When using a proxy, also make sure the SDK advertises the public HTTPS URL in seed and discovery responses. Use MALTEGO_SERVER_ROOT_URL for an explicit public URL, or configure trusted forwarded headers as described in the "Server Configuration" article's section on seed URLs behind a reverse proxy or ingress.

CORS and HTTPS Trust Are Different

CORS controls whether a browser application is allowed to read responses from a server after the TLS connection succeeds. Certificate trust controls whether the browser is willing to connect to the server at all.

Use this order when debugging browser-based setup:

1. Open https://<server-url>/swagger#/ and fix certificate trust until it loads without browser warnings.
2. Open or call https://<server-url>/seed.
3. If browser developer tools show CORS errors, configure CORS as described in the "Server Configuration" article's CORS Configuration section.
4. If the server returns 401 or 403, debug SDK authentication settings.