Itential Automation GatewayDeploy and manageConfigure

Create certificates

IAG requires certificates for secure communication between components and with Gateway Manager.

Certificate types and communication scenarios

IAG uses certificates for different communication scenarios, each requiring mutual TLS authentication:

  1. Gateway Manager certificates: Mutual TLS between IAG and Gateway Manager for secure platform connectivity
  2. Client-server certificates: Mutual TLS between gateway clients and servers for secure resource management
  3. Server-runner certificates: Mutual TLS between gateway servers and runner nodes for distributed execution

For more information, see Choose a deployment architecture.

Mutual TLS requirements

For mutual TLS (mTLS) to function properly, each node requires:

  • Certificate Authority (CA) certificate file: Used to verify the authenticity of certificates presented by other nodes
  • Public key certificate: Signed by the CA to prove the node’s identity
  • Private key: Used to decrypt communications and prove ownership of the public certificate

You can share the CA file among all nodes within the cluster or use multiple CA files signed by the same authority.

Self-signed certificate generation

The RPM/DEB installer automatically generates self-signed certificates for Gateway Manager and client-server communication. You can use these default certificates or provide your own.

Gateway Manager certificates

Create certificates for secure communication between your gateway cluster and Gateway Manager. Gateway Manager supports self-signed certificates, CA-issued certificates, and CA-issued wildcard certificates.

To generate a self-signed Gateway Manager certificate, run the following OpenSSL command on the Linux server where you installed your gateway server:

$# Create certificate directory
$mkdir certificates
$
$# Generate Gateway Manager certificate (OpenSSL 3.0+)
$openssl req -x509 -newkey rsa:4096 \
>  -keyout ./certificates/gw-manager-key.pem \
>  -out ./certificates/gw-manager.pem \
>  -days 1825 -nodes \
>  -subj "/CN=$(hostname)" \
>  -addext "basicConstraints=CA:FALSE" \
>  -addext "keyUsage=digitalSignature,keyEncipherment" \
>  -addext "extendedKeyUsage=serverAuth"
$# Create configuration file
$cat > my-ssl-conf <<-EOF
$[req]
$distinguished_name = req_distinguished_name
$x509_extensions = custom_ext
$[req_distinguished_name]
$[custom_ext]
$basicConstraints = CA:FALSE
$keyUsage = digitalSignature,keyEncipherment
$extendedKeyUsage = serverAuth
$EOF
$
$# Generate certificate
$openssl req -x509 -newkey rsa:2048 \
>  -keyout ./certificates/gw-manager-key.pem \
>  -out ./certificates/gw-manager.pem \
>  -days 1825 -nodes \
>  -subj "/CN=$(hostname)" \
>  -config my-ssl-conf

You can also provide your own certificates. For example, you might obtain certificates from a trusted certificate authority for production environments. To use your own Gateway Manager certificates, specify the certificate file and private key file with the following configuration variables:

  • GATEWAY_CONNECT_CERTIFICATE_FILE: Default location is /etc/gateway/certificates/gw-manager.pem
  • GATEWAY_CONNECT_PRIVATE_KEY_FILE: Default location is /etc/gateway/certificates/gw-manager-key.pem

For more information, see Connect variables.

Upload certificates to Gateway Manager

After creating your Gateway Manager certificate, you must upload it to Gateway Manager so Itential Platform can recognize and trust it. This trust relationship enables your gateway to establish a secure connection with Platform.

  1. Open Itential Platform in your browser.
  2. Navigate to the Gateway Manager app.
  3. Navigate to the Certificates tab.
  4. Click Upload Certificate.
  5. Upload your certificate.
  6. Click Add Certificate.

Gateway Manager validates your certificate during upload:

  • Valid: The certificate details display and you can accept the certificate by selecting Add Certificate.
  • Invalid: The certificate details cannot display and the uploaded certificate is marked as Invalid. A certificate might be marked as invalid if it is expired or self-signed. You can still choose to accept and trust an invalid certificate.
  • Malformed: The certificate is rejected because it is likely malformed. For example, Gateway Manager might flag your certificate as malformed if the Subject Alternative Name (SAN) in the certificate does not match the host it represents.

For information on viewing, downloading, and deleting certificates, see Manage certificates.

Client-Server TLS certificates for mutual authentication

For communication within your gateway cluster, generate certificates for each node type in your architecture:

$# Generate CA certificate (shared across all nodes for mutual trust)
$iagctl cert-gen ca --output ./certificates
$
$# Generate server certificate
$iagctl cert-gen server \
>  --output ./certificates \
>  --cn server.example.com \
>  --name server1 \
>  --sans "localhost,127.0.0.1"
$
$# Generate client certificate
$iagctl cert-gen client \
>  --output ./certificates \
>  --cn client@example.com \
>  --name client1
$
$# Generate runner certificates (for distributed execution)
$iagctl cert-gen runner \
>  --output ./certificates \
>  --cn runner1.example.com \
>  --name runner1 \
>  --sans "172.30.0.3"

Configure certificate environment variables

After generating your certificates, configure the environment variables to point each node to its certificate files.

For more information, see Configuration variables.

CA certificate (all application modes)

Set the CA file location for all application modes (client, server, and runner):

  • GATEWAY_APPLICATION_CA_CERTIFICATE_FILE

Client

  • GATEWAY_CLIENT_CERTIFICATE_FILE
  • GATEWAY_CLIENT_PRIVATE_KEY_FILE

Server

  • GATEWAY_SERVER_CERTIFICATE_FILE
  • GATEWAY_SERVER_PRIVATE_KEY_FILE

Runner

  • GATEWAY_RUNNER_CERTIFICATE_FILE
  • GATEWAY_RUNNER_PRIVATE_KEY_FILE

Disable TLS

Disabling TLS can be helpful when you first configure your cluster architecture to verify that everything works before placing certificates on your gateway nodes. Use the following configuration variables to disable TLS depending on the application mode:

  • GATEWAY_CLIENT_USE_TLS=false
  • GATEWAY_SERVER_USE_TLS=false
  • GATEWAY_RUNNER_USE_TLS=false

Itential strongly recommends enabling TLS in production environments.

Production certificate considerations

For production environments implementing mutual TLS, consider:

  1. Certificate Authority (CA) Certificates: Obtain certificates from a trusted CA for enhanced security
  2. Certificate Management: Implement certificate rotation and renewal processes
  3. Security Policies: Follow organizational security requirements for certificate generation
  4. Certificate Storage: Secure certificate storage and access controls
  5. Certificate Validation: Ensure proper certificate chain validation for mutual authentication

Troubleshoot TLS connections

If you experience issues while setting up your TLS certificates, you can enable additional gRPC logs to help identify and troubleshoot problems:

GRPC_GO_LOG_SEVERITY_LEVEL=info
GRPC_GO_LOG_VERBOSITY_LEVEL=99

These environment variables provide additional information about the connections being formed between nodes.