Encrypting Connections

TigerGraph supports secure data-in-transit communication using the SSL/TLS encryption protocol. This applies to all outward-facing interfaces, including GSQL clients, RESTPP endpoints, and the GraphStudio web interface.

As of TigerGraph 4.3.0, Mutual TLS (mTLS) authentication is also supported. mTLS enhances security by ensuring that both the client and server authenticate each other using certificates.

You can configure either server-only SSL/TLS or mutual authentication (mTLS), depending on your security requirements:

  • Server-only SSL/TLS: Only the server presents a certificate, and clients verify the server’s identity.

  • Mutual TLS (mTLS): Both the server and client present certificates, and each is authenticated.

Prerequisites

Before you begin, ensure you have a basic understanding of these concepts:

  • What SSL certificates and keys are used for

  • How SSL certificate chains work

  • What a Distinguished Name (DN) and Subject Alternative Name (SAN) are

Learn more: SSL/TLS Strong Encryption: An Introduction

Nginx-Based

TigerGraph uses the Nginx web server, so SSL/TLS configuration relies on Nginx’s built-in HTTPS support.

For additional reference, see the official Nginx documentation: Configuring HTTPS Servers (Nginx).

Step 1: Obtain and Install Certificates

You need certificates for your server (always) and for each client (only for mTLS).

Option A: Use a Certificate from a Trusted Authority

Obtain a certificate from a trusted Certificate Authority (CA). CA vendors provide guidance for requesting and installing certificates.

Configure in TigerGraph:

gadmin config entry ssl

Option B: Create a Self-Signed Certificate

For testing or internal use, you can generate your own certificate:

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout <PRIVATE_KEY_PATH> -out <CERTIFICATE_PATH>

Replace <PRIVATE_KEY_PATH> with the path to your private key and <CERTIFICATE_PATH> with the path to your public certificate.

You will be prompted for certificate fields such as country, locality, organization, and hostname (Common Name).

The self-signed process below uses the root certificate as the HTTPS server certificate. This is suitable for testing—not for production.

The Common Name should be your server’s hostname, since certificates are bound to domain names.

Change Certificate Permissions

Secure your certificate files:

chmod 600 <CERTIFICATE_PATH> <PRIVATE_KEY_PATH>

Step 2: Configure SSL with gadmin

After you have your certificates, enable SSL/TLS in TigerGraph:

gadmin config entry ssl
Nginx.SSL.Enable: true
Nginx.SSL.Key: <PRIVATE_KEY_PATH>
Nginx.SSL.Cert: <CERTIFICATE_PATH>

TigerGraph accepts only PEM-encoded certificates. If needed, convert using SSL Converter.

Apply the configuration:

gadmin config apply -y

Then restart services:

gadmin restart gsql nginx gui -y

Step 3: Set Up Mutual TLS (mTLS)

Mutual TLS (mTLS) adds two-way authentication, where both the client and server verify each other’s identities. To enable mTLS, first complete the server-side SSL/TLS setup (above), then follow these steps.

Required Parameters

Enable client certificate verification (mTLS):

gadmin config set Nginx.SSL.Client.Verify true

Upload or Specify Client CA Certificates

Provide a list of Certificate Authorities (CAs) trusted to authenticate client certificates.

You can do this in one of two ways:

Admin Portal Method: Upload client CA certificates through the Admin Portal. See Admin Portal: Nginx Configuration.

gadmin Method:

gadmin config set Nginx.SSL.Client.Cert <CLIENT_CA_CERT_PATH>

Replace <CLIENT_CA_CERT_PATH> with the full path to your PEM-encoded client CA certificate file, for example: /etc/tigergraph/client_ca_cert.pem.

Optional Parameters

The following parameters are optional and add deeper verification checks on client certificates. Even if you skip them, mTLS will still validate the client certificate’s signature.

DN Attribute Validation

gadmin config set Nginx.SSL.Client.DN.Verify true
gadmin config set Nginx.SSL.Client.DN.Country '["US", "UK"]'
gadmin config set Nginx.SSL.Client.DN.Organization '["MyOrg"]'
gadmin config set Nginx.SSL.Client.DN.CommonName '["client1.example.com"]'

SAN Attribute Validation

