DEV Community

Clariza Look
Clariza Look

Posted on • Edited on

Troubleshooting SSL Certificate Chain Issues in Enterprise Integration Platforms: A Real-World Case Study

#programming #devops #websecurity #systemadministration

How to diagnose and fix PKIX certificate path building errors when integrating with external APIs.

The Problem: A Mysterious SSL Error

Picture this: You're working on an integration between your enterprise middleware platform and a third-party API endpoint (api.partner-services.com), and suddenly you're hit with this cryptic error:

The request operation failed. Exception: com.ibm.jsse2.util.h: PKIX path building failed: 

java.security.cert.CertPathBuilderException: 

PKIXCertPathBuilderImpl could not build a valid CertPath.; 
internal cause is: java.security.cert.CertPathValidatorException: 

The certificate issued by 
CN=SSL.com EV Root Certification Authority RSA R2, O=SSL Corporation, L=Houston, ST=Texas, C=US is not trusted
Enter fullscreen mode Exit fullscreen mode

If you've ever encountered this error, you know how frustrating it can be. The integration was working fine, but now it's failing with SSL certificate validation issues. Let's walk through how to diagnose and fix this step-by-step.

Understanding the Error

The error message tells us several key things:

  • PKIX path building failed: The system can't build a complete certificate chain
  • Certificate not trusted: A specific SSL.com certificate isn't being trusted
  • Root cause: Missing or incomplete certificate chain in the trust store

Step 1: Identify the Failing Endpoint

First, we need to identify exactly which endpoint is causing the SSL error. This information can usually be found in:

  • Platform logs or activity monitor
  • Integration flow configuration
  • HTTP connector settings
  • Error details in the runtime logs

In our case, the failing endpoint was: api.partner-services.com:443/oauth/token

Step 2: Analyze the Certificate Chain

This is the crucial step that most troubleshooting guides skip. We need to see the actual certificate chain that the server is presenting. Use OpenSSL to inspect the complete chain:

openssl s_client -showcerts -connect api.partner-services.com:443
Enter fullscreen mode Exit fullscreen mode

What the Output Reveals

The OpenSSL output showed us a 4-level certificate chain:

Certificate chain
 0 s:C=US, ST=California, O=Partner Services Inc, CN=api.partner-services.com
   i:C=US, O=SSL Corporation, CN=Entrust OV TLS Issuing RSA CA 1

 1 s:C=US, O=SSL Corporation, CN=Entrust OV TLS Issuing RSA CA 1
   i:C=US, O=SSL Corporation, CN=SSL.com TLS RSA Root CA 2022

 2 s:C=US, O=SSL Corporation, CN=SSL.com TLS RSA Root CA 2022
   i:C=US, ST=Texas, L=Houston, O=SSL Corporation, CN=SSL.com EV Root Certification Authority RSA R2

 3 s:C=US, ST=Texas, L=Houston, O=SSL Corporation, CN=SSL.com EV Root Certification Authority RSA R2
   i:C=US, ST=Texas, L=Houston, O=SSL Corporation, CN=SSL.com EV Root Certification Authority RSA R2
Enter fullscreen mode Exit fullscreen mode

fix PKIX certificate

This revealed the complete trust chain:

  1. End Certificate: api.partner-services.com
  2. Intermediate CA: Entrust OV TLS Issuing RSA CA 1
  3. Intermediate CA: SSL.com TLS RSA Root CA 2022
  4. Root CA: SSL.com EV Root Certification Authority RSA R2

Step 3: Identify Missing Certificates

Comparing what our integration platform had versus what was needed:

  • ✅ SSL.com EV Root Certification Authority RSA R2 (already imported)
  • ❌ SSL.com TLS RSA Root CA 2022 (missing)
  • ❌ Entrust OV TLS Issuing RSA CA 1 (missing)

The issue was clear - we had the root certificate but were missing the two intermediate certificates needed to complete the chain.

Step 4: Locate and Download Missing Certificates

Finding SSL.com Certificates
Navigate to SSL.com's Certificate Repository and locate:

1. SSL.com TLS RSA Root CA 2022

  • File: SSLcom-TLS-Root-2022-RSA.pem
  • SHA1: 72:B2:76:44:BD:09:46:BF:3C:51:0C:00:0F:44:30:16:8F:E2:89:8A

2. Entrust OV TLS Issuing RSA CA 1

  • Serial: 6FE63EDE5FC1C03AFB6D7A85BD3A156D
  • SHA1: CA:AA:C3:E1:6B:D2:42:66:88:7C:C8:56:73:C0:18:F4:6A:13:9B:0F

Download both certificates in PEM format.

Step 5: Import Certificates in Your Integration Platform

