How to Enable OAuth 2.0 to Replace Web Service Access Key for Dynamics 365 Business Central

For Dynamics 365 Business Central Online environments, the basic authentication (Web Service Access Key) is deprecated, and users will need to use OAuth. In this blog, I will explain step-by-step how to set up the OAuth for Dynamics 365 Business Central Online through two main sections of processes.

The sections are:

  1. Enable and Configure OAuth 2.0 for Business Central on Azure Portal
  2. Using Postman to Generate and Test the OAuth 2.0 Token for Business Central Web Services
  3. (Optional) Register the Azure Active Directory in Business Central

The third section is optional and only applicable to systems with integrations with third party systems using Service-to-Service authentication. In these situations, registration is needed in Business Central with the Azure Active Directory.

Recently, we have been seeing the warning message pop up in Dynamics 365 Business Central that says “Web Service Access Key is no longer supported”. This means that if Business Central has any integrations or extensions, such as an EDI, POS, eCommerce, etc., then they will no longer be connected through the Web Service Access Key and the OAuth needs to be set up. Error message in D365 BC, web service access key no longer supported

Enable and Configure OAuth 2.0 for Dynamics 365 Business Central on Azure Portal

  1. Login to Azure portal with the same Business Central ID.
    D365 BC interface, with the user highlighted Azure interface, with the user highlighted At Azure portal, click on “Show Portal Menu” and “All Services”.
    Azure portal interface, with All Services highlighted
  2. Find (or search “app registration”) and click on “App registrations”.
    Azure interface, with App Registrations highlighted in navigation results
  3. Click on “New registration” in the App registrations page.
    Azure App Registration interface, with new registration highlighted
  4. Enter the name of the application. Choose who can use this app or access the API. We should select single tenant. For Redirect URL, choose Web and add the Business Central URL (https://businesscentral.dynamics.com/). Register the app.
    Azure App Registration interface, fields selected to register an application
  5. Next, we need to grant the API permission. Click on “API permission” on the menu and then click “+ Add a permission”.
    Azure App interface, Add API Permission highlighted
  6. After clicking “+ Add a permission”, the available API permissions will come up. If you can’t see Business Central, it is because the user doesn’t have a valid license.
    List of API permissions, with D365 Business Central highlighted
  7. Here, we will need to click on “Delegated Permissions” and add “user_impersonation” and “Financials.ReadWrite.All”.
    Request API permissions interface, with delegated permissions highlighted
  8. Next, click on “Application permissions” and check “app_access”, “API.ReadWrite.All”, and “Automation.ReadWrite.All”.
    Request API permissions interface, with application permissions highlighted
  9. After adding permissions, we go back to the API permissions page. We will click on “Grant admin consent for Contoso”.
    API permissions interface, with grant admin consent highlighted
  10. Click on “Yes” to grant admin consent.
    Grant admin consent confirmation with yes and no options Then, all permissions will display “Granted for Contoso”.Configured permissions interface, with the status of all APIs highlighted
  11. Next, we will add new client secret. Click on “Certificate & secret” in the menu and click on “New client secret”.
    Business Central OAuth interface, certificates & secrets page, with add new client secret highlighted The following three steps are important because they create the new key to pass the authentication. The key created is used later on in the process outlined in this article to pass the OAuth, which is the new way to authenticate.
  12. Enter client secret description and assign when it expires. Select the maximum expiry for 24 months. The “add” button can be found at the end of the page.
    Add client secret pop up, with all options showing in expiry drop-down list
  13. After adding, we will go back to the “Certificates & secrets” page. Copy and save the client secret value as shown in the screenshot. We need it for token generation by Postman.
    Business Central OAuth interface, certificates & secrets page, with client secret value highlighted
  14. Go back to the Overview section. At this time it is important to copy and save the Application (client) ID. We also need it for token generation by Postman.
    Business Central OAuth overview, with Application (client) ID highlighted

Using Postman to Generate and Test the OAuth 2.0 Token for Dynamics 365 Business Central Web Services

  1. Login to Business Central and search for Web Services.
    D365 BC interface, with Web Services selected
  2. In the Web Services page, select any web service, copy, and save the OData V4 URL. Here I am using G/L Entries Query web service.
    D365 BC Web Services interface, with the G/L entries OData V4 URL highlighted
  3. Download and install Postman.
  4. In the Postman workspace, click on “Collections” and “Create collection”. We can rename the collection to any name we prefer. Click on “Add a request” (add a GET request) and rename it.
    Postman interface with Create collection highlighted Postman interface with add a request highlighted Postman interface with OAuth G/L Entries Query highlighted
  5. In the top GET URL field, copy and paste the Web Service OData URL we had from Business Central.
    Then click on the Authorization tab, for Type, dropdown and select the “OAuth 2.0”.
    Postman interface with multiple fields highlighted in Authorization section
  6. In the Configure New Token (Configuration Options) section there are numerous fields to populate.
    Postman interface with Configure new token highlighted

    1. Token Name -> The same name as we did on the Azure, App Registrations. Refer to previous section, step 4.
    2. Grant Type -> Authorization Code.
    3. Callback URL -> https://businesscentral.dynamics.com/
    4. Auth URL -> https://login.windows.net/TENANT_ID/oauth2/authorize?resource=https://api.businesscentral.dynamics.com (Please add your Tenant ID).
    5. Access Token URL -> https://login.windows.net/TENANT_ID/oauth2/token?resource=https://api.businesscentral.dynamics.com (Please add your Tenant ID).
      To get your Tenant ID, you can copy from the URL you login to Business Central:
      Browser window with D365 BC URL tenant ID highlighted
    6. Client ID -> Refer to previous section, step 14. It is the “Application (client) ID we copied and saved.
    7. Client Secret -> Refer to previous section, step 13. It is the Client secret “Value” we copied and saved.
  7. After entering all parameters, click on “Get New Access Token”. We will see the login screen. Enter the user ID and password that we used for Business Central login.
    Microsoft D365 Business Central login window, enter email address Microsoft D365 Business Central login window, stay signed in option
  8. After entering the login information, we will have Authentication complete message.
    Get New Access Token window, saying authentication complete
  9. Back to the Postman system, we will see the generated Token and the ‘Access token added’ message in the bottom right-hand corner.
    Postman interface with access token highlighted in bottom right corner
  10. Now, click on “Send” to test the web service. We can see the OK status and the test result (Body & Headers) of G/L entries queried from Business Central. Our Authentication will be ready to use.
    Postman interface with status, time, size results highlighted

(Optional) Register the Azure Active Directory in Dynamics 365 Business Central

If the Dynamics 365 Business Central has an integration with a 3rd party system using Service-to-Service (S2S) authentication and the S2S authentication needs the Client Credentials OAuth 2.0. It requires users to register the Azure Active Directory (AAD) Applications in Business Central and this section will explain how to do that. For more information about S2S authentication, please see Microsoft’s Service-to-Service (S2S) Authentication article.

  1. Login to Azure Portal, go to the OAuth App registration we created previously. Click the Authentication.
    Azure interface, with Authentication section highlighted
  2. In the Authentication page, add a Web Redirect URI https://businesscentral.dynamics.com/OAuthLanding.htm.
    Azure interface, Authentication section, Redirect URIs section highlighted
  3. In Business Central, search “AAD”. Go to “Azure Active Directory Applications” and add a new an application.
    D365 BC interface, with Azure Active Directory Applications highlightedAzure Active Directory Application in D365 BC interface, add New highlighted
  4. Copy the Application (client) ID from Azure portal to the Client ID field in Business Central. After the description is entered, the system will add the user ID and user name automatically.
    D365 BC interface, with Azure Active Directory Application Card, description entered and shown in User Name
  5. Add the user groups, “D365 ADMINISTRATOR” & “D365 BUS FULL ACCESS”.
  6. Click “Grant Consent” and enter the Office 365 username and password to accept the permission requested.
    Grant Consent buttonMicrosoft D365 BC OAuth Permissions Requested pop-up windowConsent given successfully pop-up window in D365 BC

Contact us if you have any questions about how to enable OAuth 2.0 in Dynamics 365 Business Central.

Webinar - Dimensions in Dynamics 365 Business Central

In this webinar, we’ll start with the basics of the concept and the different types of dimensions, then we’ll cover how to best set up your dimensions and use them for insights in reports.

December 7
9:00 am – 9:30 am PST

Register Here

Webinar - Dimensions in D365 Business Central

Dec. 7
9:00 am – 9:30 am PST

Register