gadmin config set Nginx.SSL.Client.SAN.Verify true
gadmin config set Nginx.SSL.Client.SAN.DNS '["clientdomain.com"]'
gadmin config set Nginx.SSL.Client.SAN.Email '["user@email.com"]'
gadmin config set Nginx.SSL.Client.SAN.URI '["spiffe://client/uri"]'
gadmin config set Nginx.SSL.Client.SAN.IP '["192.168.1.1"]'
gadmin config set Nginx.SSL.Client.SAN.RID '["1.2.3.4.5"]'

OCSP (Certificate Revocation) Verification

gadmin config set Nginx.SSL.Client.OCSP.Verify true
gadmin config set Nginx.SSL.Client.OCSP.Resolver "8.8.8.8,8.8.4.4"
gadmin config set Nginx.SSL.Client.OCSP.Responder "http://ocsp.myca.com"

Each of the above parameters provides an extra layer of verification. For basic testing, you can leave them unset and rely only on the client certificate signature.

Testing Your Connection

To test SSL/TLS or mTLS:

Server-only TLS: You only need a CA certificate to verify the server.

curl --cacert <CERTIFICATE_PATH> https://localhost:14240

Mutual TLS (mTLS): You need both server and client certificates.

curl --cert <CLIENT_CERT_PATH> --key <CLIENT_KEY_PATH> --cacert <CLIENT_CA_CERT_PATH> https://localhost:14240

Replace placeholders:

  • <CERTIFICATE_PATH> — server’s public certificate

  • <CLIENT_CERT_PATH> — client’s certificate

  • <CLIENT_KEY_PATH> — client’s private key

  • <CLIENT_CA_CERT_PATH> — client CA certificate (PEM)

If the validation fails, you will receive a 403 Forbidden response.

Troubleshooting

Issue Description Resolution

403 Forbidden

DN or SAN mismatch

Ensure the client certificate attributes match the configured validation rules.

Missing client certificate

Client did not present a certificate

Ensure the client provides a valid certificate and key.

OCSP verification failure

Cannot validate certificate status

Check OCSP configuration or disable temporarily for testing.

Check logs:

  • Nginx logs record HTTP 403 errors.

  • TigerGraph logs provide detailed handshake error information.

Limitations

If you use mTLS, note these limitations in TigerGraph 4.3.0:

  1. Internal clients on the same TigerGraph server node may connect without mTLS.

  2. pyTigerGraph does not support mTLS.

Quick Reference: mTLS Parameters

Parameter

Purpose

Nginx.SSL.Client.Verify

Enable client certificate verification (mTLS)

Nginx.SSL.Client.Cert

Path to trusted CA file for client certificates

Nginx.SSL.Client.DN.*

DN attribute checks (Country, Organization, CommonName)

Nginx.SSL.Client.SAN.*

SAN attribute checks (DNS, Email, URI, IP, RID)

Nginx.SSL.Client.OCSP.Verify

Enable OCSP for real-time revocation checking

Nginx.SSL.Client.OCSP.Resolver

DNS resolvers for OCSP queries

Nginx.SSL.Client.OCSP.Responder

Custom OCSP responder URL

Configuring TLS for Internal Kafka.

This feature introduces SSL/TLS encryption for TigerGraph’s internal Kafka. It addresses the lack of native encryption and authentication for data in transit within the TigerGraph cluster.

Basic Setup Workflow

  1. set certificate-chain in PEM format

    gadmin config set Kafka.Security.SSL.Certificate @/path/to/cert.pem

  2. set private-key in PEM format

    gadmin config set Kafka.Security.SSL.PrivateKey @/path/to/prikey.pem

  3. set passphrase for private key. Java keystore requires passphrase.

    gadmin config set Kafka.Security.SSL.Passphrase @/path/to/passphrase

  4. Enable SSL for Kafka to ensure encrypted communication.

    gadmin config set Kafka.Security.SSL.Enable true

  5. Apply the updated Kafka security configurations to the system.

    gadmin config apply -y

  6. Restart Kafka and the corresponding client services.

    gadmin restart all -y

Configuration Reference

Parameter Description Default Value

Kafka.Security.SSL.Certificate

Kafka broker certificate in PEM format

Kafka.Security.SSL.Enable

Enable Kafka TLS encryption

false

Kafka.Security.SSL.ExternalListener.ClientAuth

Enable SSL client authentication for external listeners, the root certificate of Kafka.Security.SSL.Certificate will be used to trust client certificate.

false

Kafka.Security.SSL.Passphrase

