Dynamics 365 Business Central: clarification about OAuth2 authentication in v20

In a recent event we had with the partners community on the new Dynamics 365 Business Central 2022 Wave 1 release (version 20) we received some questions and requests of clarifications about Basic authentication deprecation.

The reason of this quick post is trying to clarify what happens on Basic Authentication in Dynamics 365 Business Central SaaS from version 20. As you know, Microsoft announced time ago that Basic authentication is deprecated on the SaaS environment and now you need to start using the OAuth 2.0 authorization protocol.

Simply speaking, OAuth 2.0 is a standard authorization protocol designed to allow an application to access resources hosted by other applications on behalf of a user. OAuth 2.0 provides consented access and restricts actions of what the client app can perform on resources on behalf of the user, without ever sharing the user’s credentials. OAuth 2.0 uses Access Tokens (that essentially are data that represents the authorization to access resources on behalf of the end-user) and scopes (used to specify exactly the reason for which access to resources may be granted). OAuth flows are essentially processes supported by OAuth for authorization and resource owners for authentication. There are OAuth flows enabling users to enter credentials via an OAuth login prompt directly into the app, or even supporting authentication without user involvement for back-end systems.

But what about the future of Basic authentication and OAuth 2.0 in Dynamics 365 Business Central? Let’s try to fix some points…

They 4 key points to remember are the following:

  1. Basic Authentication is deprecated on version 20 and it will be unsupported started from now (no support requests).
  2. New tenants created on version 20 cannot use Basic authentication.
  3. Existing tenants upgraded to version 20 can continue to use Basic authentication.
  4. Basic authentication will be disabled for everyone on Dynamics 365 Business Central version 21.

Despite the possibility of point 3, please upgrade all your integrations to OAuth as soon as possible. There’s no valid reasons to wait, OAuth is quite easy to setup and absolutely more secure and future proof.


    1. This applies to BC connections (external apps connecting to BC). For BC connecting to external apps, the authentication protocol depends on what the external app requires.


  1. Hi, for SOAP codeunits with multiple methods and parameter passing, such as xmlport, how can you use OAuth2 authentication, given that the WSDL generated by BC doesn’t expect anything other than Basic?


  2. Hi Demiliani
    have you heard anything about that Microsoft recently paused the rollout of v20 and after that Basic Authentication has been removed, and now only OAuth is supported?


  3. Hello
    I’ve just tested basic auth on an existing tenant that upgraded from V19 to V20 overnight, and basic auth failed with error:
    “error”: {
    “code”: “Authentication_InvalidCredentials”,
    “message”: “Web service access key is no longer supported as authentication. Please use OAuth.”


    1. Microsoft is rolling out a hotfix these days that enables basic auth on all sandbox v20 clusters.
      If you have a production environment that need WSK for v20 for a few more months (until October), then please create a support ticket to get it enabled.


  4. Hi Demiliani, for an existing powershell script that still uses Web Service key, do you have any idea how to convert it to Token? I’m already picking up the correct token, I just don’t know how to pass it to the credentials(this is to access a BC function within a published codeunit ):

    #Web service Key#$Credential = [System.Management.Automation.PSCredential]::new($user,(ConvertTo-SecureString $wsKey -AsPlainText -Force))
    #with Token, attempt to use AppID and token:
    $Credential = [System.Management.Automation.PSCredential]::new($ClientID,(ConvertTo-SecureString $token.AccessToken -AsPlainText -Force))

    $Client = New-WebServiceProxy -Uri $url -Credential $Credential


    1. A Powershell script for handling the OAuth 2 authentication is as follows:

      $clientid = “YOURCLIENTID”
      $clientsecret = “YOURCLIENTSECRET”
      $scope = “https://api.businesscentral.dynamics.com/.default”
      $tenant = “YOURTENANTID”
      $environment = “YOURENVIRONMENTNAME”
      $baseurl = “https://api.businesscentral.dynamics.com/v2.0/$environment”
      # Get access token
      $body = @{grant_type=”client_credentials”;scope=$scope;client_id=$ClientID;client_secret=$ClientSecret}
      $oauth = Invoke-RestMethod -Method Post -Uri $(“https://login.microsoftonline.com/$tenant/oauth2/v2.0/token”) -Body $body
      # Get companies
      $companies = Invoke-RestMethod `
      -Method Get `
      -Uri $(“$baseurl/api/v2.0/companies”) `
      -Headers @{Authorization=’Bearer ‘ + $oauth.access_token}


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.