SOAP connector SSL handshake fails when integrating with external web service

BPM Pega Platform
, , , , , , , ,
1

We’re getting SSLHandshakeException when our SOAP connector tries to connect to a partner’s web service. The service uses a self-signed certificate that we’ve obtained, but the handshake still fails.


javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed
at com.pega.integration.soap.SOAPConnector.invoke

We need to configure the truststore properly to accept this certificate, but we’re unsure about the correct approach in Pega 8.7. The certificate is in .cer format. Should we import it into the JVM truststore or is there a Pega-specific configuration? This is blocking critical data synchronization with our partner system.

2

That’s your problem - you need the entire certificate chain, not just the end entity certificate. Request the complete chain from your partner, including their internal CA certificate and any intermediate certificates. Import all of them in order: root CA first, then intermediates, then the service certificate. The PKIX path building error specifically indicates a broken trust chain. Without the CA certificate in your truststore, Pega can’t validate the service certificate’s authenticity.

3

I converted the certificate to PEM format and imported it via Certificate Management. After restarting the nodes, I’m still getting the same SSLHandshakeException. Could there be an issue with certificate chain validation? The partner mentioned their certificate is signed by an internal CA.

4

Your SSLHandshakeException stems from incomplete certificate chain configuration. Self-signed and internal CA certificates require careful handling in Pega’s truststore infrastructure. Here’s the complete resolution approach covering SSL certificate management, truststore configuration, and SOAP connector troubleshooting.

SSL Certificate Management - Complete Chain: The PKIX path building error indicates Pega cannot establish a trust path to the root CA. You need the complete certificate chain:

  1. Request from your partner:

    • Root CA certificate
    • Any intermediate CA certificates
    • The service endpoint certificate

  2. Verify chain completeness using OpenSSL:


openssl s_client -connect partner.service.com:443 -showcerts

This displays the entire chain - save each certificate block separately.

  1. Convert certificates to PEM format if needed:

openssl x509 -inform der -in certificate.cer -out certificate.pem

Truststore Configuration in Pega 8.7: Pega 8.7 uses a dedicated truststore separate from the JVM default. Import certificates through Certificate Management:

  1. Navigate to Records > Security > Certificate Management

  2. Click Import and select certificate type: “Trusted Certificate”

  3. Import in this specific order:

    • Root CA certificate first
    • Intermediate CA certificates (if any)
    • Service endpoint certificate last

  4. For each import:

    • Provide a descriptive name (e.g., “PartnerRootCA”, “PartnerService”)
    • Verify the certificate details display correctly
    • Check “Trust for SSL Server” option

  5. After importing all certificates, restart all application nodes

SOAP Connector Configuration: Update your SOAP connector to properly utilize the truststore:

  1. Open the SOAP connector rule

  2. Navigate to the Security tab

  3. Configure SSL/TLS settings:

    • Protocol: TLS 1.2 (or verify partner’s supported version)
    • Enable hostname verification
    • Truststore: Use default (Pega’s managed truststore)

  4. In the Advanced tab:

    • Set connection timeout: 30000 ms
    • Set read timeout: 60000 ms
    • Enable detailed logging for troubleshooting

SOAP Connector Troubleshooting Steps:

  1. Verify certificate installation:

    • Go to Certificate Management landing page
    • Confirm all imported certificates show “Valid” status
    • Check expiration dates

  2. Test connectivity using the connector’s test facility:

    • Open your SOAP connector rule
    • Click Actions > Test Connectivity
    • Review detailed error messages if it fails

  3. Enable SSL debug logging temporarily: Add JVM argument: `-Djavax.net.debug=ssl:handshake Restart nodes and review logs for handshake details

  4. Verify hostname matching: Ensure the certificate’s CN or SAN matches your service URL exactly

    If there’s a mismatch, you may need to disable hostname verification (not recommended for production)

Common Issues and Solutions:

  • Certificate not found after import: Verify you restarted all nodes, including background processing nodes
  • Chain validation still fails: Check certificate validity dates and ensure none are expired
  • TLS version mismatch: Add -Dhttps.protocols=TLSv1.2 to JVM arguments if partner requires specific TLS version
  • Cipher suite incompatibility: Enable additional cipher suites in java.security file if needed

Validation: After configuration, validate the setup:

  1. Test the SOAP connector from Dev Studio
  2. Monitor prlog for SSL-related errors
  3. Use Tracer to capture the connector execution and verify successful handshake
  4. Test with actual business data to confirm end-to-end functionality

For production deployment, document the certificate chain and renewal procedures. Self-signed certificates typically have shorter validity periods, so establish a process for certificate updates before expiration.

If issues persist after following these steps, verify the partner’s service is accessible and their certificate hasn’t been revoked. Use external tools like SSL Labs or OpenSSL to validate the partner’s SSL configuration independently.

5

Also verify your Java security settings aren’t blocking the connection. Check the java.security file for any restrictions on TLS versions or cipher suites that might conflict with what the partner’s service supports. Sometimes older services use TLS 1.1 which might be disabled by default in newer Java versions.