Configuring Business Central Web Server instances

Note

Azure Active Directory is now Microsoft Entra ID. Learn more

Accessing Business Central from the Business Central Web client or App requires a Business Central Web Server instance on Internet Information Services (IIS). You create a Business Central Web Server instance for the Business Central Web Server two ways:

• Using the Business Central Setup to install the Business Central Web Server
• Running the New-NAVWebServerInstance cmdlet.

When you set up a web server instance, you're configuring the connection to the Business Central Server instance. The connection settings are saved in a configuration file for the web server instance.

About the configuration file

The configuration file for the web server instances is a .json file type called navsettings.json. The navsettings.json file is a JavaScript Object Notification file type that is similar to files that use the XML file format.

After installation, you can change the configuration by modifying the navsettings.json. There are two ways to modify this file: directly or using PowerShell.

Where to find the navsettings.json file

The navsettings.json file is in the physical path of the web server instance. By default, the path is C:\inetpub\wwwroot\[WebServerInstanceName] on the computer's hard drive.

[WebServerInstanceName] corresponds to the name (alias) of the web server instance in IIS, for example, C:\inetpub\wwwroot\BC210.

Modify the navsettings.json file directly

1. Open the navsettings.json in any text or code editor, such as Notepad or Visual Studio Code.

   Each setting is defined by a key-value pair.

   In the navsettings.json file, a setting has the format:

   "keyname": "keyvalue",
   

   The keyname is the name of the configuration setting and the keyvalue is the value.

   For example, the configuration setting that specifies the Windows credential type for authenticating users is:

   "ClientServicesCredentialType":  "Windows",
   

   Include values in double quotes.

2. Find the configuration settings that you want to change, and then change the values.

   Refer to the Settings section for a description of each setting.

3. When you're done making changes, save the file.

4. Restart the Business Central Web Server instance for the changes to take effect.

   For example, in IIS Manager, in the Connections pane, select website node for Business Central Web Server, and then in the Actions pane, choose Restart. Or, from your desktop, run iisreset.

Modify the navsettings.json file by using the Set-NAVWebServerInstanceConfiguration cmdlet

The PowerShell script module NAVWebClientManagement.psm1 includes the Set-NAVWebServerInstanceConfiguration cmdlet that enables you to configure a web server instance.

1. Depending on your installation, run the Dynamics NAV Development Shell or Windows PowerShell as an administrator.

   Learn more in Get started with the Business Central Web Server cmdlets.

2. For each setting that you want to change, at the command prompt, run the following command:

   Set-NAVWebServerInstanceConfiguration -WebServerInstance [MyBCWebServerInstance] -KeyName [Setting] -KeyValue [Value] -SiteDeploymentType [Type]
   

   Replace:

   • [MyBCWebServerInstance]with the name of the web server instance for the Business Central Web Server.

   • [Setting] with the name of the setting. Refer to the next section in this article.

   • [Value] with the new value of the setting.

   • [Type] with the site deployment type either SubSite or RootSite.

     Note

     Although -SiteDeploymentType isn't a required parameter, the PowerShell script module NAVWebClientManagement.psm1 is written such that the default value for SiteDeploymentType is SubSite. If SiteDeploymentType isn't provided, the cmdlet will only operate against subsites.

Settings in the navsettings.json

The navsettings.json has the following structure, where settings are included under one of two root elements: NAVWebSettings and ApplicationIdSettings:

{
  "NAVWebSettings": {
     "//ServerInstance":  "Name of the Business Central Server instance to connect to (for client) or listen on (for server).",
     "ServerInstance":  "BC150",
      [...more keys]
 },
  "ApplicationIdSettings": {
      "BlogLink": "https://myBCBlog.com",
      [...more keys]
  }
}

// indicates a comment that provides help for the setting, and has no effect on the Web Server instance.

The following table describes the settings that are available in the navsettings.json for each root element.

• If you don't see a setting in the file, it's because some settings aren't automatically included as a key in the file. For these settings, you can add the key manually.
• If you don't add the key, the default value of the setting is used.

Important

If modifying the file directly, place values in double quotes "".

NAVWebSettings element settings

