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.


  1. Hi Stefano,

    I am intrigued. Why don’t you recommend calling external services from AL?
    We are precisely thinking of doing asynchronous processing of “jobs” from an AL background task that periodically gets “things to do” from an external system. Maybe you are referring to the limit of 3 concurrent background tasks in SaaS? If not, I’d like to know if there are other scalability factors that favour being called from AL over calling from it…


  2. In your scenario is probably fine using the backgroiujnd task and calling the external service from AL. I’m mainly referring to more complex scenarios like importing/exporting tons of sales orders or production orders from an external system. Handling that in AL has lots of drawbacks in my opinion:
    1) scalability: you cannot scale the service as needed if the calls are handled in AL
    2) AL is not the right choice for handling complex authentication protocols or complex services that uses for example SOAP with Attachments or similar
    3) performances: a complex service that transmits tons of data in AL, can reduce the performance of the tenant

    I think that the ERP should do the ERP, for small services is absolutely ok calling them from AL, but for complex integration scenarios, external services are much better and performant.


  3. If MS drops support for basic authentication and webkeys, then I think we have to start implementing Azure proxies for connections that still need more simple authentication. The idea will be that external partners contact Azure Functions that possibly save the payload into Azure Blob, from where BC then fetches the files.
    In my opinion this is unnecessarily complex when we already have been used to direct connections in/out of BC, but what can you do?


  4. Hi Stefano,

    First of all I wanted to congratulate you and thank you for all your contribution and all your posts which are always very interesting. It’s always a pleasure to find a new post from you in the morning on LinkedIn.

    After reading your article carefully, do I understand that currently it is not possible to communicate with business central APIs in server-to-server mode, using the client credentials grant flow, as proposed by Graph.

    In addition, I have just noticed that it is possible to use the basic authentication mode to authenticate with the business central APIs in a Production environment, while the Microsoft documentation says the opposite.

    I am currently working with a partner for the integration of its e-invoicing application via business central APIs.
    He needs to be able to get some data (vendor, item…) and to be able to create purchase invoices, without user interaction, and unfortunately Graph does not yet allow purchase document creation.

    Do you think that my partner can continue to use basic authentication mode in Production and that before it becomes obsolete, Microsoft will have given the possibility to use client credentials grant flow with Business Central APIs ?

    Thanks a lot.


    1. Thanks for your kind words. Microsoft is working on enabling service to service OAuth flow, so stay tuned (problem is mainly licensing related).
      Regarding Basic Auth: Microsoft has deprecated it now (you have a warning on the user card page) but Basic Auth is supported actually until Wave 1 2022 (one year from now). It will be removed ONLY when all the authentication flows will be supported, so for now you can go for it.


      1. Thank you very much for this quick response Stefano.
        We will therefore continue in this way, while waiting for the new authentication flows.
        Thanks a lot.


  5. Hello Stefano,
    I have question. I am trying to access webservice a new sandbox created form Production. The webserivce works fine in Production but when accessed for sandbox it gives error. I cant find the reason for this. The SOAP web service works but not Odata in sandbox.
    I get below error any idea on this:
    Details: “Microsoft.Mashup.Engine1.Library.Resources.HttpResource: Request failed:
    OData Version: 3 and 4, Error: The remote server returned an error: (500) Internal Server Error. (The argument is empty.
    Parameter name: nameOfTheItem CorrelationId: d2927a61-9a0d-42c1-9e4a-9607b79e9828.)
    OData Version: 4, Error: The remote server returned an error: (500) Internal Server Error. (The argument is empty.
    Parameter name: nameOfTheItem CorrelationId: 801e0e80-5ab7-4474-8c35-d3659455429c.)
    OData Version: 3, Error: The remote server returned an error: (500) Internal Server Error. (The argument is empty.
    Parameter name: nameOfTheItem CorrelationId: 5a0a3e9b-ea1c-46dc-9de5-11beae7d0c85.)”


      1. Hello Stefano,
        Thanks for your kind words.
        I think the webservices were copied from production to sandbox. I can see they are published.
        I also tried to create a new page webservice for odata but still that also stopped at that error.
        I am not able to get what exactly is stopping it.
        In the odata webservice url if i change the word Sandbox to Production it works fine however the moment we add sandbox to the url and try to get the response it gives the above error.


        Varun Tripathi


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.