Walkthrough: Configuring Web Services to Use SSL

Secure Sockets Layer (SSL) is a cryptographic protocol that provides security and data integrity for data communications over a network. By encrypting your Microsoft Dynamics NAV 2009 Web services with SSL, you make your data and your network more secure and more reliable.

Microsoft Dynamics NAV Web Services and SSL

Microsoft Dynamics NAV supports SSL authentication. The server authenticates itself to the client, but the client does not authenticate itself to the server. When the Web service client connects to the Microsoft Dynamics NAV Business Web Services server, the server replies by sending its digital certificate to the client. This certificate contains the server's public encryption key and the name of the authority that granted the certificate. The client verifies the certificate using the authority's public key.

About This Walkthrough

This walkthrough illustrates the following tasks:

  • Configuring Microsoft Dynamics NAV Web services to use SSL.

  • Obtaining a certificate and import it into the local computer store on the computer running Microsoft Dynamics NAV Server.

  • Obtaining the certificate's thumbprint.

  • Configuring the Access Control List and the Web services port to use the SSL certificate.

  • Verifying the configuration.

Prerequisites

To complete this walkthrough, you will need:

  • Microsoft Dynamics NAV 2009 with a developer license.

  • Visual Studio 2005, Visual Studio 2008, or Visual C# 2008 Express Edition.

Story

Victor, who is a business systems developer at CRONUS International Ltd., knows that his implementation of Web services applications for Microsoft Dynamics NAV is unlikely to pass a company security audit unless he does something to encrypt sensitive data that is transmitted over the company intranet. He decides to protect Web services communication with SSL.

Configuring Microsoft Dynamics NAV Web Services to Use SSL

The first step is to prepare Microsoft Dynamics NAV to use SSL. This involves configuring the Microsoft Dynamics NAV Server configuration file to specify SSL and then starting the Microsoft Dynamics NAV Business Web Services service.

To configure Microsoft Dynamics NAV Server to use SSL

  1. Use a text editor to edit the CustomSettings.config file on the computer where you have installed Microsoft Dynamics NAV Server. The default location is C:\Program Files\Microsoft Dynamics NAV\60\Service.

  2. Change the value of the WebServiceSSLEnabled parameter from false to true. Save the file, and then close the editor.

  3. In Control Panel, click Administrative Tools, and then click Services.

  4. In the list of services, find Microsoft Dynamics NAV Business Web Services. Double-click to open the Properties dialog box for this service, and then click Start. If the service is already running, click Stop, and then click Start.)

    This service is not configured to start automatically when you start the computer. If you want this service to start automatically, on the Properties dialog box for this service, on the General tab, select Automatic as the value for Startup type.

    Note

    By default, the Microsoft Dynamics NAV Business Web Services service logs on using the NT Authority\Network Service account. We recommend that you configure this service to log on using a dedicated Windows domain user account. This account should not be an administrator either in the domain or on any local computer. Because the Microsoft Dynamics NAV Server service and the Microsoft Dynamics NAV Business Web Services service run on a single process, they must be run using the same account.

  5. Close the Services tool.

Obtaining and Importing an SSL Certificate

You obtain an SSL certificate from a certificate authority. Some large organizations may have their own certificate authorities, and other organizations can request a certificate from a third-party organization. Once you obtain a certificate, you must import it into the local computer store on the computer running Microsoft Dynamics NAV Server.

The certificate is a file. Use the following procedure to import the certificate into the local computer store.

