Walkthrough: Creating a console application that use OAuth to Authenticate Business Central Web Services (REST API, OData or SOAP)

Article
09/29/2023

Note

Azure Active Directory is now Microsoft Entra ID. Learn more

Business Central supports the OAuth authorization protocol for SOAP and OData web services. The article provides a walkthrough guide on how to create a custom .NET application that connects to Business Central web services and authenticates by using OAuth.

Tip

For some samples about setting up OAuth, see the BCTech repo.

About OAuth

Note

Azure Active Directory is now Microsoft Entra ID. Learn more

OAuth is an open standard for authorizing access to web services and APIs from native clients and websites in Microsoft Entra ID. In Business Central, OAuth is useful when your deployment is configured for Microsoft Entra authentication, either through your own Azure subscription or a Microsoft 365 subscription. OAuth lets users sign in to Business Central web services using their Microsoft 365 or Microsoft Entra credentials. Otherwise, they would have to use their Business Central account credentials (user name and password or web access key).

About the tasks in this article

The tasks illustrate how to use OAuth by walking you through the creation of a simple console application. The application returns a list of customers from a page in Business Central that is published as a web service. The console application connects to Business Central by using the ODataV4 endpoint.

Prerequisites and preparation

To complete the following tasks in this article, make sure your system meets the following requirements:

Configure Business Central for Microsoft Entra ID or Microsoft 365 authentication.

For more information, see Authenticating Business Central Users with Microsoft Entra ID.

Also, for purposes of this article only, make sure that your Business Central user account is configured with a Business Central Authentication password or web access key.

Get information about the Microsoft Entra tenant and the registered Business Central application.

When you configured authentication, you had to register Business Central as an application in Microsoft Entra ID. To complete the tasks that follow, you'll need the following information about the tenant and application. You can get this information from the Azure portal.

Setting/option Description

Microsoft Entra tenant ID The ID of the directory that's used by Business Central in Microsoft Entra ID. The Microsoft Entra tenant ID can be the tenant's domain name or GUID. In most cases, you can use the domain name. The domain name is typically in the form mytenant.onmicrosoft.com, which is the case if you have a Microsoft 365 subscription. You get the domain name from the Domain or Custom domain names settings for the AD tenant in the Azure portal. The Microsoft Entra tenant ID also makes up part of the WS-federation login endpoint setting that is configured for the Business Central Server instance

App ID URI When you configured Business Central for Microsoft Entra ID or Microsoft 365 authentication, you had to register Business Central as an application in the Microsoft Entra ID and also specify an APP ID URI. The APP ID URI has the format https://<domain>/<guid>, like https://mytenant.onmicrosoft.com/00001111-aaaa-2222-bbbb-3333cccc4444. You need the APP ID URI later to enable OAuth. You can get the ID from the Azure portal by viewing the Business Central application Settings in Active Directory. This value is also specified as the wtrealm in the WS-Federation Login Endpoint setting of the Business Central Server instance configuration. For more information, see Microsoft Entra ID Settings.

Enable OData Services and V4 Endpoint on the Business Central Server instance.

For more information, see OData Services Settings.
Install Visual Studio.

You can use any edition of Visual Studio that supports adding a connected service for web services. This article uses Visual Studio 2017.
Install OData Connected Service in Visual Studio.

This tool generates code to facilitate the consumption of OData services. This tool is functionally equivalent to the Add Service Reference for OData V3 service. To install OData Connected Service, download it from OData Connected Service and follow the instructions, or do the following steps in Visual Studio:
1. On the Tools menu, select Extensions and Updates > Online
2. Search for OData Connected Service, select it in the results, and choose Download.
3. Close Visual Studio to start the installation.

Setting/option	Description
Microsoft Entra tenant ID	The ID of the directory that's used by Business Central in Microsoft Entra ID. The Microsoft Entra tenant ID can be the tenant's domain name or GUID. In most cases, you can use the domain name. The domain name is typically in the form mytenant.onmicrosoft.com, which is the case if you have a Microsoft 365 subscription. You get the domain name from the Domain or Custom domain names settings for the AD tenant in the Azure portal. The Microsoft Entra tenant ID also makes up part of the WS-federation login endpoint setting that is configured for the Business Central Server instance
App ID URI	When you configured Business Central for Microsoft Entra ID or Microsoft 365 authentication, you had to register Business Central as an application in the Microsoft Entra ID and also specify an APP ID URI. The APP ID URI has the format `https://<domain>/<guid>`, like `https://mytenant.onmicrosoft.com/00001111-aaaa-2222-bbbb-3333cccc4444`. You need the APP ID URI later to enable OAuth. You can get the ID from the Azure portal by viewing the Business Central application Settings in Active Directory. This value is also specified as the `wtrealm` in the `WS-Federation Login Endpoint` setting of the Business Central Server instance configuration. For more information, see Microsoft Entra ID Settings.

