Edit

Share via

Using security certificates with Business Central on-premises

  • Article

You use certificates to help secure connections over a wide area network (WAN), such as connections from the Business Central Web Server, Dynamics NAV Client connected to Business Central, and web services to the Business Central Server. Implementing security certificates on your deployment environment requires modifications to various components, like the Business Central Server, Business Central Web Server, and clients.

About security certificates

A certificate is a file that Business Central Server uses to prove its identity and establish a trusted connection with the client that is trying to connect. Business Central can support the following configurations:

  • Chain trust, which specifies that each certificate must belong to a hierarchy of certificates that ends in a root authority at the top of the chain.
  • Peer trust, which specifies that both self-issued certificates and certificates in a trusted chain are accepted.

The implementation in this section describes the chain trust configuration, which is the more secure option.

Note

An instance of Business Central Server that has been configured for secure WAN communication always prompts users for authentication when they start the client, even when the client computer is in the same domain as Business Central Server.

Certificates for production

In a production environment, you should obtain a certificate from a certification authority or trusted provider. Some large organizations may have their own certification authorities, and other organizations can request a certificate from a third-party organization.

Obtaining certificates

You implement chain trust by obtaining X.509 service certificates from a trusted provider. These certificates and their root certification authority (CA) certificates must be installed in the certificates store on the computer that is running Business Central Server. The CA certificate must also be installed in the certificate store on computers that are running the Business Central Web Server so that clients can validate the server.

Most enterprises and hosting providers have their own infrastructure for issuing and managing certificates. You can also use these certificate infrastructures. The only requirement is that the service certificates must be set up for key exchange and therefore must contain both private and public keys. Additionally, the service certificates that are installed on Business Central Server instances must have the Service Authentication and Client Authentication certificate purposes enabled.

Important

Microsoft recommends against using wildcard SSL certificates in Business Central installations. Wildcard certificates pose security risks because if one server or sub-domain is compromised, all sub-domains may be compromised. Wildcard certificates also introduce a new style of impersonation attack. In this attack, the victim is lured to a fraudulent resource in the certified domain through phishing. Conventional certificates detect this attack, because the user’s browser checks that the private key is hosted on a server whose name matches the one displayed in the browser’s address window.

Run the certificates snap-in for Microsoft Management Console

Some of the following procedures use the Certificates snap-in for Microsoft Management Console (MMC). If you do not already have this snap-in installed, you can add it to the MMC. For information see Add the Certificates Snap-in to an MMC.

Install and configure the certificates

You install the security certificates on the computers running Business Central Server, Business Central Web Server, and Dynamics NAV Client connected to Business Central. The root CA certificate and the service certificate are used in the configuration, but client certificates are not.

Install certificates on components

  1. Follow the installation instructions that are available from your certificate provider to install the root CA and service certificates on the following computers:

    • Install the root CA on the computer that is running Business Central Server and all computers that are running Business Central Web Server instances and Dynamics NAV Client connected to Business Central.
    • Install the service certificate on the computer that is running Business Central Server only.

  2. Make sure that the Server Authentication and Client Authentication certificate purposes are enabled for the service certificate.

    A certificate can be enabled for several different purposes. The Server Authentication and Client Authentication purposes must be enabled. You can enable or disable other purposes to suit your requirements.

    You enable certificate purposes by using the Certificates Snap-in for MMC. For more information, see Modify the Properties of a Certificate.

Grant access to the Business Central Server service account

After you have installed the root CA and the service certificate on the computer running Business Central Server, you must grant access to the service account that is associated with the server so that the service account can access the service certificate’s private key.

  1. In the left pane of MMC, expand the Certificates (Local Computer) node, expand the Personal node, and then select the Certificates subfolder.

  2. In the right pane, right-click the certificate, select All Tasks, and then choose Manage Private Keys.

  3. In the Permissions dialog box for the certificate, choose Add.

  4. In the Select Users, Computers, Service Accounts, or Groups dialog box, enter the name of the dedicated domain user account that is associated with Business Central Server, and then choose the OK button.

  5. In the Full Control field, select Allow, and then choose the OK button.

  6. In the right pane, select the certificate.

  7. In the Certificate dialog box, choose the Details tab, and then select the Thumbprint field.

  8. Copy the value of Thumbprint field.

    For example, copy the hexadecimal characters to text editor, such as Notepad. Delete all spaces from the thumbprint string. If the thumbprint is c0 d0 f2 70 95 b0 3d 43 17 e2 19 84 10 24 32 8c ef 24 87 79, then change it to c0d0f27095b03d4317e219841024328cef248779.

    Tip

    It is important that the thumbprint does not contain any invisible extra characters; otherwise you will experience problems when using it later. To avoid this, see Certificate thumbprint displayed in MMC certificate snap-in has extra invisible unicode character.

Configure the Business Central Server instance

The Business Central Server instance configuration includes several settings for certificates and enabling remote logins. You can modify a server instance by using Business Central Server Administration tool (version 20 and earlier only) or Business Central Administration Shell. For details about how to modify a server instance, see Configuring Business Central Server.

