Web service authentication

  • 5 minutes

When you develop an application in another programming language, such as C#, Python, or Java, you need to provide authentication credentials to the Business Central service before you can work with different web services. The authentication can be used for both OData and SOAP web services in Business Central.

There are two options to authenticate with Business Central: Basic Authentication and OAuth2 Authentication. With Basic Authentication, you need to provide a username and a web service access key as the password, while for OAuth2, you need to configure an Microsoft Entra ID Application. Basic Authentication isn't supported for Business Central SaaS since April 2022. Only for the on-premises version is Basic Authentication still supported.

So, this means that OAuth2 is the only option for the SaaS version, and the option we'll discuss in this learning module.

OAuth2 is an open standard defined by the IETF OAuth Working Group. OAuth2 supports different authentication flows, and Business Central has support for 2:

  • Authorization Code Flow

  • Client Credentials Flow

With Authorization Code Flow, you need to sign in providing your Microsoft Entra ID login and password. It's the same login and password you use to sign in into the Business Central application. This is often the same login you use with Office 365/Microsoft 365 services. This way the application that connects to Business Central using OAuth2, will sign in with your credentials, and therefore act as if it was you that signed in. This also means that the application is using the same permissions that are assigned to your user account in Business Central. This flow doesn't require a separate license as it's running under the user's license.

A user will be prompted to enter his credentials, and therefore the user will see a sign-in dialog each time. This means that you can't use this flow for applications that don't have a user interface (examples: services running in the background or a web shop that needs to retrieve item information).

This flow is using permissions called delegated permissions within Microsoft Entra ID applications.

The Client Credentials Flow is the solution for services that need to run in the background. This flow only needs a client ID and a client secret, without a user that needs to sign in. Microsoft provides a special "application" license that you can use for these types of applications and is free. But you aren't allowed to use it for services that are related to a user (examples: time, registration).

This flow is using a permission called application permissions (Service-to-Service (S2S)) within Microsoft Entra ID applications.

To set up OAuth, you need to create an application within Microsoft Entra ID. Open the Microsoft Entra ID portal and sign in with your organizational account.

Once signed in, you can select Microsoft Entra ID from the services menu on the left. If you can't find this, then select the All services item to have an overview of all the Microsoft Entra ID services within the Portal and select Microsoft Entra ID there.

Screenshot of the Microsoft Entra ID center.

After you opened the Microsoft Entra ID item, you can need to select App registrations to create a new app.

Screenshot of App registrations selected.

Select the +New registration button, to start a new application registration. Provide a name that describes your application, select Accounts in this organizational directory only (CompanyName only - Single tenant) and select Web as the platform and https://businesscentral.dynamics.com/OAuthLanding.htm as the Redirect URI. Select Register to start the registration.

It's important that the redirect URI is exactly as described above, as this URI is case-sensitive.

Screenshot of the Register an application page.

Select Certificates & secrets in the menu and create a new Client Secret. You'll be asked to enter a description and an expiration date. This expiration date can only have a maximum of 24 months. So, this means that every 24 months (or earlier) you should create a new key.

Make sure to copy the value of the Client Secret, as this value won't be visible anymore once you leave this page.

The next step is to specify the API permissions. Select API permissions from the menu and select the + Add a permission button. Select Dynamics 365 Business Central from the list. This will now present you with two options (which we described above):

  • Delegated Permissions

  • Application Permissions

Select Delegated Permissions to create an application that signs in as a specific user. Once selected, you can select the Financials.ReadWrite.All option from the list and select Add permissions.

Screenshot of the Request API permissions page.

When working with OAuth2, you need some values to set up the authentication. Now it's time to gather all the values:

  • Client ID: You can find this value on the Overview page of your application. This is the Application (client) ID guid value.

  • Client Secret: Value you copied from the Certificates & secrets page

  • OAuth 2.0 authorization endpoint: Select the Endpoints button to open a pane where you can select this endpoint value.

  • OAuth 2.0 token endpoint: Select the Endpoints button to open a pane where you can select this endpoint value.

  • Scope: This is dependent on the type of OAuth2 flow you want to support. For Delegated Permissions, this is https://api.businesscentral.dynamics.com/Financials.ReadWrite.All, while for Application Permissions this is https://api.businesscentral.dynamics.com/.default.

Screenshot of the OAuth2 authentication values.

Now you're ready to use these values to set up an OAuth2 authentication.