Set up and test OAuth2

tip

This guide is a continuation of the connector setup in Dime.Scheduler and its implementation in Business Central.

The purpose of this guide is to offer partners and customers a way to safely set up a testing environment of BC with OAuth2 enabled so it use this authentication and authorization flows with Dime.Scheduler. We'll break down this guide in four parts:

Prerequisites

• Docker

  We wrote this article by using Business Central on Docker (see here for a dedicated guide to start a new instance). While it is an absolute joy to run an entire ERP system on a Docker container, there are some challenges that need to be addressed. We'll be making references to those throughout this guide.

  Feel free to use your own internal testing environment.

• ngrok

  As we're running Business Central on Docker on our local machine, we need a way to expose our BC instance to Dime.Scheduler, which runs in the cloud. For that, we're going to use a popular tunneling solution named ngrok. ngrok's free tier gives you one static domain.

  If you have DNS all set up, there's no need to use ngrok.

• Extension for Dime.Scheduler in Business Central

  The extension for Dime.Scheduler in Business Central must be installed prior to registering the MS Entra ID app in Business Central.

Step 1: Create an MS Entra ID app on Azure

Create an MS Entra ID app on Azure with the following specifications:

• Name: Dime.Scheduler for MS Dynamics 365 Business Central
• Redirect URI: https://{PublicWebBaseURL}/{INSTANCENAME}/OAuthLanding.htm
• Permissions for Microsoft Dynamics 365 Business Central:
  • API.ReadWrite.All
  • app_access
• Create a client secret and copy its value along with the client id and tenant id. We'll be using this information in the next steps.

BC on Docker

The redirect URI must be accessible by Microsoft to complete the app registration consent. BC on your local Docker Desktop with an address like 'http://bc25/BC' is invalid (no SSL) and inaccessible (local). Hence, for the purposes of this guide we should create a tunnel using ngrok for the web client for just this one time.

For example, this command fires up a static domain (use your own) and forwards it to our local BC25 on Docker:

ngrok http --domain=sleeping-dolphin.ngrok-free.app http://bc25 

ngrok will return a bunch of fascinating information, but what we're after is displayed in the 'Forwarding' field. It will show you that (as long as you keep your terminal open) it will be forwarding requests from https://sleeping-dolphin.ngrok-free.app to http://bc25:80.

Use your own free static domain that is assigned to your account on ngrok, and use the following template https://yourstaticngrokdomain.ngrok-free.app/{INSTANCENAME}/OAuthLanding.htm to populate the redirect URI field in the app registration.

Step 2: Register the MS Entra ID app in Business Central

In BC, we must create a duplicate record of the MS Entra ID app that we just created:

• Client ID: paste the client ID of the MS Entra ID app that you just created
• Description: Dime.Scheduler
• State: enabled

Select the following user permission sets:

• DIME DS ADMIN
• D365 BASIC ISV

Hit 'Grant Consent' and approve the consent modal window.

BC on Docker

When running BC on Docker, you should grant consent on the same domain that you specified in the redirect URI in the MS Entra ID app.

Instead of granting consent on 'http://bc25/BC', you must open the same page on 'https://yourstaticngrokdomain.ngrok-free.app/bc'. Failure to do so will result in an error, indicating that the 'http://bc25/BC' URI is not available in the redirect URI list.

Step 3: Enable S2S authentication using OAuth2 in BC

For on-prem instances of BC, a little bit of tweaking is necessary to enable server-to-server (S2S) authentication. Consult the official documentation for more information.

warning

The contents of step are opinionated and are merely illustrative to get a working solution. Proceed with caution if you're not using a Docker container.

Below is a little PowerShell script that you can run in the BC PowerShell Prompt. We based our script on this blog post and updated it to work for Business Central 25. Change the values in the variables and run the script in the BC administration shell:

# Provide some basic info about your BC environment:
$BcBaseUrl = 'https://your_url_to_bc/'
$BCServerInstanceName = 'your_bc_instance'

# Provide the info about the MS Entra ID app that you created on Azure:

# 1. Application (client) ID
$ClientId = 'your_ms_entra_id_app_client_id'

# 2. Directory (tenant) ID
$TenantId = 'your_azure_tenant_id' 

# 3. Application ID URI
$AppIdUri = 'your_ms_entra_id_app_id_uri' 

# ---------------------------------------------
# NO MORE VARIABLES TO MODIFY BEYOND THIS POINT
# ---------------------------------------------

# Configuration for the WSFederationLoginEndpoint
$BCServerInstanceUrl = $BcBaseUrl + $BCServerInstanceName 
$LandingUrl = $BCServerInstanceUrl + "/OAuthLanding.htm"
$WSFedEndpoint = "https://login.microsoftonline.com/$TenantId/wsfed?wa=wsignin1.0&wtrealm=$AppIdUri&wreply=$LandingUrl"

# Configure BC Server
$BCConfig = @{
    "PublicWebBaseURL"               = $BCServerInstanceUrl
    "ValidAudiences"                 = "$ClientId;https://api.businesscentral.dynamics.com"
    "ADOpenIdMetadataLocation"       = "https://login.microsoftonline.com/$TenantId/.well-known/openid-configuration"
    "ClientServicesCredentialType"   = "NavUserPassword"
    "WSFederationLoginEndpoint"      = $WSFedEndpoint
}

foreach ($key in $BCConfig.Keys) {
    Set-NAVServerConfiguration -ServerInstance $BCServerInstanceName -KeyName $key -KeyValue $BCConfig[$key]
}

# Configure web server
$WebConfig = @{
    "AadApplicationId" = $ClientId
    "AadAuthorityUri"  = "https://login.microsoftonline.com/$TenantId"
}

foreach ($key in $WebConfig.Keys) {
    Set-NAVWebServerInstanceConfiguration -WebServerInstance $BCServerInstanceName -KeyName $key -KeyValue $WebConfig[$key]
}

Restart-NAVServerInstance -ServerInstance $BCServerInstanceName

With this configuration all done, BC now supports S2S authentication.

Step 4: Create a connector entry in Dime.Scheduler

note

This step is standard Dime.Scheduler functionality, and is documented here.

The only remaining task is to create a connector in Dime.Scheduler. In the Authentication section of the form, fill out the following fields:

Field	Value	How to find it in MS Entra ID
Authentication type	MS Entra ID
Tenant ID	The Azure tenant ID	Field Directory (tenant) ID in the overview page of the app registration.
Client ID	The app registration's client ID	Field Application (client) ID in the overview page of the app registration.
Client Secret	The app registration's client secret	Create a secret in the 'Certificates and secrets' blade. Copy the secret Value field, not the client secret ID!

Save the record and you have successfully set up the connector for Microsoft Dynamics 365 Business Central using OAuth2.

Don't forget to match the source app with the configuration in BC. The source app must be the same as the value that's specified in the Dime.Scheduler FastTrack Wizard in Business Central. The source app identifies which back-office system resources, tasks and appointments belong to.

Dime.Scheduler and Business Central are now able to communicate back and forth securely with OAuth2.

BC on Docker

To test whether the OAuth2 authentication flow works, you must now create a tunnel for the API (not the web client) if you're running BC locally on Docker.

For example, this command fires up a static domain (use your own) and forwards it to our local BC25's API port on Docker:

ngrok http --domain=sleeping-dolphin.ngrok-free.app http://bc25:7048

Note how this time we target port 7048 rather than port 80. As a result, the API pages of Dime.Scheduler in BC will now be available publicly on https://YOURTUNNEL/BC/api/dimeSoftware/dimeScheduler/v1.0/companies(YOURCOMPANYID)/appointments.