In just under two weeks I’ll have to present how to use OAuth 2.0 authentication to call REST APIs of Dynamics 365 Business Central. Should be easy. Not only I have already done
OAuth integrations, but there is also a nice step-by-step tutorial by Microsoft specifically done for Business Central. So, I followed the steps to the letter (as much as that was possible), and after all was done, I tried to use Postman to get myself an OAuth 2.0 token for invoking Business Central REST APIs, but it didn’t work. No matter what I did, Postman kept returning this:
(Could not complete OAuth 2.0 login. Check Postman Console for more details.)
So I checked the Postman Console for more details.
Quite some detail.
After a ridiculous amount of time troubleshooting this, I figured it out. Depending on how your Business Central trial account was configured you may encounter this problem. On top of it add the fact that the documentation isn’t exactly straightforward and at couple of places leaves you (educated-)guessing. So I decided to write this blog in case you (or myself at some future point after I will have forgotten I’ve been in this mess) ever need it.
For the sake of simplicity, I’ll just assume that you have a Business Central account, trial or otherwise.
Let’s start first with how to really set it OAuth 2.0 authentication without any need for guesswork.
1. Sign in to Azure Portal with the account you use to sign in to Business Central.
2. Create an Azure Active Directory Web app / API registration
With OAuth 2.0 authentication things are not simple, for a reason. You have a back-end AAD-managed resource you want to access (such as Business Central) and a third-party app that wants to access it (whatever integration you are developing). There should be a contract between the two, that applies only to those two parties, that controls whether an app can access your AAD-managed resource. That’s why you need to create an app registration record in your Azure Active Directory to control access the integration you are developing has to Business Central.
This is what you are configuring in this stage.
In the navigation pane, click on Azure Active Directory
If, by any chance, you don’t see this there, then click on All Services:
Then in the All Services search box, enter “Directory”:
And then in the list of found entries click Azure Active Directory.
Follow these steps to create an app registration:
Microsoft’s Getting Started article fails here. First, it directs you to a generic Azure how-to document which explains how to create any application registration type, including native (which you must not choose for Business Central OAuth 2.0 authentication). Second, it never tells you which Sign-on URL to use. It should be obvious, but you might get creative with known URLs like https://login.microsoftonline.com/ or whatever else.
Now that you created your app registration, you must configure it.
Copying this key is important. Copy it and store it somewhere. Don’t lose it. This key will be used as your client secret when authenticating using OAuth 2.0, and you should only ever use one key for one integration (one application) that communicates with the back end. You can easily revoke the keys or create as many keys as you need for other integrations (applications) you will develop.
In case you prefer it this way, here’s a short gif video that shows all of these steps in one go:
Before you can try out your OAuth 2.0 authentication, you need to copy your directory ID. It will be used during the authentication protocol, and Azure will use it to know which specific Azure Active Directory to look into.
3. Test your OAuth 2.0 with Postman
I am using Postman for two reasons. First, apparently it’s the new black and these days everyone and his sister is using it to try out REST APIs. The second reason is that it already comes bundled with full support for OAuth 2.0 authentication and I don’t need to develop my own client.
Follow these steps:
Now, if you got this last one, under d), check the Consent on behalf of your organization, then click Accept, back in Postman in the Manage Access Tokens dialog scroll down, then click Use Token, and see you next time, we are done here, really – you just got your OAuth 2.0 token and can play around your Business Central APIs using production-grade security.
However, however… if you were as unlucky as I was the first time, you got this guy:
It took me ridiculous amounts of time to troubleshoot this one. No piece of documentation, no errors to hang on and google a stackoverflow solution, no absolutely nothing. Total darkness. It actually took me two additional Business Central trial tenants before I got one working. I got surprised when it finally worked, and then I figured out what is the problem: apparently you cannot use OAuth with an unmanaged Azure Active Directory.
To check if your AAD is managed, click All Services, then search for “Subscriptions” and then you see no subscriptions listed, like this:
Click Add and then attempt to add a subscription. If your AAD is unmanaged, you won’t be able to do this.
But how did I get into this mess in the first place? I must have done something wrong! Er, no. What I did is that I simply subscribed for Business Central trial with my e-mail address with an account that didn’t have AAD tied to it already. And this will happen to you too, if you do the same. I verified this by getting myself two extra domains (cost me $3.34 at NameCheap.com) that I didn’t first sign up for Azure, and then successfully signed up for Business Central trial only to get stuck at the OAuth 2.0 wall.
What happens when you sign up for Business Central trial? One of the following may happen:
Luckily, Azure provides a guide how to perform the administrative takeover:
The kind of takeover you want to perform is the internal takeover, and the steps are explained here:
Simply follow these steps, and your AAD becomes a managed one, and you are now able to authenticate with OAuth 2.0.
Now, I don’t know (but I do intend to find out!) whether this is something by design, or simply a bug somewhere in either the sign-up process or OAuth 2.0 process. I have strong reasons to suspect that it’s actually a bug. It can be 100% repeated if you try creating your new Business Central trial from an e-mail that has no prior knowledge or ties to any AAD domain. If you sign up using such an e-mail, even though Business Central wires up your fresh new AAD, it doesn’t allow you to use OAuth. However, if you have AAD already, and then sign up for Business Central, it seems to work. To me, this sounds like a bug, especially because setting up AAD is an infrastructure task, and signing up for Business Central trial is intended to be performed by people without any knowledge of AAD or infrastructure or anything.
In the course of finding out what exactly is causing OAuth 2.0 to fail and then finding out what fixes it, I have created a crazy number of Azure Active Directories and demo Business Central tenants, and what confuses me most is that I even managed to figure out a way to create an unmanaged AAD, get Business Central on top of it, and then still be able to use OAuth 2.0 without performing administrative takeover (I don’t have more time to play around this specific scenario, but it seems to me that if you create a new AAD from the context of an existing Azure account, and then create a user for that AAD, and then sign up for Business Central, you get an unmanaged AAD and working Business Central OAuth 2.0. Seems that the only way to get a “messy” one is to start the entire process from the Business Central trial sign-up page and use an account not bound to an AAD already.
In any case, I hope this helped you, and now I am tired, but there are miles to go before I sleep.
The post How do I: Really set up Azure Active Directory based authentication for Business Central APIs appeared first on Vjeko.com.