Add debug logging to tsh when there is a SAN mismatch connecting to Auth via Proxy

[cthach]

Closes #60676

Changelog: Improve error message of tsh when there is a certificate DNS SAN mismatch when connecting to Auth via Proxy.

Demo

Before

$ tsh login  --proxy=wrong.teleport.addr

ERROR: Cannot establish https connection to wrong.teleport.addr:
x509: certificate is valid for teleport.dev, *.teleport.dev, not wrong.teleport.addr
try a different hostname for --proxy or specify --insecure flag if you know what you're doing.

After

$ build/tsh login --proxy=somenumber.teleport.cluster.local:443

ERROR: Cannot connect to the Auth service via the Teleport Proxy.

  There might be one or more network intermediaries (like a proxy or VPN) that are modifying your connection before it
  reaches the Teleport Proxy. These intermediaries can alter how your connection is seen by the Teleport Proxy and
  routed, leading to certificate mismatches.

  To fix this, ensure that any network intermediaries are properly configured and not interfering with your connection.

DEBUG INFO:
  Host: somenumber.teleport.cluster.local

  Proxy Environment Variables:
    http_proxy: bad.proxy.example

  Server Certificate Details:
    Subject: OU=christhach@Chriss-MBP.local (Chris Thach),O=mkcert development certificate
    Issuer: CN=mkcert christhach@Chriss-MBP.local (Chris Thach),OU=christhach@Chriss-MBP.local (Chris Thach),O=mkcert development CA
    Serial Number: 12507712134221951695701778001476744009
    Not Before: 2025-08-14 17:37:06 +0000 UTC
    Not After: 2027-11-14 18:37:06 +0000 UTC
    DNS Names: [teleport.dev *.teleport.dev]
    IP Addresses: []

[rosstimothy]

While I think this is better than what we return to users today I don't know that it 100% covers the reasoning for the error message in the linked ticket.

@rosstimothy

I can enumerate that as one of potential causes in the error messages of why the client might be encountering a mismatched certificate, but it might not be the only cause for every situation. How about I suggest we go for a list approach covering more potential causes and fixes? Or would you prefer we just go with this one cause?

ERROR: The certificate does not match the address "wrong.teleport.addr" you are attempting to connect to.

  This usually happens for one or more of the following reasons:

    - You are connecting using an address that is not present in the certificate's Subject Alternative Names (SANs).
    - The Teleport Proxy is misconfigured and is presenting a certificate that does not include its public address in the SANs.
    - There is some network intermediary (like a proxy or VPN) that is modifying your connection that may alter how it is seen by the Teleport Proxy and routed.

  To fix this, ensure the following:

    - You are using the public address as configured in Teleport.
    - The Teleport Proxy is configured to present a certificate that includes its public address in the SANs.
    - Any network intermediaries are properly configured and not interfering with your connection.

  If you know what you are doing, you can bypass this check by using the --insecure flag.

That's better but I think it still might be confusing to people because the address they are connecting to might not be one that they are familiar with. When we dial auth we dial <hex-encoded-cluster-name>.teleport.cluster.local which I think would be rendered as the following.

ERROR: The certificate does not match the address "<hex-encoded-cluster-name>.teleport.cluster.local"

In that case I think it would be better if we can explicitly have a message indicating that we were unable to connect to Auth via the Proxy.

[cthach]

While I think this is better than what we return to users today I don't know that it 100% covers the reasoning for the error message in the linked ticket.

@rosstimothy
I can enumerate that as one of potential causes in the error messages of why the client might be encountering a mismatched certificate, but it might not be the only cause for every situation. How about I suggest we go for a list approach covering more potential causes and fixes? Or would you prefer we just go with this one cause?

ERROR: The certificate does not match the address "wrong.teleport.addr" you are attempting to connect to.

  This usually happens for one or more of the following reasons:

    - You are connecting using an address that is not present in the certificate's Subject Alternative Names (SANs).
    - The Teleport Proxy is misconfigured and is presenting a certificate that does not include its public address in the SANs.
    - There is some network intermediary (like a proxy or VPN) that is modifying your connection that may alter how it is seen by the Teleport Proxy and routed.

  To fix this, ensure the following:

    - You are using the public address as configured in Teleport.
    - The Teleport Proxy is configured to present a certificate that includes its public address in the SANs.
    - Any network intermediaries are properly configured and not interfering with your connection.

  If you know what you are doing, you can bypass this check by using the --insecure flag.

That's better but I think it still might be confusing to people because the address they are connecting to might not be one that they are familiar with. When we dial auth we dial <hex-encoded-cluster-name>.teleport.cluster.local which I think would be rendered as the following.

ERROR: The certificate does not match the address "<hex-encoded-cluster-name>.teleport.cluster.local"

In that case I think it would be better if we can explicitly have a message indicating that we were unable to connect to Auth via the Proxy.

Ohhhh that makes sense. I'll push an update.

[rosstimothy]

What do you think about removing the internal domain reference from this message? This is more of an internal thing that might be better suited for the debug info below.

[cthach]

Suggested change

	return fmt.Sprintf(`Cannot connect to the Auth service via the Teleport Proxy using the internal cluster domain %q.
	return fmt.Sprintf(`Cannot connect to the Auth service via the Teleport Proxy.

Yeah, good point. It's not really useful or actionable to an end user AFAIK, so I'm fine with removing it and moving it to the debug info.

Side note: I'm not totally familiar with how and why that internal cluster domain resolves to Auth. If you have any reading material, please send it my way if you get a chance.

[cthach]

Moved in 785103a

[juliaogris]

@juliaogris

Updated. Please see PR description and let me know if it's more readable now 🙏🏾

Looks great to me.

[backport-bot-workflows]

@cthach See the table below for backport results.

Branch	Result
branch/v17	Create PR
branch/v18	Create PR