Configure TLS & client certificates

The agent can authenticate to a PostgreSQL source with a client certificate (mutual TLS) instead of a password. The database verifies the agent's certificate, and the agent verifies the server's — no shared secret travels the wire, and no password is stored in the control plane.

1. What you need

• A client certificate and private key for the agent, signed by a CA the database trusts.
• The database's CA certificate (to verify the server).
• PostgreSQL configured to accept certificate authentication for the user (clientcert=verify-full in pg_hba.conf, or Cloud SQL "Require trusted client certificates").

2. Generate a client certificate

If you run your own CA:

# client key + CSR (CN must match the database user you'll log in as)
openssl req -new -nodes -newkey rsa:2048 \
  -keyout client.key -out client.csr -subj "/CN=shaft_agent"

# sign it with your CA
openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
  -out client.crt -days 365

On Cloud SQL, create the client cert from the console or:

gcloud sql ssl client-certs create shaft-agent client.key --instance=YOUR_INSTANCE
gcloud sql ssl client-certs describe shaft-agent --instance=YOUR_INSTANCE \
  --format="value(cert)" > client.crt
gcloud sql instances describe YOUR_INSTANCE \
  --format="value(serverCaCert.cert)" > server-ca.crt

3. Convert the key for the agent

The PostgreSQL JDBC driver the agent uses needs the key in PKCS#8 DER:

openssl pkcs8 -topk8 -inform PEM -outform DER -in client.key -out client.key.pk8 -nocrypt

4. Place the files where the agent runs

Copy client.crt, client.key.pk8, and the CA cert (server-ca.crt) onto the agent host, readable only by the agent user:

sudo install -o shaft -g shaft -m 600 client.crt      /opt/shaft-agent/tls/client.crt
sudo install -o shaft -g shaft -m 600 client.key.pk8  /opt/shaft-agent/tls/client.key
sudo install -o shaft -g shaft -m 600 server-ca.crt   /opt/shaft-agent/tls/ca.crt

5. Configure the connector in the portal

On the connector's Configure page, choose Authentication → Client certificate (mTLS) and set:

| Field | Value | |-------|-------| | Database user | the user the certificate's CN maps to | | Client certificate | /opt/shaft-agent/tls/client.crt (or an env: reference) | | Client key (PKCS#8 DER) | /opt/shaft-agent/tls/client.key | | CA certificate | /opt/shaft-agent/tls/ca.crt |

Paths are resolved on the agent host. You can also store a value as an env: reference (e.g. env:PG_SSLCERT) and provide it to the agent's environment instead — raw material never transits the control plane.

The agent connects with sslmode=verify-full by default, which checks the server certificate against the CA and verifies the hostname. Use a laxer mode only if you understand the trade-off.