Action Required: Upgrade to TLS 1.2 for Microsoft Dynamics 365 Connectivity

Table of Contents

Microsoft is implementing a critical security update for its Dynamics 365 (online) customer engagement applications. Specifically, versions 9.x for Dynamics 365 (online) and version 8.2 for Dynamics 365 (online) Government will soon mandate connections to utilize TLS 1.2 or a superior security protocol. This proactive measure is in alignment with evolving Microsoft and industry security policies, as well as best practices designed to safeguard data integrity and privacy. Organizations leveraging these Dynamics 365 services must review their existing configurations to determine potential impacts and undertake necessary upgrades to ensure uninterrupted connectivity. Failure to upgrade will result in a loss of access to these vital business applications, affecting various services and user experiences.

Applies to: Microsoft Dynamics 365 (Online)
Original KB number: 4051700

Understanding Transport Layer Security (TLS)¶

TLS, or Transport Layer Security, represents a cryptographic protocol that establishes secure communication channels over a computer network. It is the successor to Secure Sockets Layer (SSL) and is widely adopted as an industry standard for protecting the privacy and data integrity of information exchanged over the Internet. TLS is foundational for secure web browsing (HTTPS), email communication, instant messaging, and other data transfers. It operates by enabling client and server applications to communicate in a way that is designed to prevent eavesdropping, tampering, and message forgery, ensuring that data remains confidential and authentic.

A core function of TLS is the secure handshake process, where the client and server agree on cryptographic algorithms and exchange keys to establish an encrypted session. This handshake involves several steps, including server authentication, client authentication (optional), and the negotiation of symmetric encryption keys. Different versions of TLS—such as 1.0, 1.1, 1.2, and 1.3—have been released over time, each introducing improvements in security, efficiency, and robustness. The evolution of TLS is driven by the continuous discovery of vulnerabilities in older cryptographic protocols and the need to adapt to advancements in computing power and cryptanalysis.

The Impending Change: Phasing Out Older TLS Versions¶

Currently, all versions of Dynamics 365 Customer Engagement online support TLS 1.0, TLS 1.1, and TLS 1.2. However, this multi-protocol support is nearing its end. With the rollout of Dynamics 365 (online) version 9.x and Dynamics 365 (online) Government version 8.2, Microsoft will begin to actively block connections originating from clients or browsers that are still relying on the older and less secure TLS 1.0 and TLS 1.1 protocols. This transition marks a significant step towards bolstering the overall security posture of Dynamics 365 cloud services.

The decision to deprecate TLS 1.0 and 1.1 is rooted in the identification of several known vulnerabilities within these older protocols. For instance, TLS 1.0 and 1.1 are susceptible to various attacks like POODLE, BEAST, CRIME, and SWEET32, which can potentially compromise the confidentiality of transmitted data. By enforcing TLS 1.2, Microsoft aims to eliminate these security risks and ensure that customer engagement applications communicate over a more robust and resilient encrypted channel. It’s crucial to note that this mandate specifically targets Microsoft Dynamics 365 Online Customer Engagement environments; on-premises versions are not affected by this particular change, though adopting TLS 1.2 for on-premises deployments remains a strong security recommendation.

Understanding the Potential Impact¶

The enforcement of TLS 1.2 will have a direct and critical impact on any systems or applications attempting to connect to Dynamics 365 (online) version 9.x or Dynamics 365 (online) Government version 8.2 without the required security protocol. Any connection attempt that does not utilize TLS 1.2 will unequivocally fail, leading to significant disruption. This includes a broad spectrum of Dynamics 365 services, ranging from user access to the web application itself, to various integrations, custom applications, and reporting tools.

For users, this means they may be unable to log into their Dynamics 365 environment, effectively halting daily operations that rely on the platform. For developers and IT administrators, it signifies that custom plugins, workflows, integrations with other systems, and data synchronization processes could cease to function. Business intelligence tools that pull data from Dynamics 365, such as SSRS reports or Power BI dashboards, might also experience connectivity issues. The ripple effect of these failures can lead to loss of productivity, delays in critical business processes, and potentially compromised data flows if remediation actions are not taken promptly.

Strategies to Ensure Uninterrupted Connectivity¶

To prevent any disruption to your Dynamics 365 Customer Engagement services, proactive measures are essential. Organizations must assess their entire ecosystem of clients, browsers, and applications that interact with Dynamics 365 (online) and implement the necessary upgrades to ensure full compliance with the TLS 1.2 requirement. This involves a multi-faceted approach, addressing various components and scenarios.