Using Business Central Administration Shell

  1. Run the Business Central Administration Shell as an administrator. For more information, see Administration Shell.

  2. At the prompt, run the following command to specify the certificate thumbprint:

    Set-NAVServerConfiguration -ServerInstance <BC server instance> -KeyName ServicesCertificateThumbprint -KeyValue <thumbprint>

    Substitute <BC server instance> with name of your server instance, like BC240.

  3. Run the following command to specify SSL between the web client and Business Central Server:

    Set-NAVServerConfiguration -ServerInstance <BC server instance> -KeyName ClientServicesSSLEnabled -KeyValue true

    Note

    This step is only for version 21 and later.

  4. Run the following commands to secure SOAP and OData web services:

    Set-NAVServerConfiguration -ServerInstance <BC server instance> -KeyName SOAPServicesSSLEnabled -KeyValue true

    Set-NAVServerConfiguration -ServerInstance <BC server instance> -KeyName ODataServicesSSLEnabled -KeyValue true

Using Business Central Server Administration tool

The Business Central Server Administration tool is only available for version 20 and earlier.

  1. Run the Business Central Server Administration tool.

  2. Under General, change the following settings for the Business Central Server instance.

    Setting New value Description
    Credential Type Windows, NavUserPassword, Username, or AccessControlService The default value is Windows. When you change it to NavUserPassword, Username, or AccessControlService, client users who connect to the server are prompted for user name and password credentials.
    Certificate Thumbprint Value of the Thumbprint field in the previous procedure. Remove any leading or trailing spaces in the thumbprint.

  3. If you want to use secure web services, then under SOAP Services and OData Services, select the Enable SSL check box.

  4. Save and the new values for the server instance.

  5. Restart the Business Central Server instance.

    If there is a problem, see Windows Event Viewer.

Configure the Business Central Web Server

The chain trust configuration allows client users to log on to one or more instances of Business Central Server as long as their login credentials have been associated with user accounts in Business Central. The client validates that the server certificate is signed with the root CA.

After you have installed the root CA on the computer running the Business Central Web Server, you must modify the client configuration file.

Modify the Business Central Web client configuration file

To configure the Business Central Web Server, you'll need the subject name, also known as the common name (CN), of the certificate that is used on the computer that is running Business Central Server.

You can configure the Business Central Web Server using the Business Central Administration Shell or changing the navsettings.json file manually.

Using Business Central Administration Shell

  1. Run the Business Central Administration Shell as an administrator. For more information, see Administration Shell.

  2. At the prompt, run the following commands:

    Set-NAVWebServerInstanceConfiguration -WebServerInstance <web server instance> -KeyName DnsIdentity -KeyValue true

    This following command is only required for version 21 and later:

    Set-NAVWebServerInstanceConfiguration -WebServerInstance <web server instance> -KeyName ServerHttps -KeyValue true

    Substitute <web server instance> with name of your web server instance, like BC240.

Manually changing the navsettings.json

  1. On the computer where the Business Central Web Server is installed, open the navsetting.json configuration file in a text editor, such as Notepad.

  2. Change the following settings:

    Key New value Description
    ClientServicesCredentialType Windows, NavUserPassword, Username, or AccessControlService The default value is Windows. When you change it to NavUserPassword, Username, or AccessControlService, client users who connect to the server are prompted for user name and password credentials.
    DnsIdentity The subject name of the service certificate The default value is <identity>. Replace this with the subject name or common name (CN) of the certificate that is used on the computer that is running Business Central Server.
    ServerHttps true The default value is false. This key is only available in version 21 and later, so it doesn't need to be set in earlier versions.

  3. Save the navsettings.json configuration file.

Configure Dynamics NAV Client connected to Business Central

Note

This section only applies to Business Central Spring 2019, version 14. Dynamics NAV Client connected to Business Central isn't supported in later versions.

After you have installed the root CA on the computer running the Dynamics NAV Client connected to Business Central, you must modify the client configuration file.

Modify the Dynamics NAV Client connected to Business Central configuration file

  1. Open the ClientUserSettings.config configuration file.

    The location of this file is Users\<username>\AppData\RoamingLocal\Microsoft\Dynamics 365 Business Central\<version>.

    By default, this file is hidden. Therefore, you may have to change your folder options in Windows Explorer to view hidden files.

    Note

    If you want to change default Dynamics NAV Client connected to Business Central settings for all future users, edit the default ClientUserSettings.config file — that is, the one in C:\Program Files (x86)\Microsoft Dynamics 365 Business Central\NNN. Be sure that you run your text editor with Administrator privileges when you do so.

  2. Modify the following settings.

    Key New value Description
    ClientServicesCredentialType NavUserPassword, Username, or AccessControlService The default value is Windows. When you change it to NavUserPassword, Username, or AccessControlService, client users are prompted for user name and password credentials.
    DnsIdentity The subject name of the service certificate. The default value is <identity>. Replace this with the subject name or common name (CN) of the certificate that is used on the computer that is running Business Central Server.

  3. Save and close the ClientUserSettings.config file.

When starting the Dynamics NAV Client connected to Business Central, users are prompted for a valid user name and password.

Authentication and User Credential Types