SMART External File Storage - On-Premises Connector

The SMART External File Storage - On-Premises Connector extension for Microsoft Dynamics 365 Business Central enables connectivity to on-premises file systems through a secure WebAPI service deployed in IIS. The extension provides a full range of file and directory operations on on-premises servers directly from Business Central through the unified API of the External File Storage Module.

Key Features

• Direct access to on-premises file systems through WebAPI service
• Secure OAuth 2.0 authentication with Microsoft Entra ID
• File access control through Windows account permissions
• Support for all standard file operations: create, read, upload, delete
• Directory management: create, browse contents, delete
• Integration with External File Storage module for unified access

Account Setup

To configure a connection to an on-premises file system, you need to create an account and deploy the WebAPI service.

Creating an Account

1. Click the button to open the Search function, enter External File Storage Accounts, and follow the corresponding link.
2. Click the Register new account action, and select SMART On-Premises File connector.
3. On the wizard page, fill in the required fields:

Connection Settings

Field	Description
Account Name	A unique name for the account to identify the connection in the system. Used for display in lists and selecting the account when working with files.
File Service Endpoint Url	The URL of the WebAPI service deployed on your IIS server. For example: https://yourserver/api/filehelper or http://fileserver.company.local:8080/api. This service must be accessible from Business Central and should be deployed using the package provided by the extension.
Base Folder	Initial directory on the server from which operations will be performed. All file paths will be relative to this directory. By default, the root directory ("/") is used. For example, if you specify "C:/Documents", all operations will be performed relative to the Documents folder. Access to this folder is controlled by the Windows account under which the IIS application pool runs.

Authentication Settings

Field	Description
Authorization	Authentication method used to connect to the WebAPI service: - (Empty) - No authentication required (not recommended for production) - OAuth 2.0 - Use Microsoft Entra ID authentication with client credentials flow. When selected, additional fields for tenant, client, audience, and secret become available.
Tenant	Microsoft Entra tenant ID (also known as Directory ID) where your app registration is created. You can find this in the Azure portal under Microsoft Entra ID > Overview. Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Required when using OAuth 2.0 authentication.
Client Id	Client ID (also known as Application ID) from your app registration in Microsoft Entra ID. You can find this in the Azure portal under App registrations > [Your app] > Overview. Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. This identifies your Business Central instance to the WebAPI service. Required when using OAuth 2.0 authentication.
Audience	The audience (scope) URL for the OAuth 2.0 token request. This should match the API identifier (Application ID URI) configured in your app registration. For example: api://filehelper or https://company.onmicrosoft.com/filehelper. The WebAPI service validates incoming tokens against this audience value. Required when using OAuth 2.0 authentication.
Client Secret	Client secret value from your app registration in Microsoft Entra ID. This is a password-like credential used to authenticate Business Central to the WebAPI service. You can generate this secret in the Azure portal under App registrations > [Your app] > Certificates & secrets > New client secret. The secret is stored securely in Business Central's isolated storage and displayed as "********" after saving. Required when using OAuth 2.0 authentication.

Other Parameters

Field	Description
Disabled	Indicator showing whether the account is disabled. If set, the account cannot be used for file operations. This field is automatically set when creating a sandbox environment to prevent unwanted operations with production servers.

Deploying the WebAPI Service to IIS

The On-Premises Connector requires a WebAPI service to be deployed on an IIS server with access to your file system. The service acts as a secure bridge between Business Central and the file system.

Deployment Process

1. On the On-Premises File Account wizard or card, click the Deploy to IIS button.
2. A download will start with the WebAPI service package (ZIP file).
3. Extract the ZIP file to a temporary location on your IIS server.
4. Deploy the service to IIS:
   • Open IIS Manager on your server
   • Create a new Application Pool (recommended) or use an existing one
   • Configure the Application Pool identity to run under a Windows account that has appropriate file system permissions
   • Create a new website or application pointing to the extracted service files
   • Ensure the website/application has the necessary bindings (HTTP/HTTPS)
   • Configure HTTPS certificate if using secure connections (recommended)

Important: Application Pool Identity

The Windows account under which the IIS Application Pool runs determines what files and folders Business Central can access. For example:

• To access C:\CompanyFiles\, the Application Pool identity account must have read/write permissions on this folder
• You can use a domain account, local account, or built-in account (not recommended for production)
• Follow the principle of least privilege: grant only the permissions needed for file operations

Configuring OAuth 2.0 Authentication

If you want to secure the WebAPI service with OAuth 2.0 authentication, you need to configure it in the appsettings.json file located in the service deployment folder.

Step 1: Create an App Registration in Microsoft Entra ID

1. Go to the Azure portal (https://portal.azure.com)
2. Navigate to Microsoft Entra ID > App registrations > New registration
3. Enter a name for your app (e.g., "BC File Service")
4. Select Accounts in this organizational directory only
5. Click Register
6. Note the following values from the Overview page:
   • Application (client) ID - this will be your Client ID
   • Directory (tenant) ID - this will be your Tenant ID

Step 2: Create a Client Secret

1. In your app registration, go to Certificates & secrets
2. Click New client secret
3. Enter a description and select expiration period
4. Click Add
5. Important: Copy the secret Value immediately - you won't be able to see it again
6. This value will be your Client Secret

Step 3: Configure API Permissions (Optional)

While not strictly required for the client credentials flow, you may want to set up API permissions depending on your organization's security requirements.

Step 4: Set the Application ID URI (Audience)

1. In your app registration, go to Expose an API
2. Click Set next to Application ID URI
3. Accept the default or enter a custom URI (e.g., api://filehelper or api://yourcompany.com/filehelper)
4. Click Save
5. This URI will be your Audience value

Step 5: Configure appsettings.json

Open the appsettings.json file in the WebAPI service folder and update the OAuthParams section:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "OAuthParams": {
    "Instance": "https://login.microsoftonline.com/",
    "Domain": "",
    "TenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "ClientId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

Field Descriptions:

• Instance: OAuth authority URL. Leave as https://login.microsoftonline.com/ for Microsoft Entra ID
• Domain: (Optional) Your organization's domain name. Can be left empty
• TenantId: The Directory (tenant) ID from your app registration
• ClientId: The Application (client) ID from your app registration. This is the API identifier that will validate tokens

Important Notes:

• After updating appsettings.json, restart the IIS application pool for changes to take effect
• The ClientId in appsettings.json identifies the API (the WebAPI service)
• The ClientId in Business Central account settings identifies the client (Business Central)
• The Audience in Business Central should match the Application ID URI you set in step 4
• These can be the same app registration or different ones, depending on your security architecture

Step 6: Configure Business Central Account

1. Return to Business Central and open the On-Premises File Account card
2. Set Authorization to OAuth 2.0
3. Fill in the following fields:
   • Tenant: Directory (tenant) ID from Azure portal
   • Client Id: Application (client) ID from your app registration (the one calling the API)
   • Audience: Application ID URI from step 4 (e.g., api://filehelper)
   • Client Secret: The secret value you copied in step 2

Usage

Basic File Operations

After configuring the On-Premises File account, it automatically integrates with the External File Storage module and becomes available for file operations:

• View directory contents - browse files and subdirectories on the on-premises server
• Download files - download files from the server to Business Central
• Upload files - upload files from Business Central to the server
• Delete files - delete files on the server
• Create directories - create new directories on the server
• Delete directories - delete empty directories
• Copy files - copy files to different locations on the same server
• Move files - move files to different locations on the same server

File Access Permissions

File access is controlled by the Windows account under which the IIS Application Pool runs:

• Read operations (view, download): Account needs Read permissions
• Write operations (upload, create): Account needs Write permissions
• Delete operations: Account needs Modify or Full Control permissions
• Directory operations: Account needs appropriate permissions on parent directories

Integration with External File Storage Module

After setup, the On-Premises Connector automatically registers with the External File Storage module, which enables:

• Use of a unified API for working with files regardless of storage type
• Centralized access management for file operations
• Single interface for working with different storage sources (on-premises, FTP, Azure Blob Storage, SharePoint, etc.)
• Standardized file operations across different Business Central modules
• Ability to easily change file storage location without changing business logic