Certificates
This step is optional. By default, the Frontend (9000), the Public API (8000) and the Gateway (8001) respond over HTTPS with a self-signed certificate generated by SmartAGT. Traffic is encrypted, but clients do not recognize this certificate: the browser displays a warning and curl needs the -k option. This procedure installs your own certificates.
Until a trusted certificate is installed, encryption does not guarantee the identity of the server: a third party on the network could impersonate it. This trade-off suits a PoC. For lasting use, install your certificates.
In a cluster, every Frontend node receives its certificate during installation: SmartAGT generates it only on a single server. The Public API (8000) and the Gateway (8001) respond by default with a self-signed certificate generated by SmartAGT for every node. This procedure installs your certificates on the nodes, or renews them.
Clients reach SmartAGT through the reverse proxy and the load balancers. The certificate of the public name is installed on them, following their documentation. The node certificates authenticate every node to the reverse proxy and the load balancers.
The internal link between the Frontend and the API is managed by SmartAGT and needs no certificate. PostgreSQL encryption is prepared with PostgreSQL SSL.
Prerequisites
- Components installed: Install the Backend, Install the Frontend and, if you use it, Enable AI Gateway.
- For each interface to equip, a PEM certificate issued by your authority, with its intermediate chain, and its PEM private key usable without interactive entry.
- A SAN field covering the DNS name used by clients, for example
smartagt.example.test. - Client workstations and applications that trust your authority.
- A console with
sudo(Linux) or 64-bit PowerShell as administrator (Windows).
- Components installed on their nodes: Install the Backend, Install the Frontend and, if you use it, Enable AI Gateway.
- For each node and each interface to equip, a PEM certificate issued by your authority, with its intermediate chain, and its PEM private key usable without interactive entry.
- A SAN field covering the name under which the reverse proxy or the load balancer reaches this node, for example
platform-1.example.test. - A reverse proxy and load balancers that trust your authority.
- A console with
sudo(Linux) or 64-bit PowerShell as administrator (Windows).
Procedure
1. Place the files
Copy each certificate and its key to the TLS directory of the component, without changing the permissions of this directory:
On every node, copy the certificate of this node and its key to the TLS directory of the component:
| Interface | Directory | Files |
|---|---|---|
Frontend 9000 |
/app/config/bff/tls/ or C:\app\config\bff\tls\ |
server.crt, server.key |
Public API 8000 |
/app/config/backend/tls/ or C:\app\config\backend\tls\ |
server.crt, server.key |
Gateway 8001 |
/app/config/backend/tls/ or C:\app\config\backend\tls\ |
gateway.crt, gateway.key |
Each .crt file contains the server certificate followed by its intermediate certificates in chain order. The root authority is a trust anchor to install on the client side; SmartAGT does not require a ca.crt file to serve these interfaces.
Example for the Frontend:
sudo install -d -o svc-smartagt-bff -g svc-smartagt-bff -m 700 /app/config/bff/tls
sudo install -o svc-smartagt-bff -g svc-smartagt-bff -m 600 server.crt server.key /app/config/bff/tls/
For the Public API and the Gateway, use /app/config/backend/tls and the svc-smartagt-backend account. Copy the files listed in the table.
New-Item -ItemType Directory -Force C:\app\config\bff\tls | Out-Null
Copy-Item server.crt, server.key C:\app\config\bff\tls\
Services created by the installation procedure use SYSTEM. Restrict private key access to SYSTEM and administrators; if you use another service account, also grant it read access. For the Public API and the Gateway, use the Backend directory and the files listed in the table.
Expected result: every interface has its certificate and key in the directory of the table.
Example for a Platform node:
sudo install -d -o svc-smartagt-backend -g svc-smartagt-backend -m 700 /app/config/backend/tls
sudo install -o svc-smartagt-backend -g svc-smartagt-backend -m 600 server.crt server.key /app/config/backend/tls/
Files are restricted to the service account. On a Frontend node, use the Frontend directory and the svc-smartagt-bff account.
New-Item -ItemType Directory -Force C:\app\config\backend\tls | Out-Null
Copy-Item server.crt, server.key C:\app\config\backend\tls\
Restrict private key access to the service account, SYSTEM and administrators. For a Frontend node or a Gateway, adapt the directory and filenames using the table.
Expected result: on every node, every interface it carries has its certificate and key in the directory of the table.
2. Declare the certificates
In the YAML of the component, set the file paths. Merge these keys into the existing smartagt block.
On every node, in the YAML of the component, set the file paths. The paths are the same on every node, each one reading its own files. Merge these keys into the existing smartagt block. The Frontend nodes declare them since their installation.
In /app/config/bff/smartagt-bff-core.yaml:
smartagt:
http:
server:
certfile: /app/config/bff/tls/server.crt
keyfile: /app/config/bff/tls/server.key
In /app/config/backend/smartagt-backend-core.yaml:
smartagt:
http:
public:
certfile: /app/config/backend/tls/server.crt
keyfile: /app/config/backend/tls/server.key
In /app/config/backend/smartagt-backend-core.yaml:
smartagt:
gateway:
server:
certfile: /app/config/backend/tls/gateway.crt
keyfile: /app/config/backend/tls/gateway.key
On Windows, the YAML files are under C:\app\config\. Write the paths with /, for example C:/app/config/bff/tls/server.crt.
Expected result: every modified YAML declares certfile and keyfile once.
3. Restart the component
Restart only the modified components.
sudo systemctl restart smartagt-frontend-service # Frontend
sudo systemctl restart SmartAGT-Platform-Service # Public API
sudo systemctl restart SmartAGT-AI-Gateway-Service # Gateway
Restart-Service smartagt-frontend-service # Frontend
Restart-Service SmartAGT-Platform-Service # Public API
Restart-Service SmartAGT-AI-Gateway-Service # Gateway
Expected result: the browser opens https://smartagt.example.test:9000 without a certificate warning.
Restart the modified services, one node after the other: the other nodes keep serving.
sudo systemctl restart smartagt-frontend-service # Frontend
sudo systemctl restart SmartAGT-Platform-Service # Public API
sudo systemctl restart SmartAGT-AI-Gateway-Service # Gateway
Restart-Service smartagt-frontend-service # Frontend
Restart-Service SmartAGT-Platform-Service # Public API
Restart-Service SmartAGT-AI-Gateway-Service # Gateway
Expected result: on every node, curl --cacert <authority of your certificates> https://<node name>:<port>/ (curl.exe on Windows) completes without a certificate error.
Special cases
Make the certificate generated by SmartAGT trusted
A tool or an application verifies this certificate with the root specific to your installation. Export it on a Backend server:
read -rsp 'smartagt role password: ' SMARTAGT_CORE_DATABASE_PASSWORD; echo
export SMARTAGT_CORE_DATABASE_PASSWORD
cd /app/smartagt-backend-core
sudo --preserve-env=SMARTAGT_CORE_DATABASE_PASSWORD ./run.bin pki export-ca --output ~/smartagt-ca.pem --config /app/config/backend/smartagt-backend-core.yaml
$env:SMARTAGT_CORE_DATABASE_PASSWORD = [Net.NetworkCredential]::new('', (Read-Host 'smartagt role password' -AsSecureString)).Password
Set-Location C:\app\smartagt-backend-core
.\run.exe pki export-ca --output $HOME\smartagt-ca.pem --config C:\app\config\backend\smartagt-backend-core.yaml
Expected result: smartagt-ca.pem contains the root, without a private key, and the command displays its SHA-256 fingerprint.
Hand this file to each tool rather than to the global store of a workstation: curl --cacert, the verify parameter of SDKs, proxy_ssl_trusted_certificate in NGINX. The certificate covers the name and addresses of the server: a DNS alias, a NAT or a public name require your certificates.