Troubleshoot SSL Issues

SSL Exception Cases

Review the following types of SSL errors, and their symptoms, likely causes, and resolutions.

SSLHandshakeException: PKIX path building failed

Common full pattern:

javax.net.ssl.SSLHandshakeException
sun.security.provider.certpath.SunCertPathBuilderException:
unable to find valid certification path to requested target

sun.security.validator.ValidatorException:
PKIX path building failed

Field	Details
What is the error	Oracle Integration cannot validate the server certificate chain. A required root or intermediate certificate is missing from the Oracle Integration trust store.
Symptoms	The adapter test connection fails before receiving an application response. Logs show the following: `PKIX path building failed, unable to find valid certification path, or ValidatorException` The browser may show a certificate warning for the endpoint.
Likely causes	The server uses a self-signed certificate, private certificate authority (CA), lesser-known CA, missing intermediate certificate, or new CA not present in the JDK default `cacerts`.
Resolution	Download the server trust chain. Upload the required root/intermediate certificates into Oracle Integration as a Trust certificate. Select Home, then Settings, then Certificates. Retest the connection.

Do not upload the server public certificate as an Identity certificate. This is a trust problem.

Host Name/Subject Alternative Name (SAN) Mismatch

Typical patterns:

No name matching host found
CertificateException: No subject alternative DNS name matching host
HTTPS hostname wrong

Field	Details
What is the error	The certificate is valid cryptographically, but was not issued for the host name or IP address used by the adapter endpoint.
Symptoms	The SSL handshake fails. The logs mention host name verification, SAN, CN, or name mismatch. The `openssl s_client` may show a certificate whose `subjectAltName` does not include the endpoint host.
Likely causes	The endpoint uses an IP, but the certificate only has DNS SAN. The endpoint uses DNS, but the certificate SAN has a different name. The wildcard does not cover the requested host. The certificate only has CN, and no proper SAN.
Resolution	Use the host name present in the certificate SAN or coordinate with the endpoint owner to issue a corrected certificate with the right DNS/IP SAN. For IP endpoints, the IP must be present as an IP SAN.

Check the following:

openssl s_client -connect host:443 -servername host -showcerts 
openssl x509 -in server.crt -text -noout

Look for:

X509v3 Subject Alternative Name
DNS expected-host
IP Address:expected-ip

Example: Generation of a certificate with the keytool specifying SAN (used mostly for self-signed certificates):

keytool -genkey -alias myAlias -keyalg RSA -keystore myKeyStore -keyalg RSA -validity 9999 -dname "CN=FQDN/IP, O=oic, L=RWS, S=CA, C=US, OU=oracle usa" -ext "san=DNS1:test,DNS2:localhost,IP:127.0.0.1"

Expired Or Not-Yet-Valid Certificate

Typical patterns:

CertificateExpiredException
CertificateNotYetValidException
NotAfter
NotBefore

Field	Details
What is the error	The certificate validity window does not include the current time.
Symptoms	The adapter test fails with a certificate validity exception. The `openssl x509 -text` command shows an expired `Not After` or a future `Not Before`.
Likely causes	The server certificate expired, the renewed certificate was not deployed, a system clock issue occurred, or a new certificate was activated too early.
Resolution	You must renew/redeploy the server certificate. If Oracle Integration uses an uploaded trust chain, verify that the renewed chain still links to the trusted root/intermediate certificates.

Command to run:

openssl x509 -in certificate -noout -dates

Weak or Unsupported Certificate Algorithms

Typical patterns:

Algorithm constraints check failed
Unsupported signature scheme
No available authentication scheme
key algorithm does not match

Field	Details
What is the error	Certificate algorithm, key length, signature algorithm, or TLS/cipher negotiation is incompatible with the Java/Oracle Integration SSL stack or endpoint requirements.
Symptoms	The SSL debug logs show unsupported schemes such as DSA variants, `No available authentication scheme`, `No X.509 cert selected`, or `Ignore alias certificate: key algorithm does not match`.
Likely causes	Old/weak certificate MD5/SHA1 signature Small RSA key DSA certificate EC/RSA mismatch The server requires a certificate algorithm not available in the uploaded identity keystore
Resolution	Use a certificate with supported modern algorithms. Preferably, RSA 2048+ or the algorithm explicitly required by the server. You must recreate the identity keystore with the correct key algorithm and import the full chain.

TLS Version Mismatch

Typical patterns:

protocol_version
handshake_failure
No appropriate protocol
Received fatal alert: protocol_version

Field	Details
What is the error	The client and server cannot agree on a TLS protocol version.
Symptoms	The handshake fails before certificate validation completes. The endpoint works only with old TLS versions or rejects the version that Oracle Integration uses.
Likely causes	The server only supports TLS 1.0/1.1 or the server has disabled TLS 1.2+.
Resolution	Ensure that both Oracle Integration and the endpoint support TLS 1.2 or above. Enable TLS 1.2+.

HTTP 401/403 For Identity Certificates

This category usually means TLS completed, but the server rejected the client identity or authorization.

