Internet Access TLS inspection troubleshooting
Microsoft's edit ·
Microsoft's commit message in MicrosoftDocs/entra-docs · commit 8ba658d · +97 −0 lines · also on GitHub
The file is new at this commit, or was moved here from another path: every line shows as added.
1
+---
2
+title: Troubleshoot Transport Layer Security inspection errors
3
+description: "Learn how to troubleshoot Transport Layer Security (TLS) inspection errors in Global Secure Access."
4
+author: HULKsmashGithub
5
+ms.author: jayrusso
6
+ms.service: global-secure-access
7
+ms.topic: troubleshooting-known-issue
8
+ms.reviewer: teresayao
9
+ms.date: 11/05/2025
10
+ai-usage: ai-assisted
11
+
12
+#customer intent: I want to troubleshoot Global Secure Access TLS inspection issues.
13
+
14
+---
15
+
16
+# Troubleshoot Global Secure Access Transport Layer Security inspection errors
17
+
18
+This article explains common troubleshooting scenarios when deploying a Transport Layer Security (TLS) inspection policy.
19
+
20
+## Certificate problem: unable to get the local issuer certificate
21
+
22
+This error occurs because developer tools like Git and Python don't use the operating system's certificate store by default. Instead, they maintain their own certificate stores and don't recognize the TLS inspection certificate.
23
+
24
+### Troubleshooting for Git
25
+
26
+You can direct Git to use Windows' certificate store:
27
+
28
+git config --global http.sslbackend schannel
29
+
30
+Alternatively, you can append the certificate to Git's Certificate Authority bundle:
31
+
32
+$certPath = "./myTLSInspectionRootCA.crt"
33
+$gitCAPath = git config --get http.sslcainfo
34
+if ($gitCAPath) {
35
+ Get-Content $certPath | Add-Content -Path $gitCAPath
36
+ Write-Host "Certificate appended to Git CA bundle"
37
+} else {
38
+ Write-Host "Git CA bundle path not found"
39
+}
40
+
41
+### Troubleshooting for Python
42
+
43
+Python-based tools, such as Azure CLI, will fail without the correct certificate authority. You can install pip-system-certs so Python trusts the Windows certificate store:
44
+
45
+#### Azure CLI
46
+"C:\Program Files\Microsoft SDKs\Azure\CLI2\python.exe" -m pip install pip-system-certs
47
+
48
+#### System Python
49
+python -m pip install pip-system-certs
50
+
51
+Alternatively, you can append the certificate directly to Python's certifi CA bundle:
52
+
53
+$certPath = "./myTLSInspectionRootCA.crt"
54
+$pythonCertPath = python -c "import certifi; print(certifi.where())"
55
+Get-Content $certPath | Add-Content -Path $pythonCertPath
56
+Write-Host "Certificate appended to Python's CA bundle"
57
+
58
+### Troubleshooting for Docker
59
+
60
+Docker containers might fail TLS connections when the TLS inspection certificate isn't trusted. Add your certificate to Docker's trusted certificates list by adding these commands to your Dockerfile:
61
+
62
+#### Debian or Ubuntu-based images
63
+COPY myTLSInspectionRootCA.crt /usr/local/share/ca-certificates/
64
+RUN update-ca-certificates
65
+
66
+#### Alpine-based images
67
+COPY myTLSInspectionRootCA.crt /usr/local/share/ca-certificates/
68
+RUN apk update && apk add ca-certificates && update-ca-certificates
69
+
70
+## Applications don't work on mobile platforms
71
+
72
+Mobile applications might fail when TLS inspection is enabled due to certificate pinning, which restricts applications to trust only specific certificates.
73
+
74
+### Troubleshooting steps
75
+
76
+Create a TLS bypass rule to exclude the application's destination FQDNs from TLS inspection. For detailed steps, see [Configure Transport Layer Security inspection policies](how-to-transport-layer-security.md).
77
+
78
+## An internal certificate already exists
79
+
80
+For early preview customers with legacy a TLS configuration, when creating a Certificate Signing Request (CSR), you may see this error: `Cannot create external certificate, an internal certificate already exists for tenant.`
81
+
82
+### Troubleshooting steps
83
+
84
+To resolve this issue:
85
+1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) as a [Global Secure Access Administrator](/azure/active-directory/roles/permissions-reference#global-secure-access-administrator).
86
+1. Go to https://aka.ms/tlspreview-portal<!-- Teresa, I don't think we should include this Private Preview link. Is there an equivalent for the Public Preview, or even the Prod environment? -->
87
+1. Browse to **Global Secure Access** > **Settings** > **Session management**.
88
+1. Select the **TLS Inspection** tab.
89
+1. Select and delete the Certificate URL.
90
+1. Select **Save**.
91
+
92
+## Related content
93
+
94
+- [Configure Transport Layer Security inspection policies](how-to-transport-layer-security.md)
95
+- [Configure Transport Layer Security inspection settings](how-to-transport-layer-security-settings.md)
96
+- [Frequently asked questions for Transport Layer Security inspection](faq-transport-layer-security.yml)
97
+- [What is Transport Layer Security inspection?](concept-transport-layer-security.md)
Microsoft's Markdown source from MicrosoftDocs/entra-docs, © Microsoft Corporation, under MIT. Changed lines with up to 3 unchanged lines around each; ChangeIntel kept this copy 10 Oct 17:01 UTC. The commit date is when the source changed, which can be hours or days before Learn published it.