Manage Certificates

Agent Factory uses SSL/TLS certificates for two purposes. Inbound certificates secure the connection between users’ browsers and the Agent Factory web application. Outbound certificates allow Agent Factory to verify the HTTPS endpoints that it calls.

Manage Inbound Certificates

This section explains how to generate or import inbound, browser-facing certificates. Agent Factory includes self-signed certificates by default. These certificates can trigger an “insecure connection” warning in some browsers but do not affect application functionality. You can generate your own self-signed certificates or import certificates issued by a trusted certificate authority (CA) to remove this warning.

Note: Adding your own SSL certificates won’t remove the warning unless the certificate is issued by a CA that the browser trusts, and the hostname matches the certificate.

Generate Your Own SSL Certificates

To generate your own self-signed SSL certificates, use one of the following commands from your staging location.

  1. Generate certificates for both a hostname and IP address:

    make certificates FQDN=<yourhostfqdn.example.com> IP_ADDRESS=<your.ip.address>

  2. Generate certificates for an IP address only:

    make certificates IP_ADDRESS=<your.ip.address>

  3. Generate certificates for a hostname only:

    make certificates FQDN=<yourhostfqdn.example.com>

The generated certificates replace the default self-signed certificates used by the application.

Important: Self-signed certificate generation uses the host name that you provide, or the host name detected by the host. Very long fully qualified domain names can exceed certificate subject limits. If certificate generation fails for a long host name, use a shorter DNS name or import a CA-issued certificate with the required Subject Alternative Name (SAN).

Import Your Own Certificates

To remove the browser warning, use your preferred method and certificate authority to generate certificates issued by a trusted CA. Many certificate authorities require that the VM hosting the application has a public DNS name.

You need a certificate file and a key file.

  1. Go to your staging location.

    cd </path/to/your/staging/location>

  2. Import your certificates.

    make install-certificates CERT_FILE=/path/fullchain.pem KEY_FILE=/path/key.pem

After completing these steps, the next time you access the application, the browser will show the new certificate information. If the certificate was issued by a trusted CA, the browser warning should no longer appear.

Note: SSL/TLS certificate selection, procurement, installation, renewal, and trust configuration are handled by the user or the organization operating the deployment. Agent Factory does not validate or manage third-party certificates; it only provides a mechanism to import and use certificates you supply.

Inbound Certificate Troubleshooting

Symptom Likely cause Action
Browser still warns after import Certificate is self-signed, not trusted by the browser, expired, or does not match the host name. Use a CA-issued certificate trusted by users’ browsers and make sure the SAN includes the application host name.
Import fails with invalid certificate or key File path is wrong, file is not PEM formatted, key does not match certificate, or permissions prevent reading. Verify file paths, PEM content, and certificate/key pairing before importing.
Certificate generation fails for a long FQDN Host name exceeds certificate subject length limits. Use a shorter DNS name or import a certificate generated outside Agent Factory.
SSO or MCP callback fails after certificate/DNS changes Provider callback URLs still point to the old host name. Update SSO, REST OAuth, and MCP provider callback URLs to the browser-facing URL.

Manage Outbound Certificates

This section explains how to add trusted CA certificates for outbound connections, such as LLM and embedding providers, REST API tools, and MCP servers.

Administrators with shell access to the Agent Factory container can also use aaictl to manage outbound certificates. For more information, see Agent Factory CLI.

Before You Begin

Java keystores, PKCS#12 files, and private-key files are not supported.

Add an Outbound Certificate

Currently, you add outbound certificates through the administrator API. Sign in to Agent Factory as an administrator, obtain the session cookie for that authenticated session, and send the certificate as multipart form data in a field named certificate.

Tip: Save the administrator session cookie in an environment variable by running the following command:

BASE_URL='https://your-agent-factory-host:8080'

export AGENT_FACTORY_SESSION="$(
  curl -sk -D - -o /dev/null --location "$BASE_URL/agentFactory/v1/loginValidation" \
    --user "<admin_email>:<app_password>" \
    --header "Origin: $BASE_URL" \
  | tr -d '\r' \
  | awk -F'[=;]' '/agent_factory_session=/{print $2; exit}'
)"

Use the value as agent_factory_session=$AGENT_FACTORY_SESSION in the Cookie header. Do not share the session cookie or application password.

BASE_URL='https://your-agent-factory-host:8080'

curl -k --location "$BASE_URL/agentFactory/v1/certs" \
  --header "Origin: $BASE_URL" \
  --header "Cookie: agent_factory_session=$AGENT_FACTORY_SESSION" \
  --form 'certificate=@"/path/to/private-ca.crt"'

Replace the host and certificate path with values from your environment. Do not share session cookies or private keys.

Agent Factory validates and normalizes supported certificate files, skips duplicate certificates, and updates the managed outbound trust store. A successful request returns 201 Created when it adds a certificate. It returns 200 OK if every certificate in the submitted file was already present.

Test Connection

Repeat the connection test for the affected endpoint. LLM and embedding connections detect the updated trust store without restarting Agent Factory. REST API and MCP connection tests use the updated trust store on their next test.

To view administrator-added certificates, send a GET request to the same endpoint:

curl -k --location "$BASE_URL/agentFactory/v1/certs" \
  --header "Origin: $BASE_URL" \
  --header "Cookie: agent_factory_session=$AGENT_FACTORY_SESSION"

The response includes the number of added certificates and non-sensitive metadata, such as the original filename, subject, issuer, validity dates, and SHA-256 fingerprint. It does not expose certificate contents, private keys, or internal file paths.

If the connection still fails, verify that you uploaded the correct CA or intermediate certificate. Also check the endpoint host name, network access, proxy configuration, and endpoint credentials. A valid certificate file does not by itself prove that it completes the target endpoint’s certificate chain.

Reset Outbound Certificates

To remove all certificates added through this feature and restore the default outbound trust store, send the following request:

curl --request POST "$BASE_URL/agentFactory/v1/certs/reset" \
  --header "Origin: $BASE_URL" \
  --header "Cookie: agent_factory_session=$AGENT_FACTORY_SESSION"

Reset removes only certificates added for outbound connections. It restores the generated base trust store, which includes Certifi and Oracle Linux root certificates. It does not change the browser-facing certificates imported with make install-certificates.

Outbound Certificate Troubleshooting

Symptom Action
Unsupported certificate file Use a .pem, .crt, .cer, .p7b, or .p7c file.
The uploaded file is not a valid certificate Verify that the file contains a CA or intermediate certificate, not a private key or unrelated file.
File is too large Use a file smaller than 5 MiB.
Administrator sign-in error Sign in with an administrator account and send the current session cookie.
Connection still fails after upload Check the certificate chain, endpoint host name, network access, proxy configuration, and credentials.