Mutual TLS certificate validation fails for intercompany transactions

ERP Workday
, , , , , , , ,
1

We’re implementing mutual TLS authentication for intercompany transaction APIs between our parent company Workday tenant (R2 2023) and subsidiary tenants. The mTLS handshake is failing with certificate validation errors when the subsidiary tenant tries to call our Financial Accounting web service.

Error from API gateway logs:


SSL handshake failed: certificate verification error
Unable to get local issuer certificate
Verification code: 20 (unable to verify first certificate)

We’ve configured the client certificate in the subsidiary tenant and uploaded our CA certificate to the truststore, but the intermediate CA certificates in the chain don’t seem to be getting validated properly. The certificate chain ordering and intermediate CA configuration are unclear in the Workday documentation. Our intercompany transactions are completely blocked until we resolve the mTLS validation. Anyone successfully configured mTLS certificate chains for cross-tenant API authentication?

system 2

Here’s the complete solution for your mTLS certificate validation failure:

1. mTLS Certificate Chain Ordering Your error “unable to verify first certificate” indicates an incomplete certificate chain presentation. For mTLS to work between Workday tenants, you must provide the complete certificate chain in the correct order:

Subsidiary Tenant (Client Side): Create a single PEM file with certificates ordered leaf-to-root:


-----BEGIN CERTIFICATE-----
[Client Certificate - issued to subsidiary-api-client]
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
[Intermediate CA - CompanySubCA]
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
[Root CA - CompanyRootCA]
-----END CERTIFICATE-----

Upload this complete chain to: Tenant Setup > Security > Certificates > Client Certificates. Associate it with your Integration System User for the Financial Accounting API client.

2. Intermediate CA Configuration The critical missing piece is the intermediate CA in your parent tenant’s truststore. Workday’s SSL validation requires ALL certificates in the chain to be either presented by the client or present in the server’s truststore.

Parent Tenant (Server Side): Upload intermediate and root CAs separately:

  • Navigate to: Edit Tenant Setup - Security > Certificates > Trusted Root Certificates
  • Upload CompanySubCA (intermediate) as a separate certificate
  • Upload CompanyRootCA (root) as a separate certificate
  • For each certificate, enable “Trust for API Authentication”
  • Set validation mode to “Require Valid Certificate Chain”

3. Certificate Truststore Management Proper truststore configuration requires understanding Workday’s validation hierarchy:


// Validation flow:
1. Client presents certificate chain
2. Workday validates leaf certificate signature against intermediate CA
3. Workday validates intermediate CA signature against root CA
4. Workday checks if intermediate and root are in truststore
5. All validations must pass for authentication success

Common mistakes:

  • Only uploading root CA (missing intermediate causes verification failure)
  • Uploading intermediate but not marking it as trusted for API authentication
  • Certificate chain file has certificates in wrong order (root-to-leaf instead of leaf-to-root)

4. API Gateway SSL Configuration Configure your Financial Accounting web service for mTLS:

Parent Tenant:

  • Go to: View Integration System > [Your Financial Accounting Integration]
  • Edit Integration Security
  • Enable “Require Client Certificate for Authentication”
  • Set Certificate Validation: “Validate Full Certificate Chain”
  • Map certificate subject to Integration System User:
    • Certificate Subject DN: CN=subsidiary-api-client,O=CompanyName
    • Mapped ISU: SUBSIDIARY_API_USER

Subsidiary Tenant:

  • Configure outbound integration to use certificate authentication
  • In Web Service connection properties:
    • Authentication Type: Certificate-Based
    • Client Certificate: [Your uploaded chain]
    • Verify SSL Host: Enabled
    • Trust All Certificates: Disabled (force proper validation)

Verification Steps:

  1. Validate Certificate Chain Locally:

openssl verify -CAfile intermediate_and_root.pem client_cert.pem
# Should return: client_cert.pem: OK
  1. Test Certificate Chain Order:

openssl x509 -in client_chain.pem -noout -subject
# First cert should be client certificate
  1. Test mTLS Handshake:

