Set up the add-ins for Outlook in Business Central on-premises

APPLIES TO: Business Central on-premises. For Business Central online, learn more in Get the add-in for Outlook

If your organization uses Exchange Server or Exchange Online (alone or as part of a Microsoft 365 subscription), Business Central on-premises supports integration with Outlook that enables users to complete Business Central business tasks from their Outlook inbox. As the admin, you can configure Business Central so that users can connect to Business Central data from Outlook.

Important

From February 1, 2025, Microsoft Exchange Online requires all Outlook add-ins to use Nested App Authentication (NAA). If you have an existing setup for the Outlook add-in, you have to modify it to ensure it continues to work. Learn more in Modify existing Outlook add-in setup to support Nested App Authentication (NAA).

Overview

About the add-in

Business Central add-in for Outlook consists of two add-ins:

• Contact Insights

  The add-in provides users with Business Central customer or vendor information in Outlook emails and calendar appointments. It also enables users to create and send Business Central business documents, such sales quotes and invoices to a contact. To support these tasks, the add-in adds actions to the Outlook ribbon, in the Business Central group.

• Document View

  When a business document is sent as an email, this add-in provides a direct link from email to the actual business document in Business Central.

Each add-in is provided as an XML manifest file, which must be installed in Outlook client of any user that wants this functionality. These files describe how to activate the add-ins and connect to Business Central when they're used in Outlook.

Learn more about using the add-ins in Using Business Central as your Business Inbox in Outlook.

About deployment

There are different options for deploying the add-ins. The option you choose depends on your organization's security policies, the Business Central environment, and how much control over installing the add-in you want to give users. For example, you can install the add-ins automatically for all users in your organization or targeted users only. Or, you can allow users to install the add-ins themselves. Learn more in the following sections of this article:

• Centralized Deployment
• Automated Individual Deployment
• Manual Individual Deployment

Important

Working with multiple environments? The Business Central add-in for Outlook works with a single Business Central environment. When installed, the environment name is included in the add-in's manifest. With this configuration, the add-in only connects to the environment it was installed from. To use the add-in with a different environment, open the environment and install the add-in again.

Mail server

The add-in deployment works with Exchange Online, Exchange Online as part of Microsoft 365, and Exchange Server 2019. The add-in uses Exchange Web Services (EWS) to access mailbox data from Exchange Server, while Microsoft Entra Identity Provider and Microsoft Graph are used to access data from Exchange Online.

Authentication and authorization

The authentication and authorization that can be used depends on whether you're using Exchange Online or Exchange Server.

Exchange Online

To use Exchange Online, configure Business Central to use Microsoft Entra authentication. Learn more in Configure Microsoft Entra authentication with OpenID Connect.

The Business Central add-in uses NAA (Nested App Authentication) for secure single sign-on with Outlook and Microsoft Entra ID accounts. It also supports multifactor authentication if configured in Microsoft 365.

Exchange Server

With Exchange Server, EWS and Autodiscover try to find the local Exchange Server. Business Central can be configured to use either NavUserPassword or Microsoft Entra authentication.

Note

Azure Active Directory is now Microsoft Entra ID. Learn more

Prepare for deployment

The steps to prepare for deploying the add-in depend on whether you plan to deploy to Exchange Online or Exchange Server.

Deploying to Exchange Online

1. Prepare Microsoft 365

   • Assign users a Microsoft 365 license.
   • Make sure your Microsoft 365 account has at least the Exchange Administrator role.

