Configuring SSL Certificates for Frends Agent
How to use your own SSL certificates for your Frends.
By default, the Frends Agent generates a self-signed certificate for its API and HTTP endpoints. While this works out of the box, production environments typically require a certificate issued by a trusted Certificate Authority (CA). This guide walks through installing and configuring your own SSL/TLS certificate for the Frends Agent on Windows, Linux, and Kubernetes, as well as how to use a PFX file directly without a certificate store.
Prerequisites
Before you begin, make sure you have the following ready:
A valid SSL/TLS certificate in
.pfxformat, or a certificate issued by a CA that you can export as a.pfxfileAccess to the Frends Control Panel with sufficient permissions to manage Agent Groups and Agent settings
Administrative access to the server or environment where the Agent is running
Prepare Your Certificate
Before touching any Agent configuration, you need your certificate available in .pfx format and its thumbprint at hand. How you obtain the thumbprint depends on the platform — on Windows you read it from the Certificate Manager UI, while on Linux and Kubernetes the CertificateTool prints it to the console after a successful import.
Whichever way you get it, the thumbprint must always be a hexadecimal string with no spaces, colons, or other separators, for example A1B2C3D4E5F6.... Certificate Manager in particular sometimes copies the value with a leading invisible character, so always verify the format before using it.
Platform-Specific Installation
The steps for importing the certificate and pointing the Agent to it differ between platforms. Follow the section that matches your deployment environment.
Windows
On Windows, the Agent reads its certificate from the Windows certificate store. The thumbprint of the installed certificate is then provided to the Agent through the Control Panel.
Open the Windows Certificate Manager by running certlm.msc. Navigate to Personal → Certificates, right-click and select All Tasks → Import, then follow the import wizard to import your .pfx file. If your environment requires it, also import the certificate chain into Trusted Root Certification Authorities.
Once the certificate is imported, open it in the store and go to the Details tab. Scroll down to the Thumbprint field and copy its value.
In the Frends Control Panel, navigate to the Agent settings within the Environments view. Paste the thumbprint value into the SSL Certificate thumbprint field and save. Download the Windows installer from the Control Panel after setting the thumbprint — the installer uses the thumbprint to automatically configure the correct CertificateStore value for Windows.
The Agent binds the certificate to its listener during installation, so simply updating the thumbprint in the Control Panel is not enough — you must reinstall the Agent Service for the new certificate binding to take effect.
If you downloaded the installer before adding the thumbprint, you will need to manually set CertificateStore to LocalMachine in appsettings.json to match the store where the certificate is installed.
Linux
On Linux, .NET does not use the system certificate store in the same way Windows does. Instead, certificates are imported using the GSoft CertificateTool bundled with the Agent, which writes them into the .NET cryptography store used by the Agent process.
Place your .pfx certificate file in a directory accessible by the Agent process, for example /secrets/. Then run the bundled CertificateTool using the following command:
Replace <PFX FileName> and <PFX Password> with the actual filename and password of your certificate. The tool will print the certificate thumbprint to the console once the import succeeds — copy this value for the next step.
Note: If you need to obtain the Cert Tool separately, you can use **ShareGate CertificateTool **in place of GSoft, it can be used in exactly the same way — simply replace
GSoft.CertificateTool.dllwithShareGate.CertificateTool.dllin the command above.
On Linux, the .NET certificate store used by the Agent is located at:
Set CertificateThumbprintOrPath in appsettings.json to the thumbprint printed by the CertificateTool, then restart the Agent for the change to take effect.
Kubernetes
On Kubernetes, the certificate is imported into the container's .NET store at startup using the CertificateTool, before the Agent process itself begins. This requires changes to both the secrets configuration file and the deployment YAML. You also need to set a default external address for the Agent Group before deploying.
Set a Default External Address
Before deploying, navigate to the target Agent Group in the Frends Control Panel and enter the fully qualified external address of your Agent into the Default External Address field, for example https://myagentfqdn.frendsapp.com. This field is only visible when the Allow new agents to connect to agent group option is enabled for the Agent Group. Save the changes — the address will be applied automatically the next time an Agent is deployed to this group.
Download the Kubernetes Configuration
Download and extract the Agent Kubernetes Configuration package from the Frends Control Panel. The downloaded package includes the FRENDS-Agent-Deploy.yaml deployment file and the /app/secrets/appsettings.secrets.json secrets file, both of which need to be modified to enable your own certificate.
Configure the Secrets File
Open /app/secrets/appsettings.secrets.json and set the certificateThumbprintOrPath field to the thumbprint of your certificate. Then copy your .pfx certificate file into the /app/secrets/ directory so it is available to the container at runtime.
Update the Deployment YAML
Open FRENDS-Agent-Deploy.yaml and locate the containers section. After the image clause and at the same indentation level, add the following two lines to override the default container startup command:
Replace <PFX FileName> and <PFX Password> with the filename and password of your certificate. These two lines tell the container to import the certificate into the .NET store before starting the Agent process.
Next, scroll to the volumes section and find the frends-agent-secrets volume. Under the items list, add a new entry for your certificate file:
Replace <PFX FileName> with the actual filename of your .pfx file. This makes the certificate file available inside the container via the secrets volume. With all changes saved, your Kubernetes configuration is ready to use your own SSL certificate on the next deployment.
Using a PFX File Directly
If you prefer not to import the certificate into a store, you can configure the Agent to read the certificate directly from a .pfx file on disk. This approach works on all platforms.
Place the .pfx file in a location readable by the Agent process, for example /app/secrets/cert.pfx, and set the following values in appsettings.json:
Restart the Agent after saving the changes. Always set an explicit value for CertificateThumbprintOrPath — if this field is left empty, the Agent will generate a new self-signed certificate each time it starts.
When updating the Agent, the new appsettings.json file must also be edited to use the same values, otherwise the certificate won't be used and a new self-signed certificate is generated and used instead.
Post-Installation
Once the certificate is in place and the Agent configuration has been updated, the Agent needs to be restarted for the changes to take effect.
Last updated
Was this helpful?