Walkthrough: Setting up Team Foundation Server with Secure Sockets Layer (SSL) and an ISAPI Filter

The following walkthrough describes one process for requesting, issuing, and assigning certificates that are used for Secure Sockets Layer (SSL) connections in Visual Studio Team System Team Foundation Server, configuring Basic and/or Digest authentication, and configuring an ISAPI filter. In order to support external connections to your Team Foundation Server deployments, you must configure Internet Information Services (IIS) to enable Basic and/or Digest authentication. Additionally, you must configure an Internet Server Application Programming Interface (ISAPI) filter.

Throughout this walkthrough, you will accomplish the following activities:

1. Create a certificate request for Team Foundation Web sites.

2. Issue the certificate request and create the binary certificate file.

3. Install and assign the certificate.

4. Configure the Team Foundation Server for HTTPS and SSL.

5. Install the certificate on client computers.

6. Test the certificate.

Prerequisites

To complete this walkthrough:

• The logical components that compose the data tier of Team Foundation and the application tier of Team Foundation Server must be installed and operational. This walkthrough refers to the server or servers that are running the logical components that compose the application tier of Team Foundation as the application-tier server for Team Foundation. This walkthrough also refers to the server or servers that are running the logical components that compose the data tier of Team Foundation as the data-tier server for Team Foundation. Depending on your deployment configuration, these servers might be the same physical server or one or more different physical servers. For more information, see the installation guide for Team Foundation. You can download the most recent version of this guide from the Microsoft Download Center (https://go.microsoft.com/fwlink/?linkid=79226).

• You must have a certification authority (CA) available to issue certificates. This walkthrough assumes that you are using Microsoft Certificate Services as your CA. If you do not have a certification authority, you can install Microsoft Certificate Services and configure a certification authority. For more information, see the Microsoft Web site (https://go.microsoft.com/fwlink/?LinkId=70929).

Required Permissions

To complete this procedure, you must be a member of the Administrators group on the application-tier and data-tier servers for Team Foundation and a member of the Team Foundation Administrators group. To configure a build agent for SSL connections, you must be a member of the Administrators group on the build computer. For more information about permissions, see Team Foundation Server Permissions.

Assumptions

This walkthrough demonstrates a specific deployment configuration. If your deployment differs from this configuration, some of the steps in this walkthrough will not match those steps required to configure your deployment. For more information about steps for different versions of SharePoint Products and Technologies, SQL Server, Windows Server, and Internet Explorer, consult the Help for the appropriate versions of those systems.

This walkthrough makes the following assumptions about the starting configuration of the deployment for which you want to configure HTTPS and SSL:

• The servers in the deployment are running Windows Server 2003 and IIS 6.0.

• The deployment uses SQL Server 2005 and Windows SharePoint Services 3.0.

• The client computers in the deployment are running Windows XP and Internet Explorer 6.0.

• Both Windows SharePoint Services 3.0 and Certificate Services are installed and configured on the application-tier server for Team Foundation.

  Note

  To follow best practices for security, you should install Certificate Services on the application tier only for demonstration or test purposes. In a production environment, you should always install Certificate Services on a separate server.

• The data-tier and application-tier servers for Team Foundation have been installed and deployed in a secure environment and configured according to best practices for security.

• To configure a build agent for SSL connections, the following conditions must be true:

  • Team Foundation Build and Team Explorer must be installed and operational.

  • A certificate must have been issued for the build agent.

  • Windows Support Tools must be installed on the build computer so that you can associate a certificate with the IP address and port. For more information, see "Windows Support Tools" (https://go.microsoft.com/fwlink/?LinkId=93827).

Installing Microsoft Certificate Services

This walkthrough uses Microsoft Certificate Services as the certification authority (CA) for issuing certificates. For convenience in this walkthrough, Certificate Services is installed on the Team Foundation application-tier server, but you can choose your own certification authority software and deployment configuration as best suits your business needs. For security, you should consider isolating your root certification authority when you deploy Certificate Services in a production deployment. Physical isolation of the CA server, in a facility that is available only to security administrators, can significantly reduce the risk of tampering. For more information about Certificate Services features and best practices, see the Microsoft Web site (https://go.microsoft.com/fwlink/?LinkId=70929).

To install Certificate Services on Windows Server 2003

1. Click Start, click Control Panel, and then click Add or Remove Programs.

2. Click Add/Remove Windows Components.

3. In the Windows Components Wizard, click Certificate Services in the Components list.

4. Review the text in the message box, and then click Yes.

5. Click Next to start the installation.

6. On the CA Type page, select Stand-alone root CA, and then click Next.

7. On the CA Identifying Information page, in Common name for this CA, type the name of the computer.

8. In Validity period, change the duration for the certificate to six (6) months, and then click Next.

9. On the Certificate Database Settings page, click Next without making any changes.

   A message box appears that shows that IIS must be stopped.

10. In the message box, click Yes.

    The Configuring Components page appears.

11. If a message box appears with information about Active Server Pages (ASP), click Yes.

12. Click Finish.

Creating a Certificate Request for Team Foundation Server Web Sites

On the application-tier computer, you must create a certificate request for Team Foundation using Internet Information Services (IIS) Manager.

To create a certificate request for Team Foundation Server Web sites

1. Click Start, click Administrative Tools, and then click Internet Information Services (IIS) Manager.

2. Expand ComputerName (Local Computer), and then expand Web sites.

3. Right-click Team Foundation Server, and then click Properties.

4. In Team Foundation Server Properties, click the Directory Security tab.

5. Under Secure Communications, click Server Certificate.

6. When the Web Server Certificate Wizard appears, click Next.

7. On the Server Certificate page, click Create a new certificate, and then click Next.

8. On the Delayed or Immediate Request page, click Next.

9. On the Name and Security Settings page, click Next without making any changes.

10. On the Organization Information page, specify values for Organization and Organization unit.

    For example, type the name of your company as the Organization and your team or group name for Organization unit.

11. Click Next.

12. On the Your Site's Common Name page, click Next without making any changes.

13. On the Geographical Information page, specify the appropriate information in the Country/Region, State/province, and City/locality boxes, and then click Next.

14. On the Certificate Request File Name page, under File name, specify the location where you want the certificate request file saved and the name of the file, and then click Next.

    Note

    Make sure that you save the certificate request file to a network share or other location that can be accessed from the CA computer.

15. Review the information that is listed on the Request File Summary page.

16. Click Next, click Finish, and then click OK to close the Team Foundation Server Properties dialog box.

Issuing a Certificate Request and Creating a Binary Certificate File

After you have created a certificate request, you must have the CA, in this case Microsoft Certificate Services, issue a certificate based on the request. As soon as a certificate is created, you can assign the certificate to the appropriate Web sites using IIS.

To issue a certificate request using Microsoft Certificate Services

1. Click Start, click Administrative Tools, and then click Certification Authority.

2. In the Explorer pane, right-click the computer name, select All Tasks, and the click Submit new request.

3. In the Open Request File dialog box, locate the certificate request text file that you created in the previous procedure, and then click Open.

4. In the Explorer pane, expand the computer name, and then click Pending Requests.

5. Note the Request ID value for the pending request.

6. Right-click the request, select All Tasks, and then click Issue.

7. In the Explorer window, under the computer name, select Issued Certificates and review the listed certificates to verify that a certificate was issued that matches the Request ID value for your request.

8. In Issued Certificates, right-click the issued certificate, select All Tasks, and then click Export Binary Data.

9. In Columns that contain binary data, select Binary Certificate. Under Export options, select Save binary data to a file, and then click OK.

10. In Save Binary Data, save the file to a portable media device or network share that can be accessed by the Team Foundation application-tier computer.

11. Exit Certification Authority.

Installing and Assigning the Certificate

Before you can use SSL with Team Foundation, you must install the server certificate on the Team Foundation Web site and then configure HTTPS on Team Foundation-related Web sites. These related Web sites include the following:

• Default Web site

• SharePoint Central Administration

• Report Server

Installing the Server Certificate

Follow these steps to install the server certificate on Team Foundation.

To install the server certificate on the Team Foundation Server Web site

1. On the Team Foundation application-tier server, click Start, click Administrative Tools, and then click Internet Information Services (IIS) Manager.

2. Expand <computername> (local computer) and then expand Web sites.

3. Right-click Team Foundation Server and then click Properties.

4. In Team Foundation Server Properties, click the Directory Security tab.

5. Under Secure Communications, click Server Certificate.

   The Web Server Certificate Wizard appears. Click Next.

6. On the Pending Certificate Request page, select Process the pending request and install the certificate, and then click Next.

7. On the Process a Pending Request page, click Browse.

8. In the Open dialog box, under Files of type, select All files (*.*) from the drop-down list, and then locate the directory where you saved the binary certificate in the previous procedure. Select the binary certificate file and then click Open.

9. On the Process a Pending Request page, click Next.

10. On the SSL Port page, accept the default value or enter a new value, and then click Next. The default port for SSL connections is 443, but you must assign a unique port value for each of the following three sites: the Team Foundation Server Web site, the default Web site, and the SharePoint Central Administration Web site.

    Important Note:

    Consider using a port number other than the default, as using a default port number can reduce the security of your deployment. Make a note of the SSL port value that you assign. Before you accept the default value, make sure that the port is not being used by another server certificate or other network service. SSL port values must be different for each server certificate you install. For example, if the default port of 443 is not already being used and you accept the default port value of 443 for the Team Foundation Web site, you must assign a different port value for the default Web site and the SharePoint Central Administration Web site.

11. Review the information about the Certificate Summary page, click Next, and then click Finish.

12. On the Directory Security tab, under Secure Communications, click Edit.

13. In Secure Communications, select Require secure channel (SSL) check box, make sure that Ignore client certificates is selected, and then click OK.

14. Click OK to close the Team Foundation Server Properties dialog box.

1. On the Directory Security tab, under Authentication and access control, click Edit.

2. In Authentication Methods, make sure that the Enable anonymous access check box is cleared.

3. In Authenticated access, select Integrated Windows authentication and either Digest authentication for Windows domain servers, Basic authentication, or both, as appropriate to your deployment.

   For more information, see Team Foundation Server, Basic Authentication, and Digest Authentication.

4. Clear any other selections, and then click OK.

   Note   After you click Digest authentication for Windows domain servers, you might be prompted to confirm your choice. Read the text, and then click Yes.

   Important Note:
   You must configure Digest authentication correctly. Otherwise, attempts to access Team Foundation Server will fail. Do not choose Digest authentication unless your deployments meets all the requirements for Digest authentication. For more information, see the Microsoft Web site (https://go.microsoft.com/fwlink/?LinkId=89709).

5. Click OK to close the Team Foundation Server Properties dialog box.

   Note

   If an Inheritance Overrides dialog box appears after you click OK, click Select All, and then click OK.

Assigning the Certificate to the Default Web Site

Follow these steps to set up HTTPS on the default Web site in IIS.

To set up HTTPS on the default Web site

1. On the Team Foundation application-tier server, click Start, click Administrative Tools, and then click Internet Information Services (IIS) Manager.

2. Expand <computername> (local computer) and then expand Web Sites.

3. Right-click Default Web Site and then click Properties.

4. In Default Web Site Properties, click the Directory Security tab.

5. Under Secure Communications, click Server Certificate.

   The Web Server Certificate Wizard appears. Click Next.

6. On the Server Certificate page, select Assign an existing certificate, and then click Next.

7. On the Available Certificates page, select the certificate whose Friendly Name value is Team Foundation Server. You might have to scroll to see the Friendly Name column in the list. Click Next.

8. On the SSL Port page, accept the default value or enter a new value, and then click Next. The default port for SSL connections is 443, but you must assign a unique port value for each of the following three sites: the Team Foundation Server Web site, the default Web site, and the SharePoint Central Administration Web site.

   Important Note:

   Consider using a port number other than the default, as using a default port number can reduce the security of your deployment. Make a note of the SSL port value. SSL port values must be different for each server certificate that you install, and they cannot be already in use by another network service. For example, if you accept the default port value of 443 for the Team Foundation Web site, you must assign a different port value for the default Web site and the SharePoint Central Administration Web site.

9. Review the information about the Certificate Summary page and then click Next.

10. Click Finish. The wizard will close.

11. On the Directory Security tab, under Authentication and access control, click Edit.

12. In Authentication Methods, make sure that the Enable anonymous access box is cleared. In Authenticated access, select Integrated Windows authentication and either Digest authentication for Windows domain servers, Basic authentication, or both, as appropriate to your deployment. Clear any other selections, and then click OK. For more information about authentication methods and Team Foundation Server, see Team Foundation Server, Basic Authentication, and Digest Authentication.

    Note

    After clicking Digest authentication for Windows domain servers, you might be prompted to confirm your choice. Read the text and then click Yes.

13. Click OK to close the Default Web Site Properties dialog box.

    Note

    If an Inheritance Overrides dialog box appears after clicking OK, click Select All, and then click OK.

Assigning the Certificate to SharePoint Central Administration

Follow these steps to set up HTTPS for SharePoint Central Administration.

To set up HTTPS for SharePoint Central Administration

1. On the Team Foundation application-tier server, click Start, click Administrative Tools, and then click Internet Information Services (IIS) Manager.

2. Expand <computername> (local computer) and then expand Web Sites.

3. Right-click SharePoint Central Administration and then click Properties.

4. In SharePoint Central Administration Properties, click the Directory Security tab.

5. Under Secure Communications, click Server Certificate.

   The Web Server Certificate Wizard appears. Click Next.

6. On the Server Certificate page, select Assign an existing certificate, and then click Next.

7. On the Available Certificates page, select the certificate whose Friendly Name value is Team Foundation Server. You might have to scroll to see the Friendly Name column in the list.

8. Click Next.

9. On the SSL Port page, accept the default value or enter a new value, and then click Next. The default port for SSL connections is 443, but you must assign a unique port value for each of the following three sites: the Team Foundation Server Web site, the default Web site, and the SharePoint Central Administration Web site.

   Important Note:

   Consider using a port number other than the default, as using a default port number can reduce the security of your deployment. Make a note of the SSL port value. SSL port values must be different for each server certificate that you install, and they cannot be already in use by another network service. For example, if you accept the default port value of 443 for the Team Foundation Web site, you must assign a different port value for the default Web site and the SharePoint Central Administration Web site.

   Note

   Make a note of this value, as you will need it in order to assign the certificate to the SQL Report Server.

10. Review the information about the Certificate Summary page, click Next, and then click Finish.

Configuring the ISAPI Filter

You must edit the ISAPI initialization file that is in the same directory as the AuthenticationFilter.dll file. You must also add the ISAPI filter to the registry.

To configure the ISAPI Filter

1. On the application-tier server for Team Foundation, click Start, click Programs, click Accessories, and then click Notepad.

2. In Notepad, open the AuthenticationFilter.ini file that is in the same directory as AuthenticationFilter.dll.

   By default, this directory is Drive:\Program Files\Microsoft Visual Studio 2008 Team Foundation Server\Tools.

3. Modify the .ini file in the following ways:

   • ProxyAddress is the IP address from which external network traffic to Team Foundation Server will appear to originate (usually a router) for which you want to require HTTPS/SSL with Basic or Digest authentication. 

   • SubnetMask is the IP address/subnet mask pair or pairs for which you do not want to enforce Digest or Basic authentication.

   Important Note:
   If you add the ProxyIPList key to the file, the SubnetList key and its values will be ignored. For more information, see Team Foundation Server, Basic Authentication, and Digest Authentication.

   Note

   You can specify more than one value for either ProxyAddress or IP/SubnetMask, but you must delimit multiple values with semicolons.

   [config]

   **RequireSecurePort=**false

   **ProxyIPList=**ProxyAddress

   **SubnetList=**SubnetMask

4. Save this file as AuthenticationFilter.ini in the same directory as AuthenticationFilter.dll:

   Drive**:\Program Files\Microsoft Visual Studio 2008 Team Foundation Server\Tools**

   Important Note:
   Do not change the directory of either the AuthenticationFilter.ini file or the AuthenticationFilter.dll file. If you change either of these directories, you will more likely have problems when you perform maintenance or upgrade your deployment.

5. Open a Command Prompt window.

   To open a Command Prompt, click Start, click Run, type cmd, and then click OK.

   Note

   Even if you are logged on with administrative credentials, you must open an elevated Command Prompt to perform this function on a server that is running Windows Server 2008. To open an elevated Command Prompt, click Start, right-click Command Prompt, and click Run as Administrator. For more information, see the Microsoft Web site.

6. At the command prompt, type the following command:

   reg.exe add "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Eventlog\Application\TFS ISAPI Filter" /v EventMessageFile /t REG_SZ /d %windir%\Microsoft.NET\Framework\v2.0.50727\EventLogMessages.dll /f

7. At the command prompt, type the following command:

   reg.exe add "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Eventlog\Application\TFS ISAPI Filter" /v TypesSupported /t REG_DWORD /d 7 /f

8. On the Team Foundation application-tier server, click Start, click Administrative Tools, and then click Internet Information Services (IIS) Manager.

9. Expand ComputerName (local computer), expand Web Sites, right-click Team Foundation Server, and then click Properties.

   The Team Foundation Server Properties dialog box opens.

10. Click the ISAPI Filters tab.

11. Under ISAPI Filters, click Add.

    The Add/Edit Filter Properties dialog box opens.

12. In Filter name, type TFAuthenticationFilter.

13. In Executable, type Drive**:\Program Files\Microsoft Visual Studio 2008 Team Foundation Server\Tools\AuthenticationFilter.dll**, and then click OK.

Configuring Your Firewall to Allow SSL Traffic

You must configure your firewall to allow for traffic on the SSL ports you specified in IIS for the default Web site, the Team Foundation Web site, and the SharePoint Central Administration Web site.

To configure a firewall to allow for network traffic on the SSL ports that are used by Team Foundation Server

• See your firewall product documentation to determine the steps that are required to allow for network traffic on the SSL ports you specified for the default Web site, the Team Foundation Web site, and the SharePoint Central Administration Web site.

Configuring SharePoint Products and Technologies to Allow Alternate Mappings

For team project portal mappings and administration mappings to work correctly, you must configure SharePoint Products and Technologies to allow for alternate mappings for traffic on the SSL ports you specified in IIS for the default Web site, the Web site for Team Foundation Server, and the SharePoint Central Administration Web site.

To configure Windows SharePoint Services 3.0 to allow alternate access mappings to team project Web sites

1. On the server that is running Windows SharePoint Services 3.0, open Internet Explorer, and navigate to https://SharePointServerName:AdministrationPort.

   Important Note:

   You configured the administration port for SharePoint Products and Technologies in the procedure "To set up HTTPS for SharePoint Central Administration and Require SSL" previously in this walkthrough. You must navigate to the Central Administration site using the port that you assigned in that procedure. Until this procedure has been completed, you cannot access the Central Administration tool from the Start menu.

2. On the Central Administration page, click Operations.

3. On the Operations page, in the Global Configuration section, click Alternate access mappings.

4. Edit the mappings to reflect the SSL port information for the SharePoint Administration Web site and the default Web site, and then click Save.

   Note

   For more information about alternate access mappings in Windows SharePoint Services 3.0, see this topic on the Microsoft Web site: Configure alternate access mapping (Windows SharePoint Services).

Updating Team Projects for SQL Report Server by Using the TFSConfigWss command-line tool

Follow these steps to update the team project Web sites for SQL Report Server so that reports appear correctly on the team project portal sites.

To update team project sites for SQL Report Server

1. On the application-tier server for Team Foundation, open a Command Prompt window, and change directories to Drive:\%ProgramFiles%\Microsoft Visual Studio 2008 Team Foundation Server\Tools.

2. At the command prompt, type the following command, and replace these strings:

   • SharePointSite is the new uniform resource indicator (URI) of the site collection of SharePoint Products and Technologies.

   • Reports is the new URI for SQL Server Reporting Services.

   • ReportServer is the new URI for the ReportsService.asmx Web service.

     **TfsConfigWss ConfigureReporting /SharepointSitesUri:SharePointSite/ReportsUri:Reports/ReportServerUri:**ReportServer

Updating Team Foundation Server Configuration Information

Follow these steps to update configuration information with the https URL values for the Windows SharePoint Services and Reporting Services Web sites.

To update configuration information for Team Foundation Server

1. On the Team Foundation application-tier server, open a Command Prompt window, and change directories to Drive:\%ProgramFiles%\Microsoft Visual Studio 2008 Team Foundation Server\Tools.

2. At the command prompt, type the following command, and replace these strings:

   • BaseServerURL is the new URI for the Web server for the Team Foundation application-tier server.

   • BaseSiteURL is the new URI for the default Web site for the application-tier server.

   • SharePointSite is the new URI for the SharePoint Products and Technologies site collection.

   • SharePointAdministration is the new URI for the SharePoint Central Administration Web site.

   • Reports is the new URI for SQL Server Reporting Services.

   • ReportServer is the new URI for the ReportsService.asmx Web service.

     Important Note:
     If you have installed SP1 for Visual Studio Team System 2008 Team Foundation Server, the /ReportServer parameter will not function correctly. For more information about this problem and its resolution, see this article on the Microsoft Web site: Team Foundation Server 2008 SP1 TfsAdminUtil.exe 'ConfigureConnections' fails to properly set ReportServerUri.

     TfsAdminUtil ConfigureConnections /ATUri:BaseServerURL/SharepointUri:BaseSiteURL**/SharepointSitesUri:SharePointSite/SharepointAdminUri:SharePointAdministration/ReportsUri:Reports/ReportServerUri:**ReportServer

   Note

   If you are using a named instance, you will need to specify the named instance as part of the values for Reports and ReportServer. Do not eliminate or change the name of the named instance.

   For example, if you specified port 443 for the Team Foundation Web SSL site port value, 1443 for the default Web site SSL port value in IIS, and 2443 for the SharePoint Central Administration port value, and your application-tier server was named Contoso1, you would modify the values as follows:

   **TfsAdminUtil ConfigureConnections /ATUri:**https://Contoso1:443 **/SharepointUri:**https://Contoso1:1443 /SharepointSitesUri:https://Contoso1:1443/Sites/SharepointAdminUri:https://Contoso1:2443 /ReportsUri:https://Contoso1:1443/Reports/ReportServerUri:https://Contoso1:1443/ReportServer

   Note

   The ConfigureConnections command has several additional options, such as updating the public Web address used in e-mail alerts. For more information, see ConfigureConnections Command.

Installing the Certificate on Build Computers

If you installed Build Services on one or more servers, you must install the certificate on each of those servers.

To install the certificate on build computers

1. Log on to the build computer by using an account that is a member of the Administrators group on that computer.

2. Open a browser, and then browse to the following Web site, where ApplicationTierServer is the name of the application-tier server for Team Foundation, and Port is the SSL port number that you assigned to the Web site for Team Foundation Server:

   https://ApplicationTierServer:Port/services/v1.0/serverstatus.asmx

   A security message dialog box appears.

3. On Security Alert, click View Certificate.

4. On the Certificate dialog box, click the Certification Path tab.

5. In Certification path, click the certification authority. This should be the top node of the certification hierarchy, and there should be a red X next to the name. This indicates that the certification authority is not trusted because it is not in the Trusted Root Certification Authorities store. Click View Certificate.

6. On the Certificate dialog box, click Install Certificate.

   The Certificate Import Wizard opens. Click Next.

7. On the Certificate Store page, select Place all certificates in the following store, and then click Browse.

8. In Select Certificate Store, select Show physical stores. In Select the certificate store you want to use, expand Trusted Root Certification Authorities, select Local Computer, and then click OK.

9. On the Certificate Store page, click Next.

10. On the Completing the Certificate Import Wizard page, click Finish.

11. A Certificate Import Wizard dialog box might appear confirming that the import was successful. If the dialog box appears, click OK.

12. On the Certificate dialog box, click OK. The Certificate dialog box for the top node certification hierarchy will close.

13. On the Certificate dialog box, click OK. The Certificate dialog box for the subservient certificate will close.

14. On Security Alert, click No.

15. Open a browser, and then browse to the following Web site, where ApplicationTierServer is the name of the application-tier server for Team Foundation, and Port is the SSL port number that you assigned to the Web site for Team Foundation Server:

    https://ApplicationTierServer:Port/services/v1.0/serverstatus.asmx

    The ServerStatus Web Service page opens. This result confirms that you have installed the certificate and the certification authority correctly.

16. Close the browser.

Configuring a Build Agent for SSL Connections

To configure a build agent for SSL connections, you must configure an HTTPS certificate for each combination of IP address and port. If all build agents share the same port on the build computer, you must configure only a single certificate. If you run more than one build agent on more than one port, you must configure a certificate for each port.

You configure a build agent to require SSL by performing the following tasks in sequence:

1. Create and configure the build agent to require HTTPS.

2. Stop the Visual Studio Team Foundation Build service.

3. Modify the build service configuration to require HTTPS.

4. Associate a certificate with the IP address and port.

   Important Note:
   You cannot use the same certificate on the build agent that you used on the server that is running Team Foundation Server. The build agent must have its own certificate. You must install the certificate in the trusted root store on both the build computer for the account on which the build service is running and the computer that initiates the build.

5. Configure the port and protocol for the build agent.

6. Restart the Visual Studio Team Foundation Build service.

7. Verify the SSL configuration.

To configure the build agent to require HTTPS

1. Open the Manage Build Agents dialog box, and select the Require Secure Channel (HTTPS) check box.

   For more information, see How to: Create and Manage Build Agents.

2. Click Edit.

   The Build Agent Properties dialog box appears.

3. In the Agent status list, click Disabled.

To stop the Visual Studio Team Foundation Build service

1. Log on to the build computer by using an account that is a member of the Administrators group on that computer.

2. On the build computer, click Start, click Control Panel, click Administrative Tools, and then click Services.

3. In the Services (Local) pane, right-click Visual Studio Team Foundation Build, and click Properties.

   The Visual Studio Team Foundation Build Properties (Local Computer) dialog box opens.

4. Under Service Status, click Stop.

To modify the build service configuration to require HTTPS

1. Log on to the build computer by using an account that is a member of the Administrators group on that computer.

2. Open Drive:\Program Files\Microsoft Visual Studio 2008\Common7\IDE\PrivateAssemblies, right-click TfsBuildservice.config.exe, and click Open.

   The file opens in the XML editor for Visual Studio.

3. In the <appSettings> section, change the value of the RequireSecureChannel key to "true". For example, change the key definition to the following string:

   <add key="RequireSecureChannel" value="true" />
   

4. Save your changes, and close the file.

To associate an SSL certificate to an IP address and port number

1. Log on to the build computer by using an account that is a member of the Administrators group on that computer.

2. Use the Certificates snap-in to find an X.509 certificate that has an intended purpose of server authentication.

   Important Note:
   You cannot use the same certificate on the build computer as the certificate that you use on the server that is running Team Foundation Server unless the build computer is installed on the same server that is running the application tier for Team Foundation.

   For more information, see "How To: Retrieve the Thumbprint of a Certificate" (https://go.microsoft.com/fwlink/?LinkId=93828).

3. Copy the thumbprint of the certificate into a text editor, such as Notepad.

4. Remove all spaces between the hexadecimal characters.

   You can perform this task by using the text editor's find-and-replace feature to replace each space with a null character.

5. On the build computer, click Start, click All Programs, click Windows Support Tools, and then click Command Prompt.

6. Run the HttpCfg.exe tool in "set" mode on the SSL store to bind the certificate to a port number. The tool uses the thumbprint to identify the certificate, as shown in the following example:

   httpcfg set ssl /i 0.0.0.0:9191 /h ThumbprintWithNoSpaces
   

   The /i parameter has the syntax of IPAddress:Port and instructs the tool to set the certificate to port 9191 of the build computer. The IP address 0.0.0.0 reserves all computer addresses for simplicity. If you need additional precision, specify the exact IP address on which the agent service is published. The /h parameter specifies the thumbprint of the certificate.

   If the client certificate must be negotiated, add the parameter**/f 2** as shown in the following example:

   httpcfg set ssl /i 0.0.0.0:9191 /h ThumbprintWithNoSpaces /f 2
   

   For more information about the syntax of the HttpCfg.exe command, see "How To: Configure a Port with An SSL Certificate" (https://go.microsoft.com/fwlink/?LinkId=93829).

To configure the build agent port and protocol

1. At the command prompt, run wcfhttpconfigfreePortNumber. The command statement should resemble the following string:

   wcfhttpconfig free OldPortForHttp
   

   For more information, see wcfhttpconfig (Team Foundation Build).

2. At the command prompt, run wcfhttpconfigreserveUserAccountURL. The command statement should resemble the following:

   wcfhttpconfig reserve Domain\Account https://+Computer:NewPortForHttps/Build/v2.0/AgentService.asmx
   

3. Add the port to the exceptions list for Windows Firewall.

To restart the Visual Studio Team Foundation Build service

1. Log on to the build computer by using an account that is a member of the Administrators group on that computer.

2. On the build computer, click Start, click Control Panel, click Administrative Tools, and then click Services.

3. In the Services (Local) pane, right-click Visual Studio Team Foundation Build, and click Properties.

   The Visual Studio Team Foundation Build Properties (Local Computer) dialog box opens.

4. Under Service Status, click Start.

To verify the SSL configuration

1. Open the Manage Build Agents dialog box.

   For more information, see How to: Create and Manage Build Agents.

2. Click Edit.

   The Build Agent Properties dialog box appears.

3. In the Agent status list, click Enabled.

4. Verify whether communication is occurring by running a build using the build agent.

   For more information, see How to: Queue or Start a Build Definition.

Installing the Certificate on Team Foundation Server Proxy Computers

If you installed Team Foundation Proxy on one or more computers, you must install the certificate on each of those computers.

To install the certificate on Team Foundation Server Proxy computers

1. Log on to the Team Foundation Proxy server by using an account that is a member of the Administrators group on that computer.

2. Open a browser, and then browse to the following Web site, where ApplicationTierServer is the name of the server that is running the application tier for Team Foundation and Port is the SSL port number that you assigned to the Web site for Team Foundation Server:

   https://ApplicationTierServer:Port/services/v1.0/serverstatus.asmx

3. A security message dialog box appears. On Security Alert, click View Certificate.

4. On the Certificate dialog box, click the Certification Path tab.

5. In Certification path, click the certification authority. This should be the top node of the certification hierarchy, and there should be a red X next to the name. This indicates that the certification authority is not trusted because it is not in the Trusted Root Certification Authorities store. Click View Certificate.

6. On the Certificate dialog box, click Install Certificate.

   The Certificate Import Wizard opens. Click Next.

7. On the Certificate Store page, select Place all certificates in the following store, and then click Browse.

8. In Select Certificate Store, select Show physical stores. In Select the certificate store you want to use, expand Trusted Root Certification Authorities, select Local Computer, and then click OK.

9. On the Certificate Store page, click Next.

10. On the Completing the Certificate Import Wizard page, click Finish.

11. A Certificate Import Wizard dialog box might appear confirming that the import was successful. If this dialog box appears, click OK.

12. On the Certificate dialog box, click OK. The Certificate dialog box for the top node certification hierarchy will close.

13. On the Certificate dialog box, click OK. The Certificate dialog box for the subservient certificate will close.

14. On Security Alert, click No.

15. Open a browser, and then browse to the following Web site, where ApplicationTierServer is the name of the server that is running the application tier for Team Foundation and Port is the SSL port number that you assigned to the Web site for Team Foundation Server:

    https://ApplicationTierServer:Port/services/v1.0/serverstatus.asmx

    The ServerStatus Web Service page opens. This result confirms that you have installed the certificate and the certification authority correctly.

16. Close the browser.

Installing the Certificate on Client Computers

Every client computer that accesses Team Foundation must have the certificate installed locally. Additionally, if the client computer has previously accessed a Team Foundation team project, you must clear the client cache for every user who uses the computer to connect to Team Foundation before that user will be able to connect to Team Foundation.

If your client computer is running Windows Vista or Windows Server 2008, you might experience errors when you attempt to install the certificate. You must install an update from the following page on the Microsoft Web site: How to use Certificate Services Web enrollment pages together with Windows Vista or Windows Server 2008. After you install the update, you must download the certificate manually from the certificate server and save it to the Trusted Root Authority store before you can complete the procedure below. For more information about how to save certificates, see the following page on the Microsoft Web site: Retrieve a certification authority certificate from a Windows Server 2003 CA. 

To install the certificate on Team Foundation client computers

1. Log on to the Team Foundation client computer by using an account that is a member of the Administrators group on that computer.

2. Open a browser, and then browse to the following Web site, where ApplicationTierServer is the name of the server that is running the application tier for Team Foundation and Port is the SSL port number that you assigned to the Web site for Team Foundation Server:

   https://ApplicationTierServer:Port/services/v1.0/serverstatus.asmx

   A security message dialog box appears

3. On Security Alert, click View Certificate.

   Note

   If you are using Internet Explorer 7.0, a Web page might appear instead of a security message. Click Continue to this Web site (not recommended) to continue with this procedure, and then click the Certificate Error box in the address bar in order to proceed.

4. In the Certificate dialog box, click the Certification Path tab.

5. In Certification path, click the certification authority. This should be the top node of the certification hierarchy, and there should be a red X next to the name. This indicates that the certification authority is not trusted because it is not in the Trusted Root Certification Authorities store. Click View Certificate.

   Note

   If you are using Internet Explorer 7 on Windows Vista, you must use Certificate Manager to add the certificate. For more information, see this topic on the Microsoft Web site: Certificates: Frequently Asked Questions.

6. On the Certificate dialog box, click Install Certificate.

   The Certificate Import Wizard opens. Click Next.

7. On the Certificate Store page, select Place all certificates in the following store, and then click Browse.

8. In Select Certificate Store, select Show physical stores. In Select the certificate store you want to use, expand Trusted Root Certification Authorities, select Local Computer, and then click OK.

9. On the Certificate Store page, click Next.

10. On the Completing the Certificate Import Wizard page, click Finish.

11. A Certificate Import Wizard dialog box might appear confirming that the import was successful. If the dialog box appears, click OK.

12. On the Certificate dialog box, click OK. The Certificate dialog box for the top node certification hierarchy will close.

13. On the Certificate dialog box, click OK. The Certificate dialog box for the subservient certificate will close.

14. On Security Alert, click No.

15. Open a browser, and then browse to the following Web site, where ApplicationTierServer is the name of the server that is running the application tier for Team Foundation and Port is the SSL port number that you assigned to the Web site for Team Foundation Server:

    https://ApplicationTierServer:Port/services/v1.0/serverstatus.asmx

    The ServerStatus Web Service page opens. This result confirms that you have installed the certificate and the certification authority correctly.

16. Close the browser.

To clear the cache on Team Foundation client computers

1. Log on to the Team Foundation client computer by using the user credentials of the user you want to update.

2. On the Team Foundation client computer, close all open instances of Visual Studio.

3. Open a browser and open the following folder:

   drive**:\Documents and Settings\username\Local Settings\Application Data\Microsoft\Team Foundation\2.0\Cache**

4. Delete the contents of the Cache directory. Make sure that you delete all subfolders.

5. Click Start, click Run, type devenv /resetuserdata, and then click OK.

6. Repeat these steps for every user account on the computer that accesses Team Foundation.

   Note

   You might want to consider distributing instructions on how to clear the cache to all of your Team Foundation users so that they can clear the cache for themselves.

See Also

Concepts

Team Foundation Server, HTTPS, and Secure Sockets Layer (SSL)

Other Resources

Team Foundation Administration Walkthroughs

Securing Team Foundation Server with HTTPS and Secure Sockets Layer (SSL)