Configure the App ID URI in the Business Central Server

When Business Central was registered in the Microsoft Entra tenant, it was assigned an APP ID URI. For example, in this article, the APP ID URI is https://mytenant.onmicrosoft.com/00001111-aaaa-2222-bbbb-3333cccc4444.

If you haven't already done so, set the Microsoft Entra app ID URI (or Azure AD app ID URI)) setting in the Business Central Server instance configuration to the same value as the APP ID URI in Azure. You can do this step by using the Business Central Server Administration tool, Set-NAVServerConfiguration cmdlet of the Business Central Server Administration tool, or by modifying the server instance CustomSettings.config file directly. For more information, see Configuring Business Central Server.

Expose a page as web service

Use the Business Central client to publish an object as a web service. For this article, use page 21 Customer Card from the CRONUS International Ltd. demonstration database and assign the page the service name Customer.

Search for and open the Web Services page.
Choose New.
On the new line, set: Object Type to Page, the Object ID to 21 column, and the Service Name to Customer.
Select the Published check box.

The following table shows the resultant web service setup that you'll see on the Web Services page.

Object Type Object ID Object Name Service Name Published OData URL

Page 21 Customer Card Customer √ https://myserver:7048/BC/ODataV4/Company('CRONUS%20International%20Ltd.')/Customer

In the OData URL, myserver is the computer that is running the Business Central Server instance, 7048 is the port number used for OData, and BCis the Business Central Server instance.

For more information about publishing, see Publish a Web Service.
After you publish the web service, you can now enter the OData URL in the address of an Internet browser.

You're prompted for your user name and password. The user name and password that you enter is the user name and password (or web service access key) of your Business Central account; not your Microsoft 365 or Microsoft Entra ID user name and password.

This condition illustrates the problem—users must use different credentials for Business Central clients than they do for Business Central web services.

Object Type	Object ID	Object Name	Service Name	Published	OData URL
Page	21	Customer Card	Customer	√	`https://myserver:7048/BC/ODataV4/Company('CRONUS%20International%20Ltd.')/Customer`

Register the console application in the Microsoft Entra tenant

Although you haven't yet created the console application, the next thing to do is to register it as an application in the same Microsoft Entra tenant in which you registered Business Central. Having to register the console application in Microsoft Entra ID makes sense because Microsoft Entra ID is the common authority that can issue security tokens that enable client applications to call server applications.

Using the Azure portal, register the console application as a native client application.

For information about how to do this step, follow the instructions in Quickstart: Register an app with the Microsoft Entra ID.

Use the following table as guide to help you determine some of the registration settings.

Option	Description and value	Example
Name	Specifies a descriptive name for the application.	`My Business Central Web Service App`
Application Type	Set to `Native`	`Native`
Redirect URI	Specifies the redirect URI to a valid URI for Microsoft Entra ID to redirect to in response to an OAuth request. This value is a logical URL that only acts as a unique identifier for the application. It doesn't have to refer to an actual endpoint; but it must be a valid URI.	`https://mybcclient`

Grant the console application delegated permissions to the Business Central application.
1. Select **API Permissions ** > Add a permission > APIs my organization uses.
2. Search for and select the Business Central application,
3. Select Delegated Permissions.
4. Under Permissions, select user_impersonation, then Add permissions.
For more information, see Permissions and consent in the Microsoft identity platform endpoint.
Make a note of the values of the Application (client) ID and Redirect URI values. You'll use this information later when you create the console application.

In the Azure portal, you can see these values by opening Settings for the registered application.

Now the custom client application is registered in Microsoft Entra ID, and it has the permission to call Business Central web services on behalf of a signed-in user.

Create the console application that connects to the OData Web Service using OAuth

Here, you'll create the Windows console application that connects to the Customer web service using the ODataV4 endpoint and authorizes users with OAuth.

Create the C# project

In Visual Studio, on the File menu, point to New, and then choose Project.
In the pane on the left, select Installed > Visual C# > Windows (Classic) Desktop > Console App (.NET Framework).
Set the Name and Solution Name to, for example, BusinessCentralCustomers, and choose OK to exit the New Project page.

Add a connected service reference for the OData web service

Temporarily set the Business Central Server to use Windows credential type.

This step allows you to access the OData endpoint from Visual Studio.
In the Solution Explorer pane, right-click the project (BusinessCentralCustomers), and then choose Add > Connected Service > OData Connected Service.
On the Configure Endpoint page, either keep the Service name of OData Service or change it if you like.
In the Address field, enter the URI for your OData web service.