For Supported Web Browsers¶

All officially supported web browsers for Dynamics 365 Customer Engagement (versions 7.x through 9.x) are inherently designed to comply with TLS 1.2 standards and should generally continue to function without issue. However, users or administrators might have explicitly disabled TLS 1.2 within their browser settings or operating system configurations for various reasons. In such cases, connectivity will be lost, and it becomes imperative to re-enable TLS 1.2.

Action Required:
* Verify Browser Settings: Users should check their browser’s security settings to ensure TLS 1.2 is enabled. For Internet Explorer/Edge, this is typically found under Internet Options > Advanced tab. For Chrome and Firefox, TLS settings are usually managed by the operating system, but outdated versions may not support it or may have it disabled.
* Operating System Updates: Ensure that the underlying operating system is fully updated. Modern operating systems (Windows 7 SP1, Windows 8.1, Windows 10, Windows Server 2008 R2 SP1 and later) support TLS 1.2 by default or through updates.
* Group Policy Review: In enterprise environments, IT administrators should review Group Policies that might override individual browser settings, ensuring that TLS 1.2 is explicitly enabled for all corporate machines accessing Dynamics 365.

For Code Built with the Dynamics 365 SDK¶

Custom client applications developed using the Dynamics 365 SDK must also be updated to support TLS 1.2. The underlying .NET Framework plays a crucial role in determining which TLS protocols are used by default.

Action Required:
* Recompile with .NET Framework 4.6.2 or Higher: For client applications, recompiling your projects with .NET Framework 4.6.2 or a newer version is the recommended approach. .NET Framework 4.6.2 and above enable strong cryptography by default, which includes TLS 1.2. If your existing code is already compiled against .NET 4.6.2 or later, no further action is required for the compilation target.
* Custom Plugins and Workflow Assemblies: For custom plugins and workflow assemblies deployed within Dynamics 365, the guidance remains to target .NET Framework 4.5.2. While the assemblies themselves might target 4.5.2, the execution environment (Dynamics 365 Online) will ensure TLS 1.2 communication. The critical factor here is the server-side environment where these components execute, which Microsoft controls and updates.
* Update Developer Tools: It’s also essential to ensure your developer tools are up to date. Download the latest version of developer tools, such as the Plugin Registration Tool and Configuration Migration Tool, from NuGet. Version 9.0 of these tools are backward compatible and fully support Dynamics 365 (online) version 8.2 Government and newer. This ensures your development environment also adheres to the new security standards.

Known Issue with Visual Studio 2015¶

Developers using Visual Studio 2015 may encounter a specific connectivity issue when running projects in debug mode, even if their applications target .NET Framework 4.6.2 or higher. This problem arises because the Visual Studio hosting process, which is used during debugging, is typically compiled against .NET Framework 4.5. By default, .NET 4.5 does not support TLS 1.2.

Action Required:
* Disable Visual Studio Hosting Process: As a temporary workaround for debugging, you can disable the Visual Studio hosting process. To do this, right-click on your project name in Visual Studio, select ‘Properties,’ navigate to the ‘Debug’ tab, and then uncheck the option labeled “Enable the Visual Studio hosting process.” This action ensures that the debugged application runs directly without the legacy .NET 4.5 hosting process interference, allowing it to utilize the TLS settings of its targeted framework. It’s important to remember that this only affects the debugging experience in Visual Studio 2015 and does not impact the final compiled binaries or executables. This issue is not present in Visual Studio 2017 or newer versions.

Important Note for .NET Based Applications¶

While recompiling with a newer .NET Framework is the preferred method, there are scenarios where explicitly forcing the TLS 1.2 protocol might be considered.

Action Required (with caution):
* Programmatic Enforcement: You can programmatically force the use of TLS 1.2 in your .NET application using the following C# command:

ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;

This command, when executed early in your application’s lifecycle (e.g., in Main() method or Application_Start), sets the default security protocol for all outgoing HttpWebRequest and WebRequest connections within that application domain.
* Considerations: This approach is generally not recommended as a long-term solution. Hardcoding SecurityProtocolType.Tls12 forces the application to always use TLS 1.2. Should a newer, more secure protocol like TLS 1.3 become the industry standard or mandatory for Dynamics 365 in the future, your application would require a code change and recompilation to adapt. It is usually better to rely on the operating system and .NET Framework’s default behavior, which automatically chooses the highest supported and most secure protocol available.

