Fixing GoldenGate Microservices AdminClient SSL/TLS Connection Errors

Step-by-Step Troubleshooting Guide for OGG 21c/23ai Deployments

Oracle GoldenGate Microservices Architecture (OGG MA) uses HTTPS for all communication between AdminClient, Service Manager, and deployments. When TLS is not properly configured on the client, SSL handshake failures occur during connection.

This article explains the issue, shows the full output, and provides the steps required to fix it.

1. AdminClient SSL Error During Connection

When connecting to a deployment using AdminClient, the following command is executed:

Instead of connecting, AdminClient returns SSL handshake errors similar to the following:

OGG (not connected) 1> connect https://<host>:<port>/ deployment <deployment_name> as oggadmin password xxxxxxx

Error: Network error - SSL connection unexpectedly closed

2025-11-18T07:58:46Z  ERROR   OGG-12982  Failed to establish secure communication with a remote peer.  The TLS handshake processing and negotiation was unsuccessful.
2025-11-18T07:58:46Z  ERROR   OGG-12983  Invalid certificate details:
Client Leaf Local certificate unavailable for reporting.
Client Trustpoint Local certificate unavailable for reporting.
Client Peer certificate unavailable for reporting.
2025-11-18T07:58:46Z  ERROR   OGG-12984  The remote peer submitted a certificate that failed validation.
2025-11-18T07:58:46Z  ERROR   OGG-12990  Unable to acquire the certificate-chain certificate from the remote peer. The remote peer's security context does not contain a certificate-chain certificate.
2025-11-18T07:58:46Z  ERROR   OGG-12979  A certificate or certificate-chain member may have expired or references an invalid issuer.
2025-11-18T07:58:46Z  ERROR   OGG-12900  NZ-Toolkit error 28791 - Failed to verify a certificate.

OGG (not connected) 2> exit

2. Root Cause

This problem occurs because AdminClient cannot validate the HTTPS certificate presented by the GoldenGate Service Manager or deployment. Common reasons include:

1. The client does not have the correct CA certificate.
2. Only the leaf certificate was exported instead of the full certificate chain.
3. Certificate CN or SAN does not match the hostname used in the URL.
4. Certificate is expired or incorrectly issued.
5. A self-signed certificate is being used without being trusted locally.

3. Exporting the Certificate from the GoldenGate Wallet

On the GoldenGate server, export the certificate used by Service Manager:

./orapki wallet export -wallet <SERVICE_MANAGER_WALLET_PATH> \
   -dn "<Certificate_DN>" \
   -cert <export_path>/cert.pem \
   -pwd <wallet_password>

Oracle PKI Tool Release 19.0.0.0.0 - Production
Version 19.4.0.0.0
Operation is successfully completed.

The exported file (cert.pem) must be available on the AdminClient machine.

4. Configuring AdminClient with the Trusted Certificate

Before launching AdminClient, set the required environment variables:

export OGG_CLIENT_TLS_CAPATH=<path_to>/cert.pem
export OGG_HOME=<ogg_home_path>
export PATH=$OGG_HOME/bin:$PATH
/path/to/ogg/bin/adminclient
OGG (not connected) 1> connect https://<host>:<port>/ deployment <deployment_name> as oggadmin password xxxxxxx

OGG (https://<host>:<port>/ <deployment_name>) 2>

Successful connection indicates the TLS handshake has been validated.

Summary

To resolve:

GoldenGate AdminClient secure connectivity depends on validating the HTTPS certificate from the Service Manager. If AdminClient lacks the proper trusted certificate, SSL handshake errors occur.

1. Export the correct certificate from the GoldenGate wallet.
2. Configure AdminClient with OGG_CLIENT_TLS_CAPATH.
3. Ensure certificate CN/SAN matches the URL.
4. Reconnect using AdminClient to verify successful TLS handshake.

This ensures secure, trusted communication between AdminClient and GoldenGate Microservices components.