Dynamics 365 Business Central: SOAP and Basic Authentication deprecation

If you’re using web services with Dynamics 365 Business Central version, from version 17.X you should always check the notifications that pops up in the Web Services page because some changes are in place (and Microsoft alerts you about that):

The first notification appeared from version 17 is related to OData V3 deprecation. You should never use OData V3 now and instead go for the V4 endpoint. But that’s not all. There are two important changes that are in place and you should be aware of:

  1. If you expose UI pages as SOAP endpoints, soon you will receive a notification in the Web Services page. The capability of exposing UI pages as SOAP endpoints will be removed in a later release.
  2. Basic Authentication will be replaced by OAuth2 authentication in 2022 Wave 1.


Starting from 2021 Wave 1, Microsoft will start to deprecate the the possibility to expose UI pages as SOAP endpoints. This means that in Dynamics 365 Business Central 2021 Wave 1 you will start to receive a notification (warning) that signals you to avoid that and plans are to remove the possibility to do so in 2022 Wave 1.

The Microsoft’s end goal is to remove SOAP support at all (not only for UI pages) in future releases (2022 Wave 2?). The real problem here is not for pages exposed as web services but I think it’s more related to Codeunits exposed as SOAP endpoints.

I’ve done a quick analysis in the last weeks on the situation of the partners and customers I follow about this topic and results are the following:

  • 5% of them are using UI pages as SOAP endpoints
  • 15% of them are using UI pages exposed as OData endpoints
  • 10% of them are using custom pages exposed as SOAP endpoints
  • 90% of them are using custom pages exposed as OData endpoints
  • 75% of them are using API pages
  • 85% of them are using Codeunit exposed as SOAP endpoints

OData pages are totally replacing SOAP pages just now (at least on my cases). The problem is live on codeunits. Lots of customers and partners have processes called from external clients that are codeunits exposed as SOAP endpoints. If you’re on this situation, you should work on this and start using OData V4 Unbound and OData V4 Bound actions. Here I’ve explained in the past how to use them. You should also start replacing your page-based web services with APIs (as said frequently on our lates webcasts). I know that this cannot be a very quick process, but you’ve one year to do so, so start accordingly.


This is the most problematic topic I think. Microsoft is planning to not support anymore the Basic Authentication (username and web service access key) mechanism in the future. The capability to access web services in Business Central using Web Service Access Key (Basic Auth) is deprecated for SaaS and OAuth2 will be the authentication option for SaaS. Actual plans are to remove support for Basic Authentication on SaaS in 2022 Release Wave 1. 

Please remember that for on-premises, Web Service Access Key (Basic Auth) will remain an option for the time being. 

What’s the impact about that? Tremendous I think! The analysis on this topic on the same above customers and partners base says that 99% of them are using Basic Authentication on SaaS now and they’re absolutely not ready to support OAuth2.

With Dynamics 365 Business Central Microsoft has introduced the new OAuth2 module, a new module that has the goal to provide OAuth support for connecting Business Central to external services via AL code. This is very nice and easy to use, but unfortunately I think that it doesn’t solve the real integration problems.

Only 3% of the customers and partners I work with have integrations to external services handled via AL code. I think that the main scenario which Microsoft has to think is different. Normally the most common scenarios are external services that must connect to Dynamics 365 Business Central SaaS from the outside (personally I never recommend to call external services from AL if you plan to be scalable and if you plan to have an high volume of transactions) and in these scenarios removing Basic Authentication can be a big problem. Not all external services and external clients are ready to support OAuth2 soon or CAN support OAuth2. This will be a killer choice for sure.

The other problem is the OAuth2 flow to support. All the external integrations with Dynamics 365 Business Central actually works silently (without user interaction) and to permit this with OAuth2, service-to-service authentication flow must be supported absolutely.

Last personal opinion is related to the Sandbox environment: it’s quite a frequent case to have the need to test applications or integrations on the sandbox environment quickly. With Basic Auth support on sandbox, it’s quite easy to do so (just setup your user and you’re ready to go). But when Basic Auth will be removed, also for doing testing on sandboxes you need to register applications into AAD, grant permissions and so on, a task that normally cannot be done by a Business Central developer. This can be a problem.

But that is… be aware of these changes and act accordingly.

Please remember that with version 17 the telemetry data contains informations related to the web service protocols in use and from 17.3 also informations related to the web service calls and authentication protocols in use. This can help you on monitoring your customers and discover possible problems.

Comment List