For Existing Code That Cannot Be Recompiled¶

In situations where recompiling existing .NET applications with a newer framework is not feasible due to legacy constraints or resource limitations, a machine-wide registry setting can be employed to force .NET Framework to utilize stronger security standards, including TLS 1.2.

Action Required (with extreme caution):
* Registry Modification: This is a powerful, machine-wide setting that impacts all .NET applications running on the system that rely on default TLS behaviors. It can have unintended consequences on other applications, so thorough testing is critical. Microsoft strongly recommends recompiling with .NET 4.6.2 or higher as the safer and more targeted solution.
* Registry Keys for .NET 4.5.2 and below: To force .NET 4.5.2 (and earlier versions that support TLS 1.2 through patches) to prefer TLS 1.2 machine-wide, you need to configure specific registry entries. These settings enable SchUseStrongCrypto and SystemDefaultTlsVersions for the relevant .NET Framework versions.
* For 32-bit applications running on a 64-bit OS, and for 64-bit applications:
* HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v4.0.30319
* SchUseStrongCrypto = 1 (DWORD)
* SystemDefaultTlsVersions = 1 (DWORD)
* For 32-bit applications:
* HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\v4.0.30319
* SchUseStrongCrypto = 1 (DWORD)
* SystemDefaultTlsVersions = 1 (DWORD)
These settings effectively instruct the .NET Framework to use TLS 1.2 when establishing secure connections. Refer to Microsoft Security Advisory 2960358 for detailed guidance under “Manually disable RC4 in TLS on systems running .NET Framework 4.5/4.5.¼.5.2.”

For Non-.NET Software¶

For any software or custom integrations not built on the .NET Framework that connect to Dynamics 365, the approach will vary depending on the programming language or platform used.

Action Required:
* Consult Vendor Documentation: It is essential to consult the documentation or support resources for your specific vendor or programming language. Most modern languages and frameworks provide mechanisms to specify the TLS version for outgoing connections.
* Common Examples:
* Java: Often controlled by JVM settings or specific HTTP client libraries (e.g., HttpsURLConnection or Apache HttpClient). Ensuring a recent JRE/JDK version is used is critical, and sometimes specific SSL context configurations are required.
* Python: Libraries like requests typically leverage the underlying OS’s SSL/TLS capabilities. Ensuring certifi and pyOpenSSL are updated often helps.
* Node.js: The https module in Node.js respects the system’s TLS settings and uses the highest available protocol by default, but specific versions of Node.js or older underlying OpenSSL libraries might need updates.
* Configuration Entries: Many languages allow for simple configuration entries or environment variables to dictate the minimum or preferred TLS version.

For PowerShell¶

PowerShell scripts that interact with Dynamics 365, particularly those using cmdlets like Get-CrmConnection from the Dynamics 365 SDK for PowerShell, must also explicitly enable TLS 1.2.

Action Required:
* Add Security Protocol Command: Insert the following command at the beginning of your PowerShell script, before any Dynamics 365 connection calls:

[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12

This line ensures that all subsequent web requests initiated within that PowerShell session will attempt to use TLS 1.2. It’s crucial to place this command early in your script to guarantee that it takes effect before any Dynamics 365 connectivity is attempted.

For Dynamics 365 for Microsoft Outlook¶

Users of the Dynamics 365 for Microsoft Outlook add-in must update their client to a version that supports TLS 1.2.

Action Required:
* Version 8.2.2.137 or later: For Dynamics 365 (online) Government version 8.2 and Dynamics 365 (online) version 9.x, download and install client version 8.2.2.137. This specific update ensures that the Outlook client component can establish secure connections using TLS 1.2 to the updated Dynamics 365 online instances.

For Unified Service Desk (USD)¶

Unified Service Desk (USD) is a client application used in contact centers, and it too requires an update to maintain connectivity.

Action Required:
* Latest USD Version: Download and install the latest version of Unified Service Desk. Versions 3.1, 3.2, and 3.3 are confirmed to be TLS 1.2 compliant.
* Older USD Versions: If you must continue using older versions of Unified Service Desk, you will need to apply specific registry entries on the client desktop. These registry modifications are similar to those for existing .NET code that cannot be recompiled, forcing the underlying .NET Framework on the client machine to prefer TLS 1.2. Refer to Microsoft’s documentation on “Unified Service Desk and TLS 1.2 mandate for Dynamics 365 Online” for detailed registry instructions.

For Dynamics 365 for Report Authoring¶

Tools used for authoring reports against Dynamics 365 also require updates to ensure TLS 1.2 compliance.

Action Required:
* Dynamics 365 (online) Government version 8.2: Download and install “Dynamics 365 Update 2.2 for TLS 1.2 supported clients” from the Microsoft Download Center.
* Dynamics 365 (online) version 9.x: Download and install version 9.0 of the Report Authoring Extensions.

For Dynamics 365 for Email Router¶

The Dynamics 365 Email Router, responsible for processing emails for Dynamics 365, needs to be updated to support TLS 1.2 for continued operation.

Action Required:
* Dynamics 365 (online) Government version 8.2: Download and install “Dynamics 365 Update 2.2 for TLS 1.2 supported clients.”
* Dynamics 365 (online) version 9.x: Download and install version 9.0 of the Email Router.

Example Connectivity Errors¶

When a client or application attempts to connect to Dynamics 365 without using TLS 1.2, various error messages may appear, indicating a failure in the secure communication handshake. Understanding these errors can aid in troubleshooting.

Browser Error¶

"Can't connect securely to this page
This might be because the site uses outdated or unsafe TLS security settings. If this keeps happening, try contacting the website's owner."

This message is a clear indicator that the browser’s current security configuration is insufficient to establish a secure connection with the Dynamics 365 endpoint, which is now enforcing TLS 1.2. It suggests that either the browser itself is outdated, or its security settings have TLS 1.2 disabled. The “outdated or unsafe TLS security settings” explicitly points to the need for a protocol upgrade.

Connector Error¶

"Microsoft.Xrm.Tooling.CrmConnectControl Information: 8 : Login Status in Connect is = Validating connection to Microsoft Dynamics CRM...
Microsoft.Xrm.Tooling.Connector.CrmServiceClient Error: 2 : ERROR REQUESTING Token FROM THE Authentication context
Microsoft.Xrm.Tooling.Connector.CrmServiceClient Error: 2 : Source : mscorlib
Method : ThrowIfExceptional
Error : One or more errors occurred.
Stack Trace : at System.Threading.Tasks.Task.ThrowIfExceptional(Boolean includeTaskCanceledExceptions)
at System.Threading.Tasks.Task`1.GetResultCore(Boolean waitCompletionNotification)
at System.Threading.Tasks.Task`1.get_Result()
at Microsoft.Xrm.Tooling.Connector.CrmWebSvc.ExecuteAuthenticateServiceProcess(Uri serviceUrl, ClientCredentials clientCredentials, UserIdentifier user, String clientId, Uri redirectUri, PromptBehavior promptBehavior, String tokenCachePath, Boolean isOnPrem, String authority, Uri& targetServiceUrl, AuthenticationContext& authContext, String& resource)
Inner Exception Level 1 :
Source : Microsoft.IdentityModel.Clients.ActiveDirectory
Method : Close
Error : Object reference not set to an instance of an object.
Stack Trace : at Microsoft.IdentityModel.Clients.ActiveDirectory.HttpWebResponseWrapper.Close()
at Microsoft.IdentityModel.Clients.ActiveDirectory.AuthenticationParameters.<CreateFromResourceUrlCommonAsync>d__0.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task)
at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
at Microsoft.IdentityModel.Clients.ActiveDirectory.AuthenticationParameters.<CreateFromResourceUrlAsync>d__8.MoveNext()"

This error trace from a .NET-based connector indicates a failure during the authentication process, specifically when requesting a token. The underlying cause, though not explicitly stating “TLS 1.2,” points to a failure in the secure communication channel. The One or more errors occurred and Object reference not set to an instance of an object can mask the true root cause, which is often a TLS handshake failure when the client cannot negotiate a suitable (TLS 1.2) protocol. The Microsoft.IdentityModel.Clients.ActiveDirectory component, responsible for authentication, is unable to complete its task securely.

"Inner Exception Level 1 :
Source : System
Method : GetResponse
Error : The underlying connection was closed: An unexpected error occurred on a send.
Stack Trace : at System.Net.HttpWebRequest.GetResponse()
at System.ServiceModel.Description.MetadataExchangeClient.MetadataLocationRetriever.DownloadMetadata(TimeoutHelper timeoutHelper)
at System.ServiceModel.Description.MetadataExchangeClient.MetadataRetriever.Retrieve(TimeoutHelper timeoutHelper)
Inner Exception Level 2 :
Source : System
Method : Read
Error : Unable to read data from the transport connection: An existing connection was forcibly closed by the remote host.
Stack Trace : at System.Net.Sockets.NetworkStream.Read(Byte[] buffer, Int32 offset, Int32 size)
at System.Net.FixedSizeReader.ReadPacket(Byte[] buffer, Int32 offset, Int32 count)
at System.Net.Security.SslState.StartReceiveBlob(Byte[] buffer, AsyncProtocolRequest asyncRequest)"

