> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-gateway/5/create-certificates/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Create certificates

> Create required certificates to support secure communication between Gateway components and with Gateway Manager.

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

## Certificate types and communication scenarios

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

1. **Gateway Manager certificates**: Mutual TLS between Gateway 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](./choose-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:

```bash
# 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"
```

#### For OpenSSL versions before 3.0

```bash
# 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](/itential-gateway/5/gateway-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](/itential-gateway/5/manage-certificates).

### Client-Server TLS certificates for mutual authentication

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

Itential Gateway ships with a convenience tool that can create these certificates for you:

```bash
# 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"
```

Alternatively, use the following `openssl` commands to generate certificates:

```bash
# Generate CA certificate (shared across all nodes for mutual trust)
openssl genrsa -out ca-key.pem 2048

openssl req -new -x509 -key ca-key.pem -out ca.pem -days 365 \
  -subj "/C=US/ST=Georgia/L=Atlanta/O=Automation/OU=Development/CN=my-ca"

# Generate server certificate
openssl genrsa -out server-key.pem 2048

# Generate a Certificate Signing Request (CSR) for the server
openssl req -new -key server-key.pem -out server.csr \
  -subj "/C=US/ST=Georgia/L=Atlanta/O=Automation/OU=Development/CN=my-server"

# Sign the server certificate with the CA
openssl x509 -req -in server.csr -CA ca.pem -CAkey ca-key.pem \
  -CAcreateserial -out server.pem -days 365 \
  -extfile <(printf '[v3]\nbasicConstraints=CA:FALSE\nkeyUsage=digitalSignature,keyEncipherment\nextendedKeyUsage=serverAuth,clientAuth\nsubjectAltName=DNS:my-server,IP:127.0.0.1') \
  -extensions v3

# Generate a client certificate
openssl genrsa -out client-key.pem 2048

# Generate a Certificate Signing Request (CSR) for the client
openssl req -new -key client-key.pem -out client.csr \
  -subj "/C=US/ST=Georgia/L=Atlanta/O=Automation/OU=Development/CN=my-client"

# Sign the client certificate with the CA
openssl x509 -req -in client.csr -CA ca.pem -CAkey ca-key.pem \
  -CAcreateserial -out client.pem -days 365 \
  -extfile <(printf '[v3]\nbasicConstraints=CA:FALSE\nkeyUsage=digitalSignature,keyEncipherment\nextendedKeyUsage=serverAuth,clientAuth') \
  -extensions v3

# Generate a runner certificate
openssl genrsa -out runner-key.pem 2048

# Generate a Certificate Signing Request (CSR) for the runner
openssl req -new -key runner-key.pem -out runner.csr \
  -subj "/C=US/ST=Georgia/L=Atlanta/O=Automation/OU=Development/CN=my-runner"

# Sign the runner certificate with the CA
openssl x509 -req -in runner.csr -CA ca.pem -CAkey ca-key.pem \
  -CAcreateserial -out runner.pem -days 365 \
  -extfile <(printf '[v3]\nbasicConstraints=CA:FALSE\nkeyUsage=digitalSignature,keyEncipherment\nextendedKeyUsage=serverAuth,clientAuth\nsubjectAltName=DNS:my-runner,IP:127.0.0.1') \
  -extensions v3
```

* All certificate types (server, client, and runner) use the same key usages: `digitalSignature` and `keyEncipherment` for `keyUsage`, and `serverAuth` and `clientAuth` for `extendedKeyUsage`.
* The `--sans` flag in `iagctl cert-gen` corresponds to the `subjectAltName` extension in the commands above. Subject alternative names are required for server and runner certificates.
* To use ECDSA instead of RSA, replace `genrsa 2048` with `ecparam -name prime256v1 -genkey -noout` and remove `keyEncipherment` from `keyUsage` (ECDSA does not support key encipherment).

## 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](/itential-gateway/5/configuration-variables-overview).

### 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 the following:

* **Certificate authority**: Obtain certificates from a trusted CA for enhanced security.
* **Certificate management**: Implement certificate rotation and renewal processes.
* **Security policies**: Follow your organization's requirements for certificate generation.
* **Certificate storage**: Use secure storage and restrict access to certificate files.
* **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.

> Create required certificates to support secure communication between Gateway components and with Gateway Manager.