When an application stops working after SSL decryption is enabled, the useful question is not simply “should we bypass it?” It is: which connection leg failed, which certificate did the client receive, and what evidence distinguishes a trust problem from certificate pinning? This guide provides a troubleshooting matrix, a controlled comparison workflow and an exception-review worksheet for Palo Alto Networks SSL Forward Proxy deployments.
Scope: outbound SSL Forward Proxy, not inbound inspection or a GlobalProtect portal certificate. The worksheets and hypothetical example are original operational recommendations, not a report of executed firewall tests. Confirm menus, log availability and supported settings against your PAN-OS release and management platform before using them.
The problem: a certificate error is a clue, not a diagnosis
SSL Forward Proxy creates separate client-to-firewall and firewall-to-server sessions; the firewall presents an impersonation certificate to the client rather than the original server certificate.[1] Treat those legs as separate trust investigations rather than assuming a successful connection from another machine proves the firewall should accept the same destination.
Palo Alto identifies UnknownCA and BadCertificate as common indicators when investigating pinned certificates.[1] Do not turn either string into an automatic pinning verdict. As a diagnostic recommendation, first check the issuer presented to the failing client, the relevant trust store, the matched policy and whether other managed clients reproduce the failure. A label such as “certificate error” is not enough evidence to approve a permanent exception.
Palo Alto's broader troubleshooting guidance also identifies incomplete certificate chains, unsupported cipher suites, weak protocols and revoked certificates as failure categories.[3] Your first durable asset is a matrix that keeps those hypotheses separate.
SSL decryption troubleshooting matrix
The following is a proposed investigation order, not a vendor guarantee that a symptom has only one cause. Record actual evidence in a copy of the table.
| Observed symptom | Hypothesis to investigate | Evidence to collect before changing policy | Preferred next step |
|---|---|---|---|
| Many unrelated sites fail on a newly managed endpoint | Forward Trust rollout or endpoint trust-store problem | Presented issuer, endpoint enrollment state, certificate chain and a working managed comparison client | Repair the approved trust deployment before considering destination exceptions |
| Browser works but one application fails for the same service | Application-specific trust behavior or pinning | Application version, exact destination, application error and Decryption log | Confirm application requirements with its owner; do not assume browser success validates the application |
| One destination fails across multiple managed clients | Upstream certificate chain, profile restriction or destination-specific incompatibility | Server-side failure information, certificate chain, policy/profile and timestamp | Investigate the server and profile before broadening trust |
| Failure appears only after a policy or certificate change | Changed rule match, profile or trust configuration | Before/after configuration, matched rule and certificate issuer | Compare the specific change with the approved baseline |
| TLS succeeds but login, upload or API operation fails | Application workflow or another enforcement layer | Exact failed operation, related destinations, Traffic logs and relevant security logs | Continue beyond the TLS handshake; do not close on an HTTP landing page |
| A temporary no-decrypt test succeeds | Decryption is implicated, but the underlying cause is still unproven | Same-client paired results, matched rules and unchanged routing/security scope | Restore the baseline and distinguish fixable trust/profile issues from an approved technical exception |
The certificate and profile categories in this matrix are grounded in Palo Alto's PKI and troubleshooting documentation; the sequence and evidence fields are this article's recommended workflow.[2][3]
Step 1: capture a useful incident record
Palo Alto recommends gathering reproducible symptoms, investigating logs, recording attempted actions and checking that the fix did not create another problem.[3] Put that into a change-ticket worksheet before anyone edits a rule:
- Scope: affected application and version, endpoint class, approximate affected population and last known working time.
- Flow: test timestamp with timezone, client identifier retained only in your private ticket, destination hostname and actual protocol/port.
- Path: firewall or HA pair, virtual system where applicable, management platform and PAN-OS release.
- Policy: observed Decryption rule and profile, relevant Security policy and any existing exclusion.
- Certificate: issuer and validity information actually seen by the failing client; separately record server-side evidence where available.
- Business test: the action that fails, not just the page that opens; for example, sign-in followed by opening a document.
- Change history: certificate rotation, endpoint enrollment, application update and recent policy changes.
Keep captured identifiers and any packet data in your controlled incident system, not a public paste or blog comment. Do not export signing private keys for routine troubleshooting.
Start with the narrowest reproducible test
Use one authorized test endpoint and one documented application operation. Repeat it after each change. If you test with a different browser, user, network path and destination at the same time, the comparison becomes difficult to interpret.
A read-only browser certificate view is a useful starting point for web traffic. It is not a substitute for testing a native application's behavior. Record what you observed rather than writing “certificate is fine” without naming the chain and the client that accepted it.
Step 2: use Decryption logs without over-reading the error
For PAN-OS, Palo Alto documents Monitor → Logs → Decryption and error searches for UnknownCA and BadCertificate when investigating pinning.[1] These are log-search templates, not CLI commands, and they have not been executed in a lab for this article:
(error contains 'UnknownCA')
(error contains 'BadCertificate')
Apply the timestamp and client/destination filters appropriate to your release so you do not diagnose another user's session. Strata Cloud Manager has a different log interface and query presentation; use its documented Firewall/Decryption workflow rather than pasting PAN-OS expressions unchanged.[1]
If you cannot find the attempted session, check the actual path, selected log source and logging configuration before assuming TLS succeeded. Palo Alto notes that the Decryption policy controls log settings as well as traffic selection, action and associated profile.[3]
For an authorized packet capture, keep the collection narrow and time-bounded. Palo Alto recommends packet analysis to investigate client termination around the TLS handshake when checking suspected pinning.[1] Treat that timing as corroborating evidence, not as a reason to stop checking ordinary trust problems.
Step 3: distinguish Forward Trust failure from pinning
Repair trust deployment when trust is the problem
Palo Alto requires separate Forward Trust and Forward Untrust certificates and recommends an enterprise-PKI-based subordinate signing certificate when an enterprise PKI exists.[2] Validate your deployment against the documented design and your organization's certificate policy; do not improvise a new root-trust distribution process during an outage.
Never install the Forward Untrust certificate in endpoint trust lists or sign it with the enterprise root CA. Palo Alto explicitly warns that trusting Forward Untrust causes devices to trust sites the firewall does not trust and suppresses the intended warnings.[2]
As a practical acceptance check, compare a known-good managed endpoint with the failing one. Confirm the approved trust chain in the store used by the affected application. Ask the application owner whether it uses its own certificate configuration before altering machine-wide trust.
Confirm technical incompatibility before approving a bypass
With certificate pinning, the application accepts the pinned server identity rather than the firewall's replacement certificate, which prevents forward proxy decryption of that connection.[1] If ordinary trust checks pass but the application still rejects the intercepted session, collect the application vendor's requirements and a controlled comparison result.
Palo Alto documents the SSL Decryption Exclusion List as an option for required applications with pinned certificates, while allowing you to continue blocking applications that are not needed.[1] That is a security decision, not an automatic troubleshooting shortcut: decryption is bypassed and the encrypted content cannot be inspected by the firewall.[1]
Do not treat an exclusion as an instruction to create a broad Security allow rule. Review connectivity authorization independently and retain the other controls appropriate to the application.
Step 4: run a controlled comparison, not a global bypass
Hypothetical example: a managed browser reaches a service, but the service's desktop application fails after decryption rollout. The objective is to separate application behavior from a broken trust rollout without excluding all users or all destinations.
- Obtain approval for the diagnostic change, its test window and restoration procedure. Check whether inspection is permitted for the traffic involved.
- Save the current relevant configuration and record the original rule order. Use the Palo Alto configuration rollback checklist to plan recovery before the experiment.
- Run the failing application under the current decrypt policy. Save timestamp, operation, rule match and error evidence.
- If authorized and supported by your policy design, create a narrowly scoped, temporary no-decrypt policy test for the test source and intended destination. Do not substitute an unrestricted exception if the destination cannot be scoped safely.
- Commit through the normal change workflow and verify the intended rule actually matches. Start a fresh application connection, keeping other test conditions as consistent as possible.
- Repeat the identical business operation, then restore the original policy and retest. Document whether the original failure returns.
- Decide between trust repair, profile/server remediation, an approved exception or continued blocking. A successful bypass alone does not establish pinning.
Avoid clearing all production sessions just to simplify a test. Coordinate any targeted session intervention with the application owner. This article deliberately does not provide broad bypass commands.
Exception-review worksheet
Copy this table into your change system. Treat the expiry as a required review date with an owner; do not assume the exclusion mechanism automatically expires entries.
| Field | Required decision or evidence |
|---|---|
| Business requirement | Which operation is required, by whom, and what breaks without it? |
| Confirmed reason | Application/vendor evidence plus the observed diagnostic comparison |
| Exact scope | Required destinations and the scope the chosen exception mechanism actually supports |
| Security impact | What encrypted-content visibility is lost? Which controls remain? |
| Alternative | Can the server chain, client trust or application configuration be repaired instead? |
| Owner and approval | Application owner, security approver and person responsible for implementation |
| Review date | A named owner and scheduled reassessment, especially after application updates |
| Recovery | How to remove the exception and verify normal enforcement |
Prefer the smallest justifiable change. Do not add a broad wildcard solely because an application makes many connections; first inventory which destinations the failing operation actually requires. If you cannot explain the scope, pause and collect more evidence.
Verification and troubleshooting acceptance checklist
Palo Alto's troubleshooting guidance calls for retesting the original failure and monitoring for collateral effects after a fix.[3] Use this proposed acceptance matrix instead of the single criterion “the website opens.”
| Test | Acceptance evidence |
|---|---|
| Original application operation | Sign-in and the affected business action complete on the authorized test client |
| Fresh connection | Result reproduced after starting a new application connection, with a fresh timestamp |
| Intended rule match | Log evidence shows the expected policy behavior for the test |
| Unrelated decrypted destination | Existing approved decryption still works outside the changed scope |
| Non-target client or destination | Temporary test scope has not unintentionally expanded |
| Certificate trust | No Forward Untrust certificate was added to endpoint trust; approved chain behavior is preserved |
| Inspection decision | Decrypted traffic remains inspectable; any approved exception is explicitly recorded as a visibility gap |
| Restoration | Diagnostic rules are removed or replaced by the approved final configuration |
| Ownership | Evidence, review date and escalation contact are recorded |
If the application still fails, hand the next engineer the paired test record, not just screenshots of an error. Include the exact attempted operation, policy/profile references, relevant certificate chain information and the outcome of each single-variable test. Redact secrets and unrelated user data before sharing with support.
Practical takeaways
Start by separating the client-facing and server-facing investigations. Use UnknownCA and BadCertificate to find evidence, not to approve exceptions automatically. Repair trust deployment where possible, never make Forward Untrust trusted, and keep any unavoidable exclusion narrow, reviewed and owned.
For a different “connected but unusable” problem, see the IPsec tunnel-up/no-traffic troubleshooting matrix. Browse Start Here and the networking resources page for the wider troubleshooting collection.
Post a Comment