I’m going to write a series of blog posts about OAuth Authentication and it is going to be like Star Wars movies where release order is not sequential. I’m going to write Part 2 first and then Part 3, 4 and then finally the Part 1.
In this blog post, I’m going to take you through the steps required to complete the OAuth client credentials flow for Business Central. Check this link if you want to refer to the official post from Microsoft.
The OAuth 2.0 client credentials grant flow permits a web service (confidential client) to use its credentials to authenticate when calling another web service instead of impersonating a user. In the client credentials flow, permissions are granted directly to the application itself by an administrator. When the app presents a token to a resource, the resource enforces that the app itself has the authorization to perform an action since there is no user involved in the authentication.
In order to complete the OAuth, 2.0 client credentials grant flow there are main 3 steps required to follow.
- Register the external application in Azure Active Directory.
- Create the external application in the Business Central.
- Grant concent to the external application.
Now let’s look into each of these steps and see how we can complete them.
Register the external application in Azure Active Directory
Navigate to Azure Portal and search for the App Registration, or you can navigate to Azure Active Directory and select App Registration as well. When you register your application with Azure AD, you’re creating an identity configuration for your application that allows it to integrate with Azure AD
Click on “New registration” as below
Provide a name for your app. For this example, I’m using “MVP OAuth 2.0″ as the name of the application. You have to decide how you want to use this newly registered application on this screen. If the application is only used within your tenant, then you can simply go with the “Single-tenant” option, but if you want other organizations to integrate your application with their tenant then you should go with the “Multitenant” option. The other two options are not supported by Business Central so therefore I will not go into them and explain them. Plus they are quite self-explanatory.
One other important thing on this screen is Redirect URI. You must select the type as Web and use the URL:
https://businesscentral.dynamics.com/OAuthLanding.htm
One common mistake most people use is typing everything in lower case letters, but it will not work as this is case sensitive. Therefore you need to type the URL as it is I have mentioned above.
Once you complete those steps you can click register and it will take a few seconds to register the external application and redirect you to the overview of the newly registered application.
Once you are redirected to the application overview screen, make sure to copy the Application (Client) ID into a notepad because we will need this value later to complete a few steps.
The next step we need to complete is to set the API permission for the application we registered. Once you copied the value to a notepad, click on the API permission.
Click on the “Add a permission” button from the API permission window to select which API access we are going to assign to the application.
Since we want the application to work with the Business Central, select “Dynamics 365 Business Cental” from the Microsoft APIs.
Once you select the “Dynamics 365 Business Central” from the Microsoft APIs, it will ask which type of permission is required to grant. Must select “Application permission” since we are registering this application in order to integrate with Business Central in the background without a signed-in user. In my next blog post, I will write more about the difference between Delegated permission and Application permission and their individual use cases and how the licensing works.
Once you select the “Application permissions” you will need to select what exact permission should be granted to the application. Currently, we only have 3 types of permissions and they are
- app_access – This is not supported by Business Central
- API.ReadWrite.All – Provide complete access to all the Business Central APIs.
- Automation.ReadWrite.All – Provide full access only to the Business Cental Automation APIs.
Keep in mind that “API.ReadWrite.All” has automation API access as well.
From the permission, you should select what you want to grant and in this example, I’m granting full API access to the external application.
Even though we have given full access to the Business Central APIs, it actually does not mean that the external application can simply call the Business Cental APIs and read and write data from and to the tables . Data access is controlled by the permission assigned to the application account in Business Central.
During the later stage of this blog post, I will explain how you can provide permission to the application account in Business Central.
Once you click “Add permission” on the above screen you will notice the added permissions on the screen and one thing to notice on the screen is the “Status“. It says “Not granted” for the current organization. If you went ahead with the “Single-tenant” option while you registered the application you can click “Grant admin content for <your organization name>“. If you went ahead with the “Multi-tenant” option don’t worry, I will show you how to grant permission in the later stage of this blog post. Even if it is a “Single-tenant” I normally do not grant permission from this screen and I do that through Business Central. Just bear with me a little and I will show you how to do that later.
The next step would be to create a new client secret in the application we created. Any client application or service (ex: Logic Apps, Power Automate or self-hosted app) that is going to access the Business Central through the registered application should submit the secret to the application so that the application can authenticate the request.
In order to create the secret, click on the “Certificates & secrets” and click on “New client secret“. Make sure to copy the value as you cannot view the secret value again. Another thing to remember is you cannot set the secret lifetime to unlimited and it can only go up to 24 months. This means every 2 years time you need to come to Azure Portal and create a new secret and distribute it to the client applications that are connecting to the application.
With that we completed the first step of setting up OAuth, 2.0 client credentials grant flow.
Just want to mention, I normally use Azure KeyVault to store these secrets as it is easy to manage and secure. If you are using Azure KeyVault, you can specify the expiry date of the secret when you create the secret there and then have a Logic App to check the expiry date daily and send you an e-mail when a secret is about to expire.
Create the external application in the Business Central
In this step, I’m going to explain the manual step of creating the external application in Business Central. There is another way of completing this step-through AL code, but I’m not going to go into that for this blog post.
In order to complete this step, you need to go into the Business Central and search for “Azure Active Directory Applications” or simply type “AAD“. You must be very familiar with this page if you have worked with Business Central and Dataverve virtual entity integration. Once you in the list page, click New to open the Card Page.
Enter the Client ID with the Application (Client) ID we copied to the notepad in the previous step while registering the application in Azure. Then provide a name for the application account.
If you can remember in one of the previous steps we have given full Business Central API access to the application we registered in Azure, and in that step, I mentioned we can control how the access can be controlled more precisely. So in order to do that you need to assign permission to the Application Account we just created and these assigned permissions will be used for all the API sessions that come through this Application Account. Remember that you cannot assign “Supre” permission to the Application Accounts.
When you create the Application Account in the “Azure Active Directory Applications“, in the background it creates a user account type “Application” in the Users.
Grant concent to the external application
We have successfully created an application in Azure and Application Account in Business Central. Now we need to tell the Azure Active directory that the application can access the Business Central through the Application Account user. This process is called granting content to the external application and it will then be stored as the service principle representing the application we registered.
Service Principle is a little bit complex topic and I will try to explain it in my next blog post.
Once you click “Grant Consent” Business Central will open up the sign-in window.
On the sign-in window, you need to use the user credentials of a user who has a Global Administrator, Application Administrator, or Cloud Application Administrator. If you don’t have these permissions on your user account, let a user with the above permission complete this step. Let’s assume your account has permissions, then once you enter your credentials it will take you to the below page where you need to accept the permission requested by the application we registered in step 01.
Once you click “Accept” on the above screen, Business Central will show you the confirmation dialogue like below. You are there and ready to use the application to access Business Central. If you want to be 100% certain about the access grant, you can verify that using Azure Portal. Check the next screenshot where I mentioned how you can check the verified status.
If you can remember in one of the previous steps I mentioned keeping in mind the Status of the API permissions. Earlier the Status of the API permission was “Not granted“, but since we completed the Grant step, now the status has been changed to “Grant for <your organization name>“
This means now the external application is set up and able to access Business Central.
Thank you and Regards,
Tharanga Chandrasekara