OAuth v2.0 Authentication on Cloud Installations

OAuth v2.0 Authentication on Cloud Installations

With Business Central 23.0, Microsoft discontinued basic authentication in cloud installations. Profiles can now be configured to use OAuth v2.0 authentication instead.

To use OAuth, you need to accomplish two configurations:

  1. Register Qucamba as an allowed client application.

  2. Create a new Microsoft Entra Application in Business Central that maps a user to the client application and grants access to Business Central data.

  3. Configure your Qucamba Reports profile.

The following sections describe these configuration steps in detail.

Registering a new client application

Before you can use OAuth v2.0 authentication, you need to register a new client application on your Microsoft Azure tenant. To create and register a new client application follow these steps:

  1. Open your web browser and go to: https://portal.azure.com/#home.

  2. In the search bar, type “App registrations” and open the app registrations page.

  3. In the “App registrations” page, click “New registration”.

  4. In the “Register new application” page, enter a name and select “Accounts in this organizational directory only”. Then, click “Register”. In the top right corner you can now examine the progress of creation.

  5. After your app registration is completed, open the app registration and in the left pane, select “Authentication” from the “Manage” section. Here, click “Add a platform”.

  1. In the platform configuration, select “Web” from the “Web applications” section and enter a redirection URL, such as: https://businesscentral.dynamics.com/OAuthLanding.htm

  2. From the “Manage” section in the left pane of your app registration page, select “API permissions” and click “Add a permission”. Then, in the “Request API permissions” window, select “Dynamics 365 Business Central” and select “Delegated permissions”. Here, select the permissions required.

  1. Repeat the previous step for “Application permissions”.

  2. Back to the “API permissions” page, click the action “Grant admin consent for…” in the action bar above your permissions and confirm your grant request.

  3. Finally, from the “Manage” section in the left pane of your app registration page, select “Certificates & secrets”. Click “New client secret”, enter a description and an expiration date and click “Add”. Copy the value from the column “Value” of your “Client secret”.

From the overview page of your app registration, you can now collect all information to authenticate using OAuth v2.0:

  1. Directory (tenant) ID

  2. Application (client) ID

  3. Certificates & secrets page > Value

Creating a new Microsoft Entra application in Business Central

By creating a new Microsoft Entra Application in Business Central, you connect a Business Central user to the client application that you registered in the previous section.

Business Central will create the Business Central user automatically. All you need to do, is create a new Microsoft Entra Application and assign the appropriate permission sets.

  1. Open your Business Central and in the Tell-me box (Alt+Q), search for “Microsoft Entra Applications”.

  2. Create a new record, enter a description, and set the state to Enabled. Business Central will create a new user accordingly.

  3. In the list part below, add the permissionsets required to access your Business Central installation, such as “D365 BUS PREMIUM”, “D365 FULL ACCESS”, “D365 FINANCE” etc.

  4. Finally, click “Grant Consent”.

You are now ready to use OAuth v2 authentication with Qucamba Reports.

Configuring a Qucamba Reports profile to use OAuth

To use OAuth authentication, edit your profile settings and in the “Qucamba Service” section, select the appropriate service endpoint type as either “Cloud (Sandbox environment)” or “Cloud (Production environment)”. Then, set the authentication type to “OAuth 2.0”.

Enter your Tenant ID, the Client ID and the Client Secret. For the field mapping between the Azure portal’s fields and the Qucamba Reports profile fields see the table below.

App registration Qucamba profile field
Directory (tenant) ID Tenant ID
Application (client) ID Client ID
Certificates & secrets page > Value Client Secret

Finally, click “Test Service” to check if Qucamba Reports can connect to your Business Central instance.

Note. To gain full access to the API-URL, you may also set the service endpoint type to “Custom” and enter the entire URL directly. However, OAuth authentication is supported on Microsoft Azure only. It cannot be used in On-premises installations.

Use the “Test service” button or link to test if a connection can be established successful.

Finally, click OK and connect to your profile.

Troubleshooting OAuth authentication

When configuring the profile, please make sure to use the correct host address as well as the correct port no. The port no. must refer to an OData port. Also, make sure to enable OData services in your service tier configuration.

Use the “Test service” button or link in the profile configuration to test if a connection can be established successful. In case authorization fails, make sure to specify the correct tenant id, client id and client secret. Examine the table above to find the exact names of the fields. Pay special attention to the client secret which must be taken from the “Value” column of the Azure portal “Certificates & secrets” page.

Also, try to select the “Company Name” again from the list even if it appears to be the same value.