Kafka broker private key passphrase. Should not be empty.

Kafka.Security.SSL.Port

Kafka SSL listening port

30001

Kafka.Security.SSL.PrivateKey

Kafka broker private key in PEM format

Kafka.Security.ClientConf.ProtocolForAllClients

If specified, all clients must use the specified protocol. Legal values include: empty-string (not specified), ssl, plaintext. If it’s not specified, clients can choose a preferred protocol

Kafka.Security.ClientConf.EngineProtocol

It is the protocol for engine-kafka communication. The value can be an empty-string or "plaintext", "ssl". It’s overridden by Kafka.Security.ClientConf.ProtocolForAllClients.

Kafka.Security.ClientConf.InfraProtocol

It is the protocol for infra-kafka communication. The value can be an empty-string or "plaintext", "ssl". It’s overridden by Kafka.Security.ClientConf.ProtocolForAllClients.

Kafka.Security.ClientConf.InterBrokerProtocol

It is the protocol for inter-broker communication. The value can be an empty-string or "plaintext", "ssl". It’s overridden by Kafka.Security.ClientConf.ProtocolForAllClients.

TLS Versions and Cipher Suites

TigerGraph’s Nginx supports TLS 1.2 and TLS 1.3. By default, TLS 1.3 is used for both client-facing and internal cluster communication, offering stronger security and faster connection establishment.

TLS 1.2 Cipher Suites (configured in template)

  • ECDHE-ECDSA-AES128-GCM-SHA256

  • ECDHE-RSA-AES128-GCM-SHA256

  • ECDHE-ECDSA-AES256-GCM-SHA384

  • ECDHE-RSA-AES256-GCM-SHA384

  • ECDHE-ECDSA-CHACHA20-POLY1305

  • ECDHE-RSA-CHACHA20-POLY1305

TLS 1.3 Cipher Suites

TLS 1.3 cipher suites are not explicitly configured and use OpenSSL’s built-in defaults:

  • TLS_AES_256_GCM_SHA384

  • TLS_CHACHA20_POLY1305_SHA256

  • TLS_AES_128_GCM_SHA256

Customizing TLS Versions and Cipher Suites

TLS versions and cipher suites can be customized by modifying the Nginx.ConfigTemplate. These settings control which protocols and encryption standards are used for secure communication.

Changes apply to both client-facing and internal cluster communication and should be handled carefully to avoid unintended access or compatibility issues.

Common customization options include:

  • Disable TLS 1.2

    If modern protocols are required, TLS 1.2 can be disabled by updating the ssl_protocols directive to allow only TLS 1.3.

    Current configuration
    ssl_protocols TLSv1.2 TLSv1.3;
    Updated configuration
    ssl_protocols TLSv1.3;

  • Restrict TLS 1.2 cipher suites

    TLS 1.2 connections can be limited to a specific set of cipher suites by modifying the ssl_ciphers directive. This helps ensure that only approved and secure ciphers are used.

    ssl_ciphers ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256;

  • Restrict TLS 1.3 cipher suites

    TLS 1.3 cipher suites are not explicitly configured by default. They can be defined by adding an ssl_conf_command directive. This allows control over which cipher suites are negotiated for TLS 1.3 connections.

    ssl_conf_command Ciphersuites TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256;

Steps to Apply Changes

# 1. Export the current Nginx configuration template
gadmin config get Nginx.ConfigTemplate > nginx_conf_new

# 2. Edit the file:
#    - Locate the ssl_protocols directive to customize TLS versions
#    - Modify ssl_ciphers to restrict TLS 1.2 cipher suites
#    - Add ssl_conf_command to customize TLS 1.3 cipher suites

# 3. Apply the updated configuration
gadmin config set Nginx.ConfigTemplate @nginx_conf_new
gadmin config apply -y && gadmin restart NGINX -y

Cipher suite selection is fully customizable, the configurations defined in the Nginx template are applied exactly as specified.

Changes to Nginx.ConfigTemplate do not persist across upgrades. The template is backed up and reset during the upgrade process to incorporate version-specific changes. You must manually reapply your modifications to the new template version and resolve any conflicts as needed.

Verifying Active Cipher Suites

Use openssl s_client to verify the negotiated TLS version and cipher suites at runtime. For this purpose, openssl serves as the recommended external tool.

Example
openssl s_client -connect <host>:<port> -tls1_3