How to: Set up a Build Agent to Require HTTPS and Secure Sockets Layer (SSL)

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.

Before configuring a build agent for SSL connections, make sure that you meet the following prerequisites:

To configure a build agent to require SSL, perform 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.

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

  6. Restart the Visual Studio Team Foundation Build service.

  7. Verify the SSL configuration.

Required Permissions

You must be a member of the Administrators group on the computer on which Team Foundation Build is installed to complete this procedure. For more information, see Team Foundation Server Permissions.

To configure the build agent to require HTTPS

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

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

  2. Click Edit.

  3. In the Build Agent Properties dialog box, select Disabled from the Agent status drop-down menu.

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 Visual Studio Team Foundation Build 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 Root:\Program Files\Microsoft Visual Studio 9.0\Common7\IDE\PrivateAssemblies, right-click TfsBuildservice.exe.config, and click Open.

    The file opens in the XML editor for Visual Studio.

  3. Change the value of the RequireSecureChannel key, which is located in the <appSettings> section, 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.

    Note

    Install the certification for Visual Studio Team Foundation Build service in the Team Foundation Build Service account’s personal store or in the Local Computer’s personal store. If you install the certificate in the personal store of logged in user, Team Foundation Build will not run.

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

    For more information, see 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 remove spaces 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. Execute 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 IP-address: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 argument /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 https://go.microsoft.com/fwlink/?LinkId=93829.

Note

If you are using Windows Vista or Windows Server 2008 operating systems, use netsh.exe instead of HttpCfg.exe. For more information about netsh.exe, see https://go.microsoft.com/fwlink/?LinkId=98790.

To configure the build agent port and protocol

  1. At the command prompt, run wcfhttpconfig freePortNumber.

    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 wcfhttpconfig reserveUserAccountURL.

    The command statement should resemble the following:

    wcfhttpconfig reserve Domain\Account https://+: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. In the Manage Build Agents dialog box, click Edit.

  2. In the Build Agent Properties dialog box, select Enabled from the Agent status drop-down menu.

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

  3. Verify whether communication is occurring by executing a build using the build agent.

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

See Also

Tasks

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

Concepts

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

Team Foundation Server, Basic Authentication, and Digest Authentication

Other Resources

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