Field	Details
What is the error	The endpoint requires client certificate authentication or certificate-based authorization, and the identity certificate sent by Oracle Integration is missing, not trusted, expired, unauthorized, or mapped incorrectly.
Symptoms	The adapter connection reaches the server and receives an HTTP `401 Unauthorized` or `403 Forbidden` error. The SSL handshake may appear successful. The browser/curl command with the correct client certificate may work, while Oracle Integration fails.
Likely causes	The wrong identity certificate alias was selected in the adapter connection. The identity certificate was uploaded under the wrong category. The server does not trust the client certificate issuer. The client public certificate was not registered on the server. The certificate DN/fingerprint is not mapped to an authorized user/application. The keystore contains only public certificate entries, and not a private key.
Resolution	Verify the Oracle Integration certificate is uploaded as Identity. Confirm the adapter two-way SSL is enabled and the selected alias matches the uploaded identity alias. Confirm the JKS contains a `PrivateKeyEntry`. Provide the exported public client certificate to the endpoint owner and ask them to trust/map it. Confirm the root/intermediate chain is accepted by the server.

Support checks:

keytool -list -v -keystore identityKeystore.jks

Look for:

Entry type: PrivateKeyEntry

If it says trustedCertEntry, it is not a valid mTLS identity keystore.

Test outside Oracle Integration:

curl -v --cacert rootCA.crt --key client.key --cert client.crt https://host/path

If the curl command succeeds with the same certificate, but Oracle Integration receives a 401/403 error, check the Oracle Integration alias/category/passwords and whether the endpoint is authorizing the exact certificate that Oracle Integration sends.

HTTP 500 For Identity Certificate Mismatch

Field	Details
What is the error	The server or upstream application encountered an internal error while processing the presented client certificate, typically because the certificate does not match what the server expects.
Symptoms	Oracle Integration receives an HTTP `500` message after SSL/mTLS negotiation. The SSL debug may show Oracle Integration sent a certificate, but the application still fails. Server-side logs may show a client DN mismatch, issuer mismatch, fingerprint mismatch, subject mismatch, missing certificate mapping, or certificate chain validation error.
Likely causes	The wrong identity alias was selected. The certificate subject/issuer/fingerprint does not match server configuration. The server expects a different public certificate than the one in Oracle Integration. The certificate was renewed in Oracle Integration, but not updated on the server allowlist. The private key and certificate chain do not correspond. There was an intermediate/root chain mismatch.
Resolution	Compare the certificate actually uploaded/selected in Oracle Integration with the certificate registered on the server. Match the SHA-1/SHA-256 fingerprint, subject DN, issuer DN, serial number, and validity. Re-upload the correct JKS as Identity, select the correct alias on the connection, and ask the endpoint owner to update the allowlist/mapping if the certificate changed.

Useful fingerprint commands:

openssl x509 -in client.crt -noout -fingerprint -sha1
openssl x509 -in client.crt -noout -fingerprint -sha256
keytool -list -v -keystore identityKeystore.jks -alias alias

Check whether the identity keystore was built correctly:

keytool -list -v -keystore identityKeystore.jks

Expected output:

Alias name: alias-used-in-OIC
Entry type: PrivateKeyEntry
Certificate chain length: leaf + intermediate/root

Decision Matrix

Observed Issue	Most Likely Area	Action
`PKIX path building failed`	Trust certificate	Upload server root/intermediate certificates as Trust in Oracle Integration.
Host name/SAN error	Server certificate	Use the correct host name or ask the server owner to reissue the certificate with the correct SAN.
Expired/not valid	Server or client certificate validity	Renew/redeploy the certificate.
No `available authentication scheme`	Identity certificate algorithm/private key	Recreate the identity certificate/keystore with a compatible key and `PrivateKeyEntry`.
HTTP `401`	Client certificate is missing or unauthenticated	Verify the mTLS alias, identity category, private key, and server trust.
HTTP `403`	Client certificate is authenticated, but unauthorized	Ask the endpoint owner to authorize/map the certificate subject/fingerprint.
HTTP `500` after mTLS	Server-side certificate mismatch	Compare the Oracle Integration certificate with the server expected certificate and update the mapping/allowlist.

Escalation Checklist

Before contacting Oracle Integration support, collect the following:

Full Oracle Integration connection test error.
HTTP response code and response body, if available.
SSL debug snippet around CertificateRequest, certificate selection, and failure.

The output of the following command:

openssl s_client -connect host:443 -servername host -showcerts

For mTLS, the sanitized output of the following:
```
keytool -list -v -keystore identityKeystore.jks
```
- Confirmation of the Oracle Integration certificate upload category: Trust or Identity.
- The alias selected in the adapter connection.
- Whether the browser/curl test with the same client certificate succeeds.

SSL Certification Troubleshooting Issues

Go to the Settings > Certificates tab and upload the server certificate.
For exception errors that occur when configuring a connection with OAuth Client Credentials or OAuth Resource Owner Password Credentials:

Carefully review the OAuth documentation and use the Custom Two-Legged security policy.
For exception errors that occur when configuring a connection with OAuth Authorization:

Carefully review the OAuth documentation and use the Custom Three-Legged Security Policy.