February 4th, 2020

Microsoft Graph subscriptions to change notifications – deprecating TLS 1.0 and 1.1

Vincent Biret
Principal Software Developer

Following earlier announcements from AppleGoogleMicrosoft, and Mozilla and a global continuing trend to deprecate TLS 1.0 and 1.1subscribers of change notifications on user data should take note. Starting May 15th, 2020, subscribers who use notification endpointthat only support TLS 1.0 or TLS 1.1 will stop receiving notifications, unless they upgrade their infrastructure to compliance and support TLS 1.2. 

Security and privacy are key commitments that Microsoft makes to our customers. Earlier versions of TLS make it challenging for us to live up to these commitments. 

We’re introducing a new latestSupportedTlsVersion property on the subscription entity to let our customers gradually transition to TLS 1.2. 

Subscriptions created with both the v1.0 and the beta endpoints are impacted by this change. 

How does this affect me? 

If your application implementchange notifications and the notification endpoint (as specified by the notificationURL property) does not support TLS 1.2, you must upgrade your infrastructure in order to keep receiving notifications. 

You can test your endpoints using the SSL server test tool provided by SSL Labs. After you run the test, if TLS 1.2 in the Configuration section is set to yes, you don’t need to take any action. 

If this protocol is set to no, you need to upgrade your infrastructure to support TLS 1.2. 

Key dates 

Starting on February 17, 2020: 

  • New subscriptions should be using notification endpoints that support TLS 1.2Compliant new subscriptions can ignore the latestSupportedTlsVersion property. 
  • Or, new subscriptions which use endpoints that are not yet compliant must set the latestSupportedTlsVersion propertyMeanwhile, start upgrading notification endpoints to compliance. 

Creating new subscriptions (POST) will fail if the notification URL does not support TLS 1.2. The operation will get the following error message: 

     The property latestSupportedTlsVersion is required to be v1_0 or v1_1 when the notification URL does not support TLS 1.2. 

You can either: 

  • Upgrade your infrastructure to TLS 1.2 or higher. (recommended) 
  • Or, include the latestSupportedTlsVersion property in your POST operation, and set it to v1_0 or v1_1 to match the highest protocol version your endpoint supports. You have till March 15, 2020, to complete the required infrastructure upgrade. 

Starting on March 16, 2020: 

  • New subscriptions must use compliant notification endpoints. 
  • Existing subscriptions should be using compliant notification endpoints. Subscriptions that are already compliant can ignore the latestSupportedTlsVersion property. 
  • Or, existing subscriptions that are not yet using compliant endpoints must be updated to set the latestSupportedTlsVersion property, while their notification endpoints are being upgraded to compliance. 

Creating new subscriptions (POST) will fail if the notification URL does not support TLS 1.2 or if latestSupportedTlsVersion is set to either v1_0 or v1_1The operation will get the following error message: 

     TLS 1.0 and 1.1 not supported for notification endpoint.  

The notification endpoints of new subscriptions must support TLS 1.2 at this time. 

Renewing subscriptions (PATCH) will fail, if the notification URL does not support TLS 1.2, and will get the following error message: 

     The property latestSupportedTlsVersion is required to be v1_0 or v1_1 when the notification URL does not support TLS 1.2. 

You can either: 

  • Upgrade the infrastructure for existing subscriptions to TLS 1.2. (recommended) 
  • Or, update existing subscriptions to include the latestSupportedTlsVersion property and set it to v1_0 or v1_1 to match the highest protocol version your endpoint supports. You have till April 15, 2020, to complete the required infrastructure upgrade. 

Starting on April 15, 2020:  

Existing subscriptions must also use compliant notification endpoints. 

Renewing subscriptions (PATCH) will fail if the notification URL does not support TLS 1.2 or if latestSupportedTlsVersion is set to either v1_0 or v1_1. The operation will get the following error message: 

     TLS 1.0 and 1.1 not supported for notification endpoint.  

The notification endpoints of existing subscriptions must now support TLS 1.2. 

Starting on May 15, 2020:  

Microsoft will disable TLS 1.0 and 1.1 on the backend services for outgoing calls. Any remaining change notification endpoints that haven’t been upgraded to TLS 1.2 will stop receiving notifications. 

Point of contact and additional feedback 

 If you have additional feedback or would like to discuss your production applications and TLS 1.0 & 1.1 deprecation, please email at msgraphwebhookstls@microsoft.com. 

National cloud deployments

The changes outlined in this articles impact the public cloud as well as all the national cloud deployments where Microsoft Graph change notifications are available.

Next steps 

  • Read our documentation. 
  • Send us feedback and suggestions through UserVoice. 
  • Find more information about the TLS deprecation. 

Author

Vincent Biret
Principal Software Developer

Microsoft Graph SDKs Software Developer