This is a more direct indication of a TLS issue. “The underlying connection was closed: An unexpected error occurred on a send” combined with “Unable to read data from the transport connection: An existing connection was forcibly closed by the remote host” are classic symptoms of a TLS handshake failure. This means the client attempted to initiate a secure connection, but the server (Dynamics 365) rejected it because the proposed TLS protocols (likely TLS 1.0 or 1.1) were not acceptable. The connection is terminated prematurely by the server, indicating a protocol mismatch.

Additional Information and Best Practices¶

Beyond the immediate actions required, there are several best practices and additional considerations to ensure a smooth transition and maintain robust security for your Dynamics 365 environment.

Best Practices for TLS Configuration¶

• System-Wide Compliance: Don’t just focus on individual applications. Ensure your entire IT infrastructure, including operating systems, network devices (firewalls, load balancers, proxies), and middleware, is configured to support and prefer TLS 1.2.
• Regular Patching: Keep all systems and applications, especially those interacting with cloud services, fully patched and up-to-date. Security updates often include critical TLS-related enhancements and bug fixes.
• Automated Scans: Implement regular security scans of your internal and external network endpoints using tools like SSL Labs’ SSL Server Test or Nmap with SSL scripts. These tools can identify systems still using weak TLS protocols or cipher suites.
• Phased Rollout: For larger organizations, consider a phased rollout of TLS 1.2 enforcement in your custom applications and client environments. This allows for testing and remediation in a controlled manner.

Testing and Validation¶

After implementing the necessary upgrades, it is crucial to thoroughly test all components and integrations that connect to Dynamics 365.
* User Acceptance Testing (UAT): Conduct UAT with a representative group of users to ensure their browsers and client applications can successfully connect and operate Dynamics 365 as expected.
* Integration Testing: Verify all custom integrations, data synchronization jobs, and API calls are functioning correctly with TLS 1.2.
* Developer Tools Validation: Confirm that developer tools, like the Plugin Registration Tool, can connect to and interact with Dynamics 365.

Compliance Considerations¶

The move to TLS 1.2 is not just a Microsoft mandate; it aligns with various industry compliance standards.
* PCI DSS: The Payment Card Industry Data Security Standard (PCI DSS) explicitly requires the deprecation of SSL/early TLS for protecting payment card data.
* HIPAA & GDPR: While not directly mandating TLS 1.2, these regulations emphasize data protection and confidentiality, making strong encryption like TLS 1.2 a crucial component of compliance.

The Future: TLS 1.3¶

While TLS 1.2 is the current requirement, the industry is already moving towards TLS 1.3, which offers even greater security and performance improvements. By ensuring your systems are agile enough to adopt TLS 1.2, you position your organization well for future upgrades to TLS 1.3 and beyond. This flexible approach, where you rely on the system to choose the strongest protocol rather than hardcoding, is ideal for future-proofing your IT landscape.

Troubleshooting Guide¶

Should you encounter connectivity issues even after implementing the recommended actions, consider the following general troubleshooting steps:
1. Verify OS Support: Confirm the client operating system fully supports TLS 1.2 and has the necessary updates installed.
2. Check .NET Version: For .NET applications, verify the target .NET Framework version and ensure SchUseStrongCrypto and SystemDefaultTlsVersions are correctly set if relying on registry changes.
3. Firewall/Proxy Configuration: Ensure no firewalls, proxies, or network appliances are interfering with TLS 1.2 connections by downgrading or blocking them.
4. Application Logs: Review application logs for more specific error messages that might pinpoint the exact failure point.
5. Packet Capture: Use tools like Wireshark to capture network traffic and analyze the TLS handshake process to identify where the connection is failing.

---

Upgrading to TLS 1.2 for Microsoft Dynamics 365 connectivity is a critical security measure that impacts every organization using these cloud services. By proactively addressing these requirements, you can safeguard your data, maintain business continuity, and align with modern security standards.

Have you already begun your TLS 1.2 upgrade journey for Dynamics 365? What challenges or successes have you encountered? Share your experiences and questions in the comments below!