The endpoint has the format https://<servercomputer>:<business-central-odata-port>/<business-central-server-instance>/ODataV4, for example:

https://localhost:7048/BC/ODataV4

Important

In this example, we use the HTTP protocol to illustrate the use of OData web services. We recommend that you use the more secure HTTPS protocol when you consume web services.
Choose Next.
On the Settings page, either keep the file name Reference or change it if you like.

The project is created, and your OData web service is added as a connected service reference. Next, you add the code that will show a list of existing customers, add a customer, and then rename the new customer.
From Solution Explorer, open the C# reference file (Reference.cs or whatever you named it) under Connected Services > OData Service, and then do the following steps:
- Replace all references to Microsoft.OData.Edm.Library.Date with Microsoft.OData.Edm.Date.
- Replace all references to Microsoft.OData.Edm.Csdl.EdmxReader with Microsoft.OData.Edm.Csdl.CsdlReader.
Set the Business Central Server to use AccessControlService credential type again.

Install and add a reference to the Microsoft.Identity.Client

The Microsoft.Identity.Client library contains utilities for token acquisition for OAuth web services. The library enables you to add code in the console application for acquiring a security token to access Business Central web services. You can read about the package at Microsoft.Identity.Client.

Install the latest version of the package by using NuGet Package Manager in Visual Studio Code as follows:

Select Tools > NuGet Package Manager > Package Manager Console.

At the PM> prompt, enter the following command:

Install-Package Microsoft.Identity.Client -Version 4.40.0

Add a reference to Microsoft.Identity.Client in the console application project.

Add code to console application

In the code editor, write the following code. Replace brackets <> with your values.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using Microsoft.Identity.Client;

namespace MyBCCustomers
{
    class Program
    {
        // Microsoft Entra registrations:
        // Specifies the Microsoft Entra tenant ID
        const string AadTenantId = "<mytenant.onmicrosoft.com>";
        // Specifies the Application (client) ID of the console application registration in Microsoft Entra ID
        const string ClientId = "<00001111-aaaa-2222-bbbb-3333cccc4444>";
        // Specifies the redirect URL for the client that was configured for console application registration in Microsoft Entra ID
        const string ClientRedirectUrl = "<https://mybcclient>";
        // Specifies the APP ID URI that is configured for the registered Business Central application in Microsoft Entra ID
        const string ServerAppIdUri = "<https://mytenant.onmicrosoft.com/00001111-aaaa-2222-bbbb-3333cccc4444>";

        static void Main()
        {
            // Get access token from Microsoft Entra ID. This will show the login dialog.
                        // Get access token from Microsoft Entra ID. This will show the login dialog.
            var client = PublicClientApplicationBuilder.Create(ClientId)
                .WithAuthority("https://login.microsoftonline.com/" + AadTenantId, false)
                .WithRedirectUri(ClientRedirectUrl)
                .Build();
            AuthenticationResult authenticationResult = client.AcquireTokenInteractive(new string[] { $"{ServerAppIdUri}/.default" }).ExecuteAsync().GetAwaiter().GetResult();
            // Connect to the Business Central OData web service and display a list of customers
            var nav = new NAV.NAV(new Uri(<"https://localhost:7048/BC/ODataV4/Company('CRONUS%20International%20Ltd.'>)"));
            nav.BuildingRequest += (sender, eventArgs) => eventArgs.Headers.Add("Authorization", authenticationResult.CreateAuthorizationHeader());

            // Retrieve and return a list of the customers 
            foreach (var customer in nav.Customer)
            {
                Console.WriteLine("Found customer: " + customer.Name);
            }
            Console.ReadLine();
        }
    }
}

Build and run the application.

You should be prompted to enter a user name and password.

Summary

More and more companies adopt Microsoft 365 and integrate Business Central with Microsoft 365 to obtain single sign-on. As this occurs, it also becomes important that customers can authenticate to Business Central web services by using their universal credentials – the Microsoft 365 user name and password. OAuth is the web service authorization protocol that makes this possible.

This article covered how to configure Business Central web services for OAuth authorization. It also demonstrated how to create a simple .NET console application that connects to these web services. It is also possible to create other types of applications that authenticate using OAuth, such as modern Windows 10 apps, iOS apps, and Android apps. The Microsoft Microsoft Entra ID team has released libraries for all these platforms. See the following resources:

https://github.com/azureadsamples/nativeclient-windowsstore

https://github.com/MSOpenTech/azure-activedirectory-library-for-ios

https://github.com/MSOpenTech/azure-activedirectory-library-for-android

Partager via