# Configuring SSL Certificates for Frends Agent 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 `.pfx` format, or a certificate issued by a CA that you can export as a `.pfx` file * Access 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: ``` dotnet --roll-forward Major /opt/frends-agent-linux/CertTool/GSoft.CertificateTool.dll add \ -f /secrets/ \ --password \ --store-name My ``` Replace `` and `` 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.dll` with `ShareGate.CertificateTool.dll` in the command above. On Linux, the .NET certificate store used by the Agent is located at: ``` /opt/frends-agent-linux/.dotnet/corefx/cryptography/x509stores/my ``` 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.

External address for Kubernetes deployments.

#### 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: ``` command: ["/bin/bash","-c"] args: ["dotnet --roll-forward Major /app/CertTool/GSoft.CertificateTool.dll add -f /app/secrets/ --password --store-name My && dotnet Frends.Agent.dll"] ``` Replace `` and `` 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.

Example FRENDS-Agent-Deploy.yaml file contents for Containers.

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: ``` - key: path: ``` Replace `` 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.

Example of FRENDS-Agent-Deploy.yaml file at volumes section.

## 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`: ``` "CertificateThumbprintOrPath": "/app/secrets/cert.pfx", "CertificatePassword": "your-certificate-password" ``` 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.frends.com/guides/setup-and-installation/configuring-ssl-certificates-for-frends-agent.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.