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. 

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.
   At Azure portal, click on “Show Portal Menu” and “All Services”.
   
2. Find (or search “app registration”) and click on “App registrations”.
   
3. Click on “New registration” in the App registrations page.
   
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.
   
5. Next, we need to grant the API permission. Click on “API permission” on the menu and then click “+ Add a permission”.
   
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.
   
7. Here, we will need to click on “Delegated Permissions” and add “user_impersonation” and “Financials.ReadWrite.All”.
   
8. Next, click on “Application permissions” and check “app_access”, “API.ReadWrite.All”, and “Automation.ReadWrite.All”.
   
9. After adding permissions, we go back to the API permissions page. We will click on “Grant admin consent for Contoso”.
   
10. Click on “Yes” to grant admin consent.
    Then, all permissions will display “Granted for Contoso”.
11. Next, we will add new client secret. Click on “Certificate & secret” in the menu and click on “New client secret”.
    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.
    
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.
    
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.
    

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.
   
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.
   
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.
   
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”.
   
6. In the Configure New Token (Configuration Options) section there are numerous fields to populate.
   
   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:
      
   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.
   
8. After entering the login information, we will have Authentication complete message.
   
9. Back to the Postman system, we will see the generated Token and the ‘Access token added’ message in the bottom right-hand 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.
    

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

If the Dynamics 365 Business Central has an integration with a 3^rd 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.
   
2. In the Authentication page, add a Web Redirect URI https://businesscentral.dynamics.com/OAuthLanding.htm.
   
3. In Business Central, search “AAD”. Go to “Azure Active Directory Applications” and add a new an application.
   
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.
   
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.
   

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