Setting/KeyName	Description
AadApplicationId	Specifies the application (client) ID assigned to the registered application for Business Central in the Microsoft Entra tenant. This setting is only used for Microsoft Entra authentication in Business Central, version 20.0 and later. The value must match the value of the Valid Audiences setting on the Business Central Server. For more information, see Authenticating Business Central Users with Microsoft Entra ID
AadAuthorityUri	Specifies the URI of the Microsoft Entra ID authority used for Microsoft Entra authentication. This setting is only used for Microsoft Entra authentication in Business Central, version 20.0 and later. The value has the format https://login.microsoftonline.com/<AADTenentID>, where <AADTenentID> is the Microsoft Entra tenant ID. For more information, see Authenticating Business Central Users with Microsoft Entra ID
AllowedCrossFrameMessageAncestors	Specifies the host name of any web domain that is allowed to send messages to iframes hosting Business Central or parts of it. By default, the Business Central web server doesn't allow messages to be sent to the iframes, unless the website is hosted on the same web server. This condition can affect the browser printing functionality of the product. The value of this setting is a comma-separated list of host names (URIs). Wildcard names are accepted. For example: https://mysite.sharepoint.com, https://*.myportal.com.
AllowedFrameAncestors	Specifies the host name of any web sites in which the Business Central Web client or parts of are embedded. By default, the Business Central Web Server doesn't allow a website to display it inside an iframe unless the website is hosted on the same web server. This value of this setting is a comma-separated list of host names (URIs). Wildcard names are accepted. For example: https:mysite.sharepoint.com, https:*.myportal.com
AllowNtlm	Specifies whether NT LAN Manager (NTLM) fallback is permitted for authentication. To require Kerberos authentication, set this value to false. Values: true, false Default value: true
AuthenticateServer	Specifies whether enable service identity checks on the protocol between the web server and the Business Central Server instance. Values: true, false Default value: true
ClientServicesCredentialType	Specifies the authorization mechanism that is used to authenticate users who try to connect to the Business Central Web Server. For more information, see Authentication and User Credential Type. The credential type must match the credential type configured for the Business Central Server instance that the Business Central Web Server connects to. For information about how to set up the credential type on Business Central Server, see Configuring Business Central Server. Values: Windows, UserName, NavUserPassword, AccessControlService Default value: Windows
ClientServicesChunkSize	Sets the maximum size, in kilobytes, of a data chunk that is transmitted between Business Central Web Server and Business Central Server. Data transmitted between Business Central Web Server and Business Central Server is broken down into smaller units called chunks. It's then reassembled when it reaches its destination. Values: From 4 to 80. Default value: 28 APPLIES TO: Business Central 2022 release wave 1 (version 20) and earlier.
ClientServicesCompressionThreshold	Sets the threshold in memory consumption at which Business Central Web Server starts compressing data sets. This setting limits amount of consumed memory. The value is in kilobytes. Default value: 64
ClientServicesPort	Specifies the Transmission Control Protocol (TCP) port for the Business Central Server. The port is part of the Business Central Server's URL. Values: 1-65535 Default value: 7085 (7046 in version 20 and earlier)
ClientServicesProtectionLevel	Specifies the security services used to protect the data stream between the Business Central Web Server and Business Central Server. This value must match the value that is specified in the Business Central Server configuration file. For more information, see Configuring Business Central Server. Values: EncryptAndSign, Sign, None Default value: EncryptAndSign APPLIES TO: Business Central 2022 release wave 1 (version 20) and earlier.
DefaultRelativeHelpPath	Specifies the default Help article to open if no other context-sensitive link is specified. Default value: none
Designer	Specifies whether the in-client designer is enabled in the Business Central Web client. Set to true to enable designer. For more information, see Use Designer.
DnsIdentity	Specifies the subject name or common name of the service certificate for Business Central Server. This parameter is only relevant when security certificates are used on the Business Central Web Server and Business Central Server to protect communication. Note: You can find the subject name by opening the certificate in the Certificates snap-in for Microsoft Management Console (MMC). The MMC is available on the computer that's running Business Central Web Server or Business Central Server. For more information, see Authentication and User Credential Type. Value: The subject name of the certificate. Default value: none
GlobalEndPoints	Specifies the comma-separated list of global endpoints that are allowed to call this website. The values must include http scheme and fully qualified domain name (FQDN), such as https://businesscentral.microsoft.com. "GlobalEndPoints": "null,ms://businesscentral,ms://dynamicsnav" Default value: none
HelpServer	Specifies the name of the Business Central Help Server if the deployment uses Help Server. If the deployment uses an online library, remove this setting. Default value: none
HelpServerPort	Specifies the TCP port on the specified Business Central Help Server if the deployment uses Help Server. If the deployment uses an online library, remove this setting. Default value: none
LoadScriptsFromCdn	Specifies whether to load scripts from Content Distribution Networks (CDNs). This setting only applies to scripts that are available from a CDN, like jQuery. If set to false, scripts are loaded from the web server, which is useful in, for example, an intranet scenario where there's no internet access. Default value: true DISCONTINUED AFTER: Business Central Spring 2019
ManagementServicesPort	The listening TCP port for the Business Central management endpoint. Valid range: 1-65535 Default value: 7045
OfficeSuiteShellServiceClientTimeout	Defines the time Business Central waits for the Office Suite Shell Service to respond. Important: This setting is deprecated in Business Central, and it has no effect on the Web Server instance. Default value: 10
PersonalizationEnabled	Specifies whether personalization is enabled in the Business Central Web client. Set to true to enable personalization. For more information, see Managing Personalization.
ProductName	Specifies the full name of the application.
ProductNameShort	Specifies the short name of the application.
ProductNameMarketing	Specifies the marketing name of the application.
RequireSsl	Specifies whether Secure Sockets Layer (SSL) (https) is required. If the value is set to true, all cookies are marked with a \u0027secure\u0027 attribute. If SSL is enabled on the web server, you should set this setting to true. Values: true, false Default value: false
Server	Specifies the name of the computer that is running the Business Central Server. Default value: localhost
ServerInstance	Specifies the name of the Business Central Server instance that the Business Central Web Server connects to. Default value: BC210
ServerHttps	Specifies whether https is used over the connection to the Business Central Server instance. If the ClientServicesSSLEnabled setting of the Business Central Server is set to true then ServerHttps must also be set to true. For more information, see Using security certificates with Business Central on-premises. Default value: false
ServicePrincipalNameRequired	If this parameter is set to true, then the Business Central Web Server can only connect to a Business Central Server instance associated with a service principal name (SPN). If this parameter is set to false, then the Business Central Web Server attempts to connect to the configured Business Central Server service, even if the service isn't associated with a service principal name (SPN). For more information about SPNs, see Configure Delegation. Default: false
SessionTimeout	Specifies the maximum time that a connection between the Business Central Web Server and the Business Central Server can remain idle before the session is stopped. In the Business Central Web Server, this setting determines how long an open Business Central page or report can remain inactive before it closes. For example, suppose the SessionTimeout is set to 20 minutes. If a user doesn't take any action on a page within 20 minutes, then the page closes and the following message appears: The page has expired and the content cannot be displayed. The time span has the format [dd.]hh:mm:ss[.ff]: - dd is the number of days - hh is the number of hours - mm is the number of minutes - ss is the number of seconds - ff is fractions of a second Default value: 00:20:00
ShowPageSearch	Specifies whether to show the Tell me what you want to do icon in the Business Central header. This feature lets users find Business Central objects, such as pages, reports, and actions. If you don't want to show the Tell me what you want to do icon, then set the parameter to false. Default value: true
UnknownSpnHint	Specifies whether to use a server principal name when establishing the connection between the Business Central Web Server server and Business Central Server. This setting is used to authenticate the Business Central Server, and it prevents the Business Central Web Server server from restarting when it connects to Business Central Server for the first time. You set values that are based on the value of the ServicePrincipalNameRequired key. Value: The value has the following format. (net.tcp://BCServer:Port/ServerInstance/Service)=NoSpn|SPN - BCServer is the name of the computer that is running the Business Central Server. - Port is the port number on which the Business Central Server is running. - ServerInstance is the name of the Business Central Server instance. - NoSpn|SPN specifies whether to use an SPN. If the ServicePrincipalNameRequired key is set to false, then set this value to NoSpn. If the ServicePrincipalNameRequired key is set to true, then set this value to Spn. Default value: (net.tcp://localhost:7046/BC210/Service)=NoSpn If you set this key to the incorrect value, then during startup, the Business Central Web Server automatically determines a correct value. An incorrect value causes the Business Central Web Server to restart. Note: For most installations, you don't have to change this value. Unlike the Dynamics NAV Client connected to Business Central, this setting isn't updated automatically. If you want to change the default value, then you must change it manually. APPLIES TO: Business Central 2022 release wave 1 (version 20) and earlier.
UseAdditionalSearchTerms	Specifies whether Tell me uses the other search terms that are defined on pages and reports. The other search terms are specified by the AdditionalSearchTerms and AdditionalSearchTermsML properties. If you set this key name to false, the other search terms are ignored. Default value: true
SaveValueToDatabasePromptly	If set to true, changes to values in fields are saved to the database as soon as the user moves focus from the field, for example, by selecting Tab. false is the default value. If set to false, changes aren't saved until the user closes the page by using the back arrow or stops editing by choosing the edit (pencil) button. After a user makes changes to a field and moves focus to the next field, the status in the upper-right corner of the page changes to Saving and then to Saved. This behavior can be misleading because the changes aren't yet saved to the database at this time.

ApplicationIdSettings element settings

Setting/KeyName	Description
BaseHelpUrl	Specifies the link to the online Help library that the deployment uses, such as https://mysite.com/{0}/mylibrary/. Default value: none For more information, see Configuring the Help Experience.
BlogLink	Specifies the target of the blog link on the Help & Support page. Use this link to give users access to your end-user blog. Value: a valid URL Default value: https://go.microsoft.com/fwlink/?linkid=2076643|
ComingSoonLink	Specifies the target of coming soon link on the Help & Support page. Use this link to give users access to information about your roadmap or any upcoming features and fixes. Value: A valid URL. Default value: https://go.microsoft.com/fwlink/?linkid=2047422
CommunityLink	Specifies the URL to a community or resource for sharing information. Value: a valid URL Default value: https://go.microsoft.com/fwlink/?LinkId=287089|
ContactSalesLink	Specifies the target of the contact sales link on the Help & Support page. Use this link to give users access to your sales-focused web page where users can engage with your sales process. Note: This setting and link aren't used for Business Central on-premises.
SigninHelpLink	Specifies the URL to open if the user selects help on the sign-in page box. Value: a valid URL Default value: none

Related information

Setting up Multiple Business Central Web Server Instances
Install Business Central Components
Business Central Web Server Overview
Configuring Business Central Server
Configuring the Help Experience