To import an SSL certificate into the local computer store

  1. On the computer running Microsoft Dynamics NAV Server, click Start, and then click Run.

  2. In the Open box, type mmc, and then click OK.

  3. On the File menu, click Add/Remove Snap-in.

    This procedure assumes that you do not already have the Certificates snap-in installed in Microsoft Management Console. If the Certificates snap-in is already installed, you can skip steps 3 through 9.

  4. In the Add/Remove Snap-in dialog box, click Add.

  5. In the Add Standalone Snap-in dialog box, click Certificates, and then click Add.

  6. In the Certificates snap-in dialog box, click Computer account, and then click Next.

  7. In the Select Computer dialog box, click Local computer, and then click Finish.

  8. In the Add Standalone Snap-in dialog box, click Close.

  9. In the Add/Remove Snap-in dialog box, click OK.

  10. In the left pane of the console, double-click Certificates (Local Computer).

  11. Right-click Personal, point to All Tasks, and then click Import.

  12. On the Welcome to the Certificate Import Wizard page, click Next.

  13. On the File to Import page, click Browse, locate your certificate file, and then click Next.

  14. If the certificate has a password, type the password on the Password page, and then click Next.

  15. On the Certificate Store page, click Place all certificates in the following store, and then click Next.

  16. Click Finish, and then click OK to confirm that the import was successful.

Obtaining the Certificate's Thumbprint

To perform this task, you continue working in the Certificates snap-in in Microsoft Management Console.

To obtain the certificate's thumbprint

  1. In the left pane of the Console Root window, click Certificates (Local Computer).

  2. Click the Personal folder to expand it.

  3. Click the Certificates folder to expand it.

  4. Double-click the certificate that you just imported.

  5. In the Certificate dialog box, click the Details tab.

  6. Scroll through the list of fields, and then click Thumbprint.

  7. Copy the hexadecimal characters from the box, and then paste them in Notepad.

  8. Delete all spaces in the thumbprint.

Configuring the Access Control List and the Web Services Port

These procedures use the httpcfg tool for configuring the HTTP server. When you install Microsoft Dynamics NAV Server, Setup puts a copy of httpcfg.exe in the Microsoft Dynamics NAV Server directory. By default, this directory is C:\Program Files\Microsoft Dynamics NAV\60\Service.

An Access Control List (ACL) is part of the Windows security infrastructure. For more information, see Access Control Lists.

To configure the Access Control List

  1. At the command prompt, navigate to the directory where httpcfg.exe is located.

  2. View the ACL for the Web services port to determine if any entries are already using the relevant host name and port by typing the following command:

    httpcfg query urlacl
    

    In the data that is returned to the prompt, '+' (plus sign) represents localhost.

    Note

    If you have previously configured Microsoft Dynamics NAV Web services for delegation using the instructions in How to: Configure Web Services with Delegation, you will have also previously configured an ACL for the http URL. We recommend deleting that ACL and replacing it with one for the https URL as described in the following steps because Web services clients could otherwise connect to Microsoft Dynamics NAV without using SSL.

  3. Delete any entries that use your host name and Web service port, such as:

    httpcfg delete urlacl –u http://+:7047/DynamicsNAV/
    
  4. Register the port with https:

    httpcfg set urlacl -u https://+:7047/DynamicsNAV/ -a D:^(A;^;GX^;^;^;<security identifier>)
    

    Replace <security identifier> with the actual security-identifier attribute (SID) for the account. A security identifier is a unique value of variable length used to identify a user or group account. For more information, see Security Identifiers.

  5. Requery the ACL as you did in step 2 to verify that your port has been registered.

To configure the port to use the SSL certificate

  1. At the command prompt, type the following command to view the current port configuration:

    httpcfg query ssl
    
  2. If SSL is already configured on the address and port that you want to use, where 0.0.0.0 indicates all IP addresses, then delete it using the following command and substitute your IP and port number:

    httpcfg delete ssl –i 0.0.0.0:7047
    
  3. Associate the certificate with your port, using the IP address, port number, and thumbprint that you pasted to Notepad:

    httpcfg set ssl -i <ip address>:<port> -h <thumbprint>
    

Verifying the Configuration

You should now be able to use Web services that are encrypted with SSL. To verify this, type the following URL in the address bar for your browser.

https://localhost:7047/DynamicsNAV/WS/services

The page lists any Web services that have been published.

Next Steps

You can now try any other walkthroughs in this section of the online Help. The only change that is required for using these walkthrough with SSL is that you use "https" instead of "http" in your URLs.

See Also

Tasks

How To: Set Up Delegation

Concepts

Security in the RoleTailored Environment