You can use this page to diagnose and resolve TLS protocol mismatches when MDrivenServer or a Turnkey server cannot connect to an HTTPS API.
When this page applies
Use this procedure when a server-side operation fails while calling an API and the error indicates an SSL, TLS, secure connection, handshake, or connection problem.
In this situation, the MDriven component that makes the outbound request is the client. The API endpoint is the server. A connection can succeed only when both sides support at least one TLS protocol in common.
For example, an API may accept only a newer TLS protocol while the Windows installation that runs MDrivenServer or Turnkey does not have that protocol enabled. The HTTPS connection then fails before the API can process the request.
Diagnose the protocol mismatch
- Identify the HTTPS endpoint that the failing server-side action calls. For example, if an action calls
https://api.example.com/orders, testapi.example.com. - Open SSL Labs Server Test.
- Enter the API endpoint and review which TLS protocols the endpoint accepts.
- On the Windows machine that runs MDrivenServer or Turnkey, open SSL Labs Client Test in Internet Explorer.
- Record the protocols that the Windows client supports.
- Compare the two results. Find a protocol supported by both the API endpoint and the Windows client.
| Result | Meaning | Next action |
|---|---|---|
| At least one protocol is supported by both sides | A protocol mismatch is not established by these tests. | Review the complete error and the endpoint configuration. |
| No protocol is supported by both sides | The TLS handshake cannot select a protocol. | Enable an appropriate protocol on the Windows host, or ask the API owner to provide a compatible protocol. |
| The endpoint cannot be tested | The endpoint may be private, unavailable, or inaccessible from the test service. | Test from the relevant network and review the endpoint's TLS configuration with its owner. |
Enable a compatible protocol on Windows
If the comparison shows no shared protocol, use IIS Crypto on the Windows installation that hosts the failing MDriven component to add a protocol that matches the API endpoint.
- Run IIS Crypto on the Windows host where MDrivenServer or Turnkey runs.
- Enable a TLS protocol that is also offered by the API endpoint.
- Apply the change as required by the tool and Windows.
- Retry the server-side operation that calls the API.
Make changes on the machine that makes the outbound connection. For example, if a server-side job runs in MDrivenServer, changing TLS settings on an end user's browser does not resolve that job's API call.
Do not enable protocols without considering the security requirements of the API and your organization. Prefer a mutually supported current protocol rather than weakening the endpoint's TLS configuration.
This page covers outbound connections from MDrivenServer or Turnkey to an API. Use the following pages for other HTTPS scenarios:
- For local MDrivenServer and Turnkey development, see Documentation:LocalServers. Core builds described there can run with the
-nohttpscommand-line parameter when HTTPS is not needed for local development. - To create and trust a localhost developer certificate, see Documentation:LocalhostDevCert.
- To manage SSL and code-signing certificates, including PFX export, see Documentation:Certificate.
- For certificate setup on Azure with Let's Encrypt, see Documentation:Lets encrypt.
- For a Docker deployment, including the production path that uses an Nginx reverse proxy for SSL certificates and domain mapping, see Documentation:Deploying MDriven Server and Turnkey with Docker.
- For an Nginx reverse-proxy configuration, see Documentation:Serving MDriven with Nginx Server as a Proxy.
Troubleshooting checklist
Before changing Windows TLS settings, confirm the following:
- The failing URL is the API endpoint, not the URL of the Turnkey site.
- The operation is executed by MDrivenServer or Turnkey on the expected host.
- The SSL Labs endpoint result and the Windows client result have been compared for the same TLS protocols.
- The Windows host is the host on which you make the protocol change.
- You retry the same operation after the configuration change.