Skip to main content

gRPC Certificate Management

In order to use TLS encryption for gRPC or the Mango web server, you need a PKI (Public Key Infrastructure) to issue X.509 certificates. This guide describes how to use Smallstep step-ca as a Certificate Authority (CA) for Mango, enabling secure gRPC communication between cloud and edge Mango instances.

Prerequisites​

  • Mango 5.0 installed on both cloud and edge instances.
  • step-ca server installed somewhere accessible from both the cloud and edge Mango instances. This guide assumes step-ca was installed in Docker via the manual installation steps.
  • step-cli client installed on all Mango instances (cloud and edge).

Initialization of step-ca​

Run the init command with remote management enabled and answer the prompts, or initialize and run directly via Docker:

docker run -it -v step:/home/step \
    -p 9000:9000 \
    -e "DOCKER_STEPCA_INIT_NAME=Example Test CA" \
    -e "DOCKER_STEPCA_INIT_DNS_NAMES=localhost,$(hostname -f)" \
    -e "DOCKER_STEPCA_INIT_REMOTE_MANAGEMENT=true" \
    smallstep/step-ca

Note the root fingerprint and store the password in a secure location (such as a password manager). Start the step-ca server:

step-ca $(step path)/config/ca.json
# Or for Docker:
docker start <CONTAINER_ID>

Generate and Install Server Certificates​

Run the following commands on the cloud Mango instance.

Bootstrap the step-cli Client​

step ca bootstrap --ca-url ca.example.com:9000 \
    --fingerprint fac319855f4aa55c54ffca94e8d0cd27424af4b3b382a1dc6537df5953f20e68

Generate a Server Certificate​

Change to your Mango data directory and generate a certificate for your server's hostname:

cd /opt/mango-data
step ca certificate localhost server.crt server.key --kty RSA --size 4096

Enter your CA password when prompted. If you use the default key type of EC/P-256 instead of RSA, convert the key to PKCS #8 format:

step crypto key format server.key --out server.key --pkcs8 --pem --insecure --no-password

Download the Root Certificate​

step ca root root_ca.crt

Configure Mango for gRPC​

Edit your mango.properties file to use the certificates for gRPC:

# Enable gRPC server
grpc.server.enabled=true
# gRPC server TCP port
grpc.server.port=9090
# Server X.509 certificate, including full certificate chain
grpc.server.certChain=server.crt
# Server private key
grpc.server.privateKey=server.key
# Root certificates for verification of client certificates (mTLS)
grpc.server.rootCerts=root_ca.crt
# Client authentication options (mTLS): NONE/OPTIONAL/REQUIRE
grpc.server.clientAuth=REQUIRE

Optional: Use the Certificate for HTTPS​

Create a PKCS #12 keystore to also use this certificate as the web server HTTPS certificate:

step certificate p12 server.p12 server.crt server.key

Enter a password when prompted, then edit mango.properties:

ssl.on=true
ssl.port=8443
ssl.keystore.location=server.p12
ssl.keystore.password=mango

Restart Mango for the changes to take effect.

Generate and Install Client Certificates​

Run the following commands on each edge Mango instance.

Bootstrap the step-cli Client​

step ca bootstrap --ca-url ca.example.com:9000 \
    --fingerprint fac319855f4aa55c54ffca94e8d0cd27424af4b3b382a1dc6537df5953f20e68

Generate a Client Certificate​

Change to your Mango data directory and generate a client certificate using a unique identifier as the common name:

cd /opt/mango-data
step ca certificate client-1 client.crt client.key --kty RSA --size 4096

Enter your CA password when prompted. For EC/P-256 keys, convert to PKCS #8:

step crypto key format client.key --out client.key --pkcs8 --pem --insecure --no-password

Download the Root Certificate​

step ca root root_ca.crt

Configure Mango for gRPC Client​

Edit mango.properties on the edge instance:

# Client X.509 certificate, including full certificate chain
grpc.client.certChain=client.crt
# Client private key
grpc.client.privateKey=client.key
# Root certificates for verification of server certificate
grpc.client.rootCerts=root_ca.crt

Restart Mango for the changes to take effect.

Installing the Root Certificate​

If you are using the generated certificate as your web server TLS certificate for HTTPS, you may want to install the root certificate into your operating system so your browser trusts it. This is recommended only for development purposes; production deployments should use certificates from a trusted public CA or deploy the root certificate through enterprise certificate management.

Windows​

  1. Locate your root_ca.crt (or ca.crt) file.
  2. Double-click the file and click "Install certificate".
  3. Choose "Current User".
  4. Select "Place all certificates in the following store" and browse to "Trusted Root Certification Authorities".
  5. Click "Next" then "Finish".
  6. Confirm the security warning by clicking "Yes".

macOS​

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain root_ca.crt

Linux​

Copy the root certificate to the system trust store and update:

# Debian/Ubuntu
sudo cp root_ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

# CentOS/RHEL
sudo cp root_ca.crt /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust

Built-in PKI Service​

Mango 5.0 includes a built-in PKI service that can automatically generate and manage certificates without requiring an external CA like step-ca. When pki.enabled=true is set in mango.properties, Mango creates a local CA and server certificates automatically. The built-in PKI handles:

  • Automatic certificate generation on first start
  • Certificate expiration monitoring via the pki.monitor.checkPeriod property
  • Automatic certificate renewal when pki.monitor.autoRenewEnabled=true
  • Configurable renewal threshold via pki.monitor.expiringSoonThreshold

See the Mango Properties Reference for the full list of PKI properties.

Troubleshooting​

  • TLS handshake failures: Verify that both the server and client certificates were signed by the same CA, and that the root certificate is correctly configured on both sides.
  • Certificate format errors: Ensure certificates are PEM-encoded. DER-encoded certificates must be converted first.
  • Key format issues: gRPC requires PKCS #8 format for private keys. Use the step crypto key format command to convert if needed.
  • Connection refused on port 9090: Verify grpc.server.enabled=true and that the port is not blocked by a firewall.
  • Client authentication failures: When grpc.server.clientAuth=REQUIRE, every connecting client must present a valid certificate signed by a trusted CA.