openssl s_client -connect parent-tenant.workday.com:443 \
  -cert client_chain.pem -key private_key.pem -showcerts
# Should complete handshake without certificate errors

Common Configuration Issues:

  • Certificate expiration: Verify all certificates in chain are valid (not expired, not yet valid)
  • Subject name mismatch: Certificate CN must match configured ISU mapping
  • Key usage restrictions: Client certificate must have “Digital Signature” and “Key Encipherment” key usage
  • Extended key usage: Must include “TLS Web Client Authentication” (OID 1.3.6.1.5.5.7.3.2)

Implementation Checklist:

  1. ✓ Create complete certificate chain file (leaf-to-root order)
  2. ✓ Upload chain to subsidiary tenant Client Certificates
  3. ✓ Upload intermediate CA to parent tenant Trusted Root Certificates
  4. ✓ Upload root CA to parent tenant Trusted Root Certificates
  5. ✓ Mark both CAs as trusted for API authentication
  6. ✓ Enable “Require Client Certificate” on Financial Accounting web service
  7. ✓ Map certificate subject DN to Integration System User
  8. ✓ Configure subsidiary outbound integration for certificate authentication
  9. ✓ Test with OpenSSL before attempting actual API calls
  10. ✓ Monitor SSL handshake logs for validation errors

Expected Outcome: Once properly configured, the subsidiary tenant’s API calls will complete the mTLS handshake successfully. The parent tenant will validate the complete certificate chain (client → intermediate → root), authenticate the client based on certificate subject mapping, and process intercompany Financial Accounting transactions. Your API gateway will show successful SSL handshakes with certificate-based authentication in the security logs.

This draft is based on general Workday knowledge. It has not been verified against your specific version and environment. Practitioners: verify the steps and share your experience below.

3

The “unable to verify first certificate” error typically means your certificate chain is incomplete or incorrectly ordered. When you uploaded the client certificate to the subsidiary tenant, did you include the full certificate chain (client cert + intermediate CA + root CA) in a single PEM file? Workday requires the complete chain in proper order: client certificate first, then intermediate CA(s), then root CA. The truststore on the receiving end (parent tenant) needs to have the intermediate and root CAs configured separately.

4

We uploaded just the client certificate initially. Let me clarify the chain - we have: client cert issued by intermediate CA “CompanySubCA”, which is issued by root CA “CompanyRootCA”. So on the subsidiary tenant (client side), we should upload a PEM file containing all three certificates in that order? And on the parent tenant (server side), we need both the intermediate and root CA in the truststore?

7

Exactly right. Client side needs the full chain in one PEM file, ordered from leaf to root. Server side truststore needs the CAs that will validate incoming certificates. Here’s what often gets missed: Workday’s API gateway validates the entire chain, not just the client certificate. If the intermediate CA isn’t in the truststore, validation fails even if the root CA is present. In Workday, go to Edit Tenant Setup - Security > Certificates and upload your intermediate CA certificate separately from the root CA. Make sure both are marked as trusted for API authentication.

8

I’ve dealt with this exact scenario. One thing to verify: when you export your certificate chain from your CA, ensure you’re getting the intermediate certificates in the correct order if there are multiple intermediates. Some CAs have multi-level hierarchies. Use OpenSSL to verify your chain locally before uploading to Workday:


openssl verify -CAfile root_and_intermediates.pem client_cert.pem
openssl s_client -connect api.workday.com:443 -cert client_chain.pem -key private.key

This will show you if the chain is valid before you even touch Workday configuration.

9

Kim’s verification approach is solid. Also check your API gateway SSL configuration on the parent tenant. In Workday Web Services security settings, there’s an option for “Require Client Certificate” that needs to be enabled for mTLS. And verify that the certificate authentication is configured at the integration level, not just at the tenant level. Each Financial Accounting web service endpoint can have its own certificate requirements.

10

Don’t forget about the certificate subject name validation. Workday validates that the certificate subject matches the configured integration system user or API client. If your client certificate has a subject like “CN=subsidiary-api-client” but your ISU is configured differently, validation will fail even with a perfect certificate chain. Check the certificate subject mapping in your integration security configuration.