Import Process

  1. Navigate to your platform's SSL certificate management section
  2. Select "Import from Clipboard" or similar option
  3. Paste the complete PEM certificate (including BEGIN/END lines)
  4. Set certificate type as "CA Certificate" or "Intermediate Certificate"
  5. Provide descriptive aliases:
    • SSL.com-TLS-Root-2022-RSA
    • Entrust-OV-TLS-Issuing-RSA-CA-1

Troubleshooting Import Issues

If you encounter "Couldn't establish a chain of trust" during import:

  • ✅ Check "Trusted" or "Mark as trusted" during import
  • ✅ Import certificates in order (root to intermediate)
  • ✅ Use "CA Certificate" import option instead of "TrustStore Entry"
  • ✅ Ensure complete PEM format with proper BEGIN/END lines

Step 6: Deploy and Test

After importing both certificates:

  • Deploy the configuration in your integration platform
  • Wait 1-5 minutes for changes to take effect
  • Test the integration that was previously failing
  • Monitor logs for any remaining certificate errors

Understanding Certificate Chains: Why Not Just One Certificate?

You might wonder why we need multiple certificates instead of just one. Here's why certificate chains exist:

Security Benefits

  • Root CA Protection: Root certificates are kept offline and ultra-secure
  • Risk Limitation: If an intermediate is compromised, only that level needs replacement
  • Compartmentalization: Different intermediates serve different purposes

Operational Benefits

  • Scalability: One root can't physically sign millions of certificates
  • Flexibility: Easier to revoke or replace intermediate certificates
  • Specialization: Different validation levels and certificate types

Trust Model

  • Browser Trust: Browsers only trust ~150 pre-installed root CAs
  • Delegation: Root CAs delegate trust to intermediate CAs
  • Chain Validation: Each level vouches for the level below it

Who Is Responsible for Implementing Certificate Chains?

Understanding certificate chain responsibilities helps prevent issues and clarifies troubleshooting ownership:

Certificate Authorities (CAs) Design the Chain

  • SSL.com, DigiCert, Let's Encrypt, etc. design and operate the certificate hierarchy
  • They decide how many intermediate levels to use for security and scalability
  • They create and manage the intermediate CAs
  • They determine the chain structure for operational efficiency

Service Providers Configure the Chain

  • API providers (like api.partner-services.com) configure their web servers to present the complete chain
  • They install the end certificate + all intermediate certificates on their servers
  • They're responsible for ensuring clients can validate the full chain
  • They handle certificate renewals and chain updates

Integration Teams Handle Missing Components

  • Integration developers import any missing intermediate/root certificates into client systems
  • Your middleware platform needs the complete chain to validate connections
  • You troubleshoot and fix incomplete chains in your trust store
  • You monitor for certificate-related integration failures

Infrastructure Teams Maintain Trust Stores

  • IT/Security teams maintain the root certificate trust stores across the organization
  • They ensure enterprise systems have necessary CA certificates pre-installed
  • They handle certificate lifecycle management, renewals, and security policies
  • They establish standards for certificate validation and trust

Shared Responsibility Model
The ideal approach follows a shared responsibility model:

  • Service providers should present complete certificate chains
  • Clients should be prepared to import missing intermediates when needed
  • Both parties should monitor certificate health and expiration dates
  • Organizations should have processes for handling certificate issues

In this Case Study:

  • SSL.com: Designed the 4-level certificate chain architecture
  • Partner Services: Configured their server to present the complete chain
  • Integration Team: Imported the missing intermediate certificates to fix the validation
  • IT Infrastructure: Maintains the overall certificate trust infrastructure

Remember: While service providers should ideally present complete chains, integration teams must be prepared to handle missing intermediate certificates as part of robust API integration practices.

Key Takeaways

  • Certificate chains require ALL certificates from root to intermediate
  • OpenSSL is your best friend for diagnosing certificate chain issues
  • Import intermediate certificates even if you have the root
  • Check certificate repositories of the issuing CA for missing certificates
  • Mark certificates as trusted during import to avoid validation errors

Prevention Tips

  • Regularly audit your certificate trust store
  • Monitor certificate expiration dates and renewal schedules
  • Test integrations in staging environments before production
  • Document certificate dependencies for your integrations
  • Set up monitoring for SSL certificate validation errors

Conclusion

SSL certificate chain issues can be frustrating, but with the right diagnostic approach, they're entirely solvable. The key is understanding that certificate validation requires the complete chain of trust, not just the root certificate.

By using tools like OpenSSL to inspect certificate chains and systematically importing missing intermediate certificates, you can resolve these issues quickly and prevent them from recurring.

Remember: when in doubt, check the complete certificate chain first. It's often the missing piece that solves the puzzle!

Have you encountered similar SSL certificate issues in your integrations? Share your experiences and solutions in the comments below.

Additional Resources

Top comments (0)

Some comments may only be visible to logged-in visitors. Sign in to view all comments.