Internet Access TLS inspection troubleshooting

This page's changes and edits · All guidance changes

Microsoft's edit · 5 Nov 2025 23:40 UTC

Nov 05 completed draft and added TOC and related links

Microsoft's commit message in MicrosoftDocs/entra-docs · commit f7cb1c0 · +23 ~~−16~~ lines · also on GitHub

11 ---

22 title: Troubleshoot Transport Layer Security inspection errors

3 −description: "Learn how to troubleshoot Transport Layer Security (TLS) inspection errors in Global Secure Access."

3 +description: "Learn how to troubleshoot and resolve Transport Layer Security (TLS) inspection errors in Global Secure Access."

44 author: HULKsmashGithub

55 ms.author: jayrusso

66 ms.service: global-secure-access

⋯ 2 unchanged lines

99 ms.date: 11/05/2025

1010 ai-usage: ai-assisted

1111

12 −#customer intent: I want to troubleshoot Global Secure Access TLS inspection issues.

12 +#customer intent: As an IT admin, I want to troubleshoot Transport Layer Security (TLS) inspection errors.

1313

1414 ---

1515

1616 # Troubleshoot Global Secure Access Transport Layer Security inspection errors

17 −

1817 This article explains common troubleshooting scenarios when deploying a Transport Layer Security (TLS) inspection policy.

1918

2019 ## Certificate problem: unable to get the local issuer certificate

21 −

2220 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.

2321

2422 ### Troubleshooting for Git

25 −

2623 You can direct Git to use Windows' certificate store:

2724

28 −git config --global http.sslbackend schannel

25 +`git config --global http.sslbackend schannel`

2926

30 −Alternatively, you can append the certificate to Git's Certificate Authority bundle:

27 +Alternatively, you can append a custom TLS inspection root certificate to Git's Certificate Authority bundle so Git trusts your internal certificate authority.

3128

29 +```PowerShell

3230 $certPath = "./myTLSInspectionRootCA.crt"

3331 $gitCAPath = git config --get http.sslcainfo

3432 if ($gitCAPath) {

⋯ 2 unchanged lines

3735 } else {

3836 Write-Host "Git CA bundle path not found"

3937 }

38 +```

4039

4140 ### 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:

41 +Python-based tools, such as Azure CLI, fail without the correct certificate authority. You can install `pip-system-certs` so Python trusts the Windows certificate store:

4442

4543 #### Azure CLI

44 +

45 +```powershell

4646 "C:\Program Files\Microsoft SDKs\Azure\CLI2\python.exe" -m pip install pip-system-certs

47 +```

4748

4849 #### System Python

50 +

51 +```bash

4952 python -m pip install pip-system-certs

53 +```

5054

51 −Alternatively, you can append the certificate directly to Python's certifi CA bundle:

55 +Alternatively, you can append a custom TLS inspection root certificate to Python’s CA bundle so Python trusts your internal certificate authority.

5256

57 +```powershell

5358 $certPath = "./myTLSInspectionRootCA.crt"

5459 $pythonCertPath = python -c "import certifi; print(certifi.where())"

5560 Get-Content $certPath | Add-Content -Path $pythonCertPath

5661 Write-Host "Certificate appended to Python's CA bundle"

62 +```

5763

5864 ### Troubleshooting for Docker

59 −

6065 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:

6166

6267 #### Debian or Ubuntu-based images

68 +

69 +```dockerfile

6370 COPY myTLSInspectionRootCA.crt /usr/local/share/ca-certificates/

6471 RUN update-ca-certificates

72 +```

6573

6674 #### Alpine-based images

75 +

76 +```dockerfile

6777 COPY myTLSInspectionRootCA.crt /usr/local/share/ca-certificates/

6878 RUN apk update && apk add ca-certificates && update-ca-certificates

79 +```

6980

7081 ## Applications don't work on mobile platforms

71 −

7282 Mobile applications might fail when TLS inspection is enabled due to certificate pinning, which restricts applications to trust only specific certificates.

7383

7484 ### Troubleshooting steps

75 −

7685 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).

7786

7887 ## 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.`

88 +For preview customers with a legacy TLS configuration, when creating a Certificate Signing Request (CSR), you might see this error: `Cannot create external certificate, an internal certificate already exists for tenant.`

8189

8290 ### Troubleshooting steps

83 −

8491 To resolve this issue:

8592 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).

8693 1. Go to https://aka.ms/tlspreview-portal

⋯ 11 unchanged lines

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 00:54 UTC. The commit date is when the source changed, which can be hours or days before Learn published it.