2. Set up Business Central for Microsoft Entra authentication.

   Learn more in Configure Microsoft Entra authentication with OpenID Connect.

   In the app registration, expose the Business Central API with a scope requiring admin and user consent:

   1. Sign in to Microsoft Entra admin center and open the app registration.

   2. Select Expose an API.

   3. If there's no value for Application ID URI, select Add > Save. Make note of the Application ID URI for later.

   4. On the Expose an API page, select Add a scope and configure these settings:

      Setting	Value	Example
      Scope name	Specify a meaningful name for a permission scope.	BusinessCentralOnPrem.Access
      Consent	Choose Admins and users.
      Admin consent display name	Specify a meaningful name for admin consent.	Access Business Central as the signed-in user
      Admin consent description	Specify a meaningful description.	Business Central is a business management solution that helps organizations work smarter, adapt faster, and perform better.
      User consent display name	Specify a meaningful name for user consent.	Have full access to Business Central
      User consent description	Specify a meaningful description.	Allow the application full access to Dynamics 365 on your behalf.

   5. Make a note of the scope's name on the Expose an API page and app registration's display name on the Overview page. You might need this information later.

   Learn more in Configure an application to expose a web API.

3. Configure Business Central Web Server to use SSL (https).

   Learn more in Configure SSL to secure the connection to web client.

4. Configure the Business Central Server instance to work with the Office Add-ins.

   Learn more in Configure the server instance to work with the add-ins.

5. Register an application in Microsoft Entra ID for connecting Outlook and Business Central

   Learn more in Register an app that connects Outlook and Business Central.

6. Configure the Business Central web server instance to work with Exchange Online

   Learn more in Configure the Business Central web server instance to work with Exchange Online.

7. Set the authentication email on user accounts to the user's Microsoft 365 email address.

   Learn more in Create Users According to Licenses in the business functionality help.

Deploying to Exchange Server

1. Prepare Exchange Server

   • Enable access to EWS. Learn more in Control access to EWS in Exchange
   • Make sure your Exchange account has the Organization Management role or the Org Apps admin role

2. Set up Business Central for Microsoft Entra authentication or NavUserPassword.

   Learn more in Authenticating users with Microsoft Entra ID or Authenticating users with NavUserPassword

3. Configure Business Central Web Server to use SSL (https).

   Learn more in Configure SSL to Secure the Connection to Web Client.

4. Configure the Business Central Server instance to work with the Office Add-ins.

   Learn more in Configure the server instance to work with the Office Add-ins

5. (optional) Register an application in Microsoft Entra ID for connecting Outlook and Business Central

   This step only applies when using Microsoft Entra authentication. Learn more in Register an app that connects Outlook and Business Central

Register an app that connects Outlook and Business Central

APPLIES TO: Connecting to Exchange Online and Exchange Server

1. Sign in to the Microsoft Entra admin center.

2. Create a new app registration on your tenant with the following settings:

   Setting	Value	Example
   Name	Specify a meaningful name for the app	Business Central on-premises Outlook Add-in Connector
   Supported account types	Use the default or select Accounts in any organizational directory (Any Microsoft Entra ID directory - Multitenant)
   Redirect URI - Select a platform box	Single-Page application (SPA)
   Redirect URI - URI box	Enter the base URL for your Business Central on-premises web client. For Exchange Online, the URL has the format: brk-multihub://<web server hostname> For Exchange Server, the URL has the format: https://<web server hostname>	Exchange Online: brk-multihub://MyBCWebServer Exchange Server: https://MyBCWebServer

   Learn more in Register an application in Microsoft Entra ID.

3. Add the following API permissions the new registered app.

   With the new registered app open, select API permissions > Add a permission. The required permissions are different for connecting to Exchange Online and Exchange Server:

   Permissions for Exchange Online

   • In the Microsoft APIs tab, select Microsoft Graph, and Delegated permissions. From the list of available permissions, select User.Read and Mail.ReadWrite.

   • In the APIs my organization uses tab, search for the name of the registered app that authenticates Microsoft Entra ID users with Business Central and add the scope you created earlier. This app isn't the app you registered to connect Outlook and Business Central.

   Select Add permissions to save the changes.

   Permissions for Exchange Server

   In the Microsoft APIs tab, select Microsoft Graph > Delegated permissions. From the list of available permissions, select EWS.AccessAsUser.All. Select Add permissions to save changes.

---

Learn more in Add permissions to access web APIs.

Configure the Business Central server instance to work with add-ins

APPLIES TO: Connecting to Exchange Online and Exchange Server

For this task, use the Set-NAVServerConfiguration cmdlet cmdlet in the Business Central Administration Shell.

1. Start the Business Central Administration Shell as an administrator.

2. Run the Set-NAVServerConfiguration cmdlet to set the PublicWebBaseUrl key to the base URL of the Business Central Web client.

   The base URL is the public URL that Outlook clients use to access Business Central. The base URL is the root portion of all URLs that are used to access pages in the web client. It must have the format https://[hostname:port]/[instance], such as https://MyBCWebServer:443/BC252.

   Set-NavServerConfiguration -ServerInstance BC252 -KeyName PublicWebBaseUrl -Keyvalue "https://MyBCWebServer:443/BC252"
   

3. Run the Set-NAVServerConfiguration cmdlet to set the ValidAudiences key to the host name of the Business Central Web client. The value is the web client base URL without the port number and server instance, like https://MyBCWebServer.

   Set-NavServerConfiguration -ServerInstance BC252 -KeyName ValidAudiences -Keyvalue "https://MyBCWebServer"
   

   If you have a multitenant deployment with different host names for tenants, like https://tenant1.cronusinternational.com, register each host name as a valid audience. You can do this task in two ways:

   • On the server-level, use the Set-NavServerConfiguration cmdlet to add each host name to Valid Audiences setting of the Business Central Server instance. separate each host name with a semi-colon.

     Set-NavServerConfiguration -ServerInstance BC -KeyName ValidAudiences -Keyvalue "<host name 1>;<host name 1>"
     

   • On the tenant-level, add the host names to the Valid Audiences setting when you mount the tenant by using the Mount-NAVTenant cmdlet.

     Mount-NavTenant -ServerInstance <BC server instance> -Tenant <tenant_ID> -ValidAudiences "<host name 1>"
     

   Note

   If there's more than one host name, separate each host name with a semicolon. Specify the host names at the server level, tenant level, or both.

4. (Optional) Run the Set-NAVServerConfiguration cmdlet to set the ExchangeAuthenticationMetadataLocation key.

   Set-NavServerConfiguration -ServerInstance <BC server instance> -KeyName ExchangeAuthenticationMetadataLocation -Keyvalue <metadata document URL>
   

   This setting is used to confirm the identity of the signing authority when using Exchange authentication. In part, the value includes the URL of the Exchange mail server. The field accepts a wild-card URL. So for example, if the URL of the Exchange mail server is https://mail.cronus.com, then you can set the field to https://mail.cronus.com*. The default value is https://outlook.office365.com/. Complete this step only if you want to use a value other than the default.

Configure the Business Central web server instance to work with Exchange Online

APPLIES TO: Connecting to Exchange Online

This task is only required when working with Exchange Online. To complete this task, you need the application (client) ID of the registered application used for Business Central authentication in Microsoft Entra.

Use the Set-NAVWebServerInstanceConfiguration in the Business Central Administration Shell to configure the following web server instance settings:

KeyName	KeyValue	Example
ExchangeOnlineAppId	Use the Application (client) ID for the application you registered that connects Outlook and Business Central.	00001111-aaaa-2222-bbbb-3333cccc4444
ExchangeOnlineAppScope	Use the Scope from the application you registered that authenticates Microsoft Entra ID users with Business Central. The value has the format: <BC OnPrem app ID>/<scope>	11112222-bbbb-3333-cccc-4444dddd5555/BusinessCentralOnPrem.Access

Run the cmdlet for each setting using the following syntax:

Set-NAVWebServerInstanceConfiguration -ServerInstance <BC server instance> -Tenant <tenant_ID> -KeyName <KeyName> -KeyValue <KeyValue> 

For example:

Set-NAVWebServerInstanceConfiguration -ServerInstance BC252 -Tenant default -KeyName ExchangeOnlineAppId -KeyValue "00001111-aaaa-2222-bbbb-3333cccc4444" 
Set-NAVWebServerInstanceConfiguration -ServerInstance BC252 -Tenant default -KeyName ExchangeOnlineAppScope -KeyValue "11112222-bbbb-3333-cccc-4444dddd5555/BusinessCentralOnPrem.Access" 

Restart the web server instance when you're done.

iireset

Centralized Deployment

Centralized Deployment is a feature in Microsoft 365 admin center and Exchange admin center that lets you automatically install add-ins in users' Office apps, like Outlook. It's the recommended way for admins to deploy for Office add-ins to users and groups within your organization. Learn more in Centralized Deployment FAQ.

Complete the following steps:

1. Verify that Centralized Deployment works for your organization.

   Learn more in Determine if Centralized Deployment of add-ins works for your organization.

2. In Business Central, choose the icon, enter Assisted Setup, and then choose the related link.

3. Choose Outlook Add-in Centralized Deployment > Next.

4. In the Deploy column, select the check box for the add-ins that you want to deploy, then choose Download and Continue.

   A file named OutlookAddins.zip is downloaded to your device.

5. On the Where do you want to deploy to? page, set Deploy Add-in to to either Microsoft 365 or Exchange Server, then choose Next.

6. At this point, you're finished with the work you need to do in Business Central, so you can choose Done.

   Tip

   Before you choose Next, select the Go to Microsoft 365 (opens in a new window) or Learn more about the add-in for Outlook in Exchange Server link to open or get help on the admin center.

7. Go the folder where the OutlookAddins.zip file was downloaded, and extract the Content Insights.xml and Document View.xml files from the .zip to a folder of your choice.

   Learn more in Zip and Unzip files and folders.

8. For Microsoft 365 deployment, sign in to the Microsoft 365 admin center. For Exchange Server deployment, sign in to Exchange admin center.

9. Upload the add-in files as custom add-ins in the admin center you're working with:

   • For Microsoft 365 admin center, follow the steps at Deploy add-ins in the admin center.
   • For Exchange admin center, follow the steps at Install or remove add-ins for Outlook for your Exchange organization.

   This step assigns users and deploys the add-ins.

Important

An add-in can take up to 24 hours before users see the add-in in Outlook app.

After you finish, you can always change the deployment in admin center, like assigning more users.

Automated individual deployment

With this deployment option, users install the Business Central add-in for Outlook themselves. This option uses a registered application in Microsoft Entra ID with Exchange web service permission, so users don't have to upload the add-ins manually in Outlook. Users don't have to sign in to Business Central to use the add-ins, because authentication against Exchange or Microsoft 365 is done using an authentication token.

If you prepared for deployment as described earlier, as an admin, the only remaining task is to set up an application registration in Microsoft Entra ID. Then, users can install the add-in in Outlook.

Register an application in Microsoft Entra ID

In the Azure portal, add an application registration for Business Central in your Microsoft Entra tenant. Give the registered app delegated permission to Exchange web service (EWS). After you add the registered app in Microsoft Entra ID, set up Business Central to use it by using the Set up your Microsoft Entra accounts assisted setup.

Learn more in Registering Business Central on-premises in Microsoft Entra ID.

Get the add-in (users)

After you complete the Business Central setup, users deploy the add-in by using Get Outlook Add-in assisted setup in Business Central. Learn more in Install the Business Central Add-in for Outlook.

Manual individual deployment

With this deployment option, users install the Business Central add-in for Outlook for themselves only. Unlike the individual acquisition (automated) deployment option, users have to download the add-in files from Business Central, then manually add them in Outlook. If you prepared your deployment as described earlier, the only step remaining is for users to get the add-in.

Get the add-in (users)

After you complete the Business Central setup, users deploy the add-in by using Get Outlook Add-in assisted setup in Business Central. Learn more in Install the Business Central Add-in for Outlook.

Related information

Deploying Business Central
Using Business Central as your Business Inbox in Outlook
Mount or Dismount a Tenant
Configuring Business Central Web Server to Accept Host Names for Tenants
FAQ