It’s a recurring question I get quite frequently: how to set up Business Central on-premises for Azure Active Directory authentication? And related to that, how to call APIs on Business Central on-premises with OAuth authentication? I know there are quite some sources out there like docs and blog posts about this topic. But I figured it would make sense to write it up myself as well, at least for my own record.
All information below can also be found at Microsoft docs in an excellent step through explanation: Authenticating Business Central Users with Azure Active Directory.
But there might be some pieces that I recommend differently… 
And I will add some background information here and there.
Prerequisites
There are a few prerequisites that are not in scope for this blog post.
- Business Central needs to be configured with a security certificate. This is a standard requirement for the credential-type setting that supports Azure AD authentication. The certificate can be a self-signed certificate for development environments, but for a production environment, it should be obtained from a trusted certificate authority. It’s also possible to get a free certificate from Let’s Encrypt. For more information about setting up security certificates with Business Central see this Microsoft docs article.
- An active Azure subscription is required. If you don’t have one, than it’s time to sign up for a free Azure subscription here. Then create an Azure Active Directory tenant as described here. Azure Active Directory is a free service and it will stay free forever, as indicated here.
- The Azure AD tenant must contain users that will be mapped to the users in Business Central. Read here how to manage users in Azure Active Directory. The main difference with Business Central database authentication is that the authentication for these users will be managed by Azure AD. Passwords and other security settings like multi-factor authentication are also managed inside Azure AD and not in Business Central.
- Microsoft also recommends to limit the lifetime of an access token to 10 minutes. Ths procedure is explained here. But let me also explain the why. The default life of an access token is 1 hour, and an access token can’t be revoked. That means that if somebody would be able to steal an access token he would be able to use it up to an hour. Limiting the lifetime increases security. This doesn’t mean that a user has to login again every 10 minutes. It’s just a matter of how long an access token can be used to start a session. After that, when a session is started, access is maintained for as long as the session is active. Later on you will also see how to extend the time that a user session may be inactive before the connection is dropped.
Business Central on-premises environment
On-premises environments with Business Central are quite diverse. Over the years I’ve seen different setups and it’s quite hard to describe an environment that fits everybody’s needs. But there are some common characteristics that apply to the majority of environments.
- Customer environments with multiple BC servers, like production and test.
- Partner environments with multiple BC servers, for different purposes like development, demo and test.
- In most cases those environments have the same user accounts.
- The BC servers are often configured with Windows authentication.
In many cases, companies do already use Azure Active Directory. Some have configured synchronization or federation between on-premises Windows Active Directory and Azure Active Directory, allowing users to access cloud services like Office365 with their on-premises credentials. It makes total sense to configure the on-premises Business Central environments to work with Azure Active Directory rather than Windows authentication. It decouples the Business Central environment from the on-premises Windows Active Directory. While user accounts can still be shared across multiple Business Central environments. And for developers creating API integrations, it allows them to work with OAuth authentication against a local development environment.
In this article, I want to explain how to set up an environment with multiple environments, PROD and TEST. They will be accessible with the URL’s
- https://prod.cronus.company/bc
- https://test.cronus.company/bc
In case you are doing this for one environment, just skip the steps that mention the second URL.
Azure Active Directory
The first step is to register the Business Central environment as an application in Azure Active Directory. This is required to give the Business Central environment its own identity that accepts Azure AD logins.
You can choose to register each individual Business Central environment as an application in Azure Active Directory or to create one application registration that covers them all. The option to register one application for multiple Business Central environments is easier because it requires less configuration. It is even possible to register one application in Azure Active Directory that works for multiple Azure Tenants.
To make this easier to understand, it would help to consider the application registration in Azure Active Directory as an application rather than a Business Central service tier. All Business Central environments of one customer are (most probably) the same application, with the same set of users. It could be different versions of the application, but still the same application.
From the point of view of an ISV, it could be one application running in multiple environments for developers, for testing purposes, or for demos. In different versions, in different stages of development, but still the same application.
Actually, you could even decide to have just one Azure app registration covering all your Business Central environments.
Why am I elaborating on this point? You will see when we get to the configuration settings. Let’s dive into it.
Open the Azure portal at https://portal.azure.com and open Azure Active Directory (direct link). Open App registrations in the left menu and then click on New registration.
The properties that need to be filled in are:
Click on Register to create the app registration.
The app registration has now one redirect URL for the PROD environment. We need to add another for the TEST environment.
Click on Authentication in the left menu. Then click on Add URI in the box with the title Web. Here we add the URL for the TEST environment. Don’t forget to click the Save button at the top.
This step must be repeated for every single Business Central environment that you want to use Azure Active Directory authentication. They all have their own unique redirect URL, and they must all be registered here.
Tip: If you have multiple Business Central server tiers running on a single server, then you don’t need to specify a redirect URL for each one of them. Just specify one redirect URI with only the hostname, e.g. https://bcserver.cronus.company. That should work for all Business Central server instances on that server. I couldn’t find a way to work with wildcards (which is considered unsafe anyway), so if you use subdomains as I do in this example, then you need to specify a redirect URL for each subdomain. You can specify up to 256 redirect URL’s.
The next step is to create an Application ID URI. Click on Expose an API in the left menu. Then at the top of the page, click on Set right after the text Application ID URI. A popup will be displayed with a suggested URI that has the format api://[guid], whereas the guid is the application id that is assigned to the app registration.
You can choose to use the suggested URI or create your own one. It must start with https, api, urn, or ms-appx and has no slash at the end. To use an https URI the domain that is used must be a verified domain. In this example, I choose to use https://businesscentral.cronus.company.
One may ask why I don’t use the full URL of the Business Central server instance, https://prod.cronus.company/bc. The reason is that I want to use this for multiple Business Central environments. So I’d rather go with a generic URI instead of one that is linked to a specific server. This is a URI, not a URL. A URI is an identifier of a resource and does not tell how to access it (that’s what a URL is for).
That’s it, no more settings are required in Azure. If you have been here before, you may have done extra steps like creating a scope or adding an app role in order to use OAuth authentication with APIs. As you will see in the next blog post, this is not required because there is an easier way.
Business Central server configuration
Let’s move over to Business Central and configure it for Azure Active Directory authentication. The first step is to set up at least one user for Azure AD authentication. Otherwise, you won’t be able to sign in after the switch to Azure AD.
A Business Central user account must be associated with an Azure AD account. This is done by specifying the user principal name in Azure AD (usually the email address) in the field Authentication Email on the User Card. This field is only editable in on-premises environments. Keep in mind, the field will not be editable in Docker sandbox containers because they behave like SaaS environments. For this reason, and because the other settings are also done with PowerShell, I prefer to set this field using a PowerShell command. See below for the full PowerShell script, including the command to configure the user.
Now we are ready to configure the Business Central server. The following settings must be done:
After configuring these settings, the Business Central server instance must be restarted.
The final step is to configure the web client to use AAD login. This can also be done with a simple PowerShell command. Of course, you can also change this setting manually in the navsettings.json file of the web client.
The full script to configure the server looks like this:
$ApplicationIDURI = "https://businesscentral.cronus.company"
$AADTENANTID = "97ff4abe-bcfe-4592-bb21-aa249ad4e83a"
$RedirectURL = "https://{HOSTNAME}/BC/SignIn"
#Configure user
Set-NAVServerUser -ServerInstance BC -User "ADMIN" -AuthenticationEmail "admin@cronus.company"
#Configure Business Central server instance
Set-NAVServerConfiguration -ServerInstance BC -KeyName ClientServicesCredentialType -KeyValue NavUserPassword
Set-NAVServerConfiguration -ServerInstance BC -KeyName WSFederationLoginEndpoint -KeyValue "https://login.microsoftonline.com/$AADTENANTID/wsfed?wa=wsignin1.0%26wtrealm=$ApplicationIDURI%26wreply=$RedirectUrl"
Set-NAVServerConfiguration -ServerInstance BC -KeyName ClientServicesFederationMetadataLocation -KeyValue "https://login.microsoftonline.com/$AADTENANTID/FederationMetadata/2007-06/FederationMetadata.xml"
Set-NAVServerConfiguration -ServerInstance BC -KeyName DisableTokenSigningCertificateValidation -KeyValue true
Set-NAVServerConfiguration -ServerInstance BC -KeyName ExtendedSecurityTokenLifetime -KeyValue "8"
Restart-NAVServerInstance -ServerInstance BC
#Configure Web Client for AAD login
Set-NAVWebServerInstanceConfiguration -WebServerInstance BC -KeyName ClientServicesCredentialType -KeyValue "AccessControlService"
This script can be executed for all Business Central server instances that must be configured for AAD login for the same Azure tenant. In my scenario, I run this for both PROD and TEST server instances.
Tip: for multi-tenant environments, the settings are slightly different. I’ve not included the differences here to make this blog post not overly difficult to follow. The Microsoft docs mentioned above will give you the required information for configuring multi-tenant environments.
The above script does not enable OAuth authentication for calling API web services. That’s for the next blog post. Stay tuned!