Setting up Visual Studio Team Foundation Server to Require Client Certificates

  • Article

Aaron Block

January 2009

Summary

This article describes how to set up Team Foundation Server 2008 (TFS) to require client certificates.

Applies to:

Team Foundation Server 2008

Introduction

Prerequisites

Setting up your Client Certificates

The Common Failure: Error 413

Setting up Build Services with Client Certificates

Helpful Procedures for Working with Certificates

The Basics of Certificates

How Team Foundation Server Uses Certificates

Conclusion

Introduction

This document is designed for users who want their Team Foundation Server 2008 (TFS) system to require client certificates. Client certificates provide you with an additional level of security beyond the standard user name and password combination. For more information about choosing the type and level of certificate you need, see The Basics of Certificates.

Increasing the security of your system can introduce additional complexities, which may cost more time and money, therefore, before you integrate client certificates into Team Foundation Server, you must consider whether the client certificates are necessary or if you only need server certificates. For more information about certificates, see the Microsoft Web site: Walkthrough: Setting up Team Foundation Server to Require HTTPS and Secure Sockets Layer (SSL). In the following sections, we will describe the steps required to set up server and client certificates, discuss the basics of certificates, and conclude with a discussion of how Team Foundation Server uses certificates.

Prerequisites

To force Team Foundation Server to require client certificates, you must have the following requirements in place:

  • The application tier and data tier of Team Foundation Server must be installed on your computer. You can either install them both on the same machine or each on different machines.
  • You must have permissions set to request (and be granted) certificates by a certificate authority that is trusted by your Team Foundation Server computer.
  • You must have Team Foundation Server Power Tools installed on every client computer. You can install Team Foundation Server Power Tools from the Microsoft Web site: Visual Studio Team System 2008 Team Foundation Server Power Tools.

Required Certificates

To complete these steps, you must have the following certificates:

  • Each client needs a client authentication certificate.
  • You must have a server authentication certificate for the application-tier server.
  • You must have a client authentication certificate.
    For more information about the purpose of each of these certificates, see How Team Foundation Server Uses Certificates.

Note

If you are required to set up client certificates, then it is likely that you will have one or all of these certificates. (If you are interested in using client certificates in conjunction with smart cards, it is likely that each user that has a smart card has a client authentication certificate stored on their smart card.) For more information about verifying that you have the right certificates, see the procedures To Access the Machine Store and Verify the Application Tier has a Sufficient Client Authentication Certificate and To Access the Machine Store and Verify the Application Tier has a Sufficient Server Authentication Certificate in this article.

Permissions

You must be a member of the Administrators group in Team Foundation Server and the data-tier servers. For more information about permissions, see the Microsoft Web site: Team Foundation Server Permissions.

A Warning

The application tier trusts any certificate issued by the certificate authority (CA) that has a certificate in the application tier’s Trusted Certificate Authorities certificate store. Most installations of Microsoft Windows will pre-populate the Trusted Certificate Authorities certificate store with certificates from commonly trusted certificates (e.g. VeriSign). For more information about certificates see, How Team Foundation Server Uses Certificates. For highly-secure environments, you may want to delete all certificates from this store on the application tier. For more information about removing certificates, see To Access the Machine Store and Check in or Remove a Certificate from the Trusted Root Certification Authorities in this article.

Setting up your Client Certificates

Step One: Setup Secure Sockets Layer (SSL) for Team Foundation Server

Before you can perform the set up to require client certificates, you must set up Team Foundation Server to require HTTPS and SSL. For more information about this topic see the Microsoft Web site: Team Foundation Server, HTTPS, and Secure Sockets Layer (SSL)

It is important that before continuing to the next step you verify that TFS works after SSL has been set up.

Note

You might have to reconfigure Team Foundation Server to use HTTP before you can apply service packs or other updates. You should assign different port values for the default Web site, the Team Foundation Server Web site and the SharePoint Administration Web site. It is important that the port number for the default Web site be the same number as the port number for SSL, 443.

Note

These steps are specific to IIS 6.0 and SQL 2005. If you are using IIS 7.0 or SQL 2008 you must follow a different set of steps.

For help, see Helpful Procedures for Setting Up Secure Sockets Layer (SSL) for Team Foundation Server.

Step Two: Set up Client Certificates in IIS

After you set up SSL for Team Foundation Server, you must require client certificates in IIS by following these steps:

For IIS 6.0

  1. Open Internet Information Services (IIS) Manager.

  2. Expand the node Computer Name (local Computer).

  3. Expand the node Web Sites.

  4. Right-click Team Foundation Server.

  5. Click Properties.

  6. Click the Directory Security tab.

  7. Click Edit in the Secure Communications dialog box.

  8. Click Require Client Certificates in the Client Certificates dialog box.

  9. Click OK to close the Secure Communications dialog box.

  10. Click OK to close Team Foundation Server.

  11. Repeat steps 4-10 for the default Web site and SharePoint Central Administration Web site.

    For more information about this topic see the Microsoft Web site: Enabling Client Certificates in IIS 6.0 (IIS 6.0)

For IIS 7.0

  1. Open Internet Information Services (IIS) Manager.

  2. Expand the node which has your computer’s name.

  3. Expand the node Sites.

  4. Expand the node default Web site, Team Foundation Server Web site, or SharePoint Central Administration Web site.

  5. In the Feature View pane, open SSL Settings.

  6. Select Require for Client Certificates.

  7. In the Actions pane, click Apply.

  8. Repeat steps 3-7 for all three of your sites.

For more information about SSL and IIS see the Microsoft Web site: SSL and Certificates (IIS 6.0).

Step Three: Installing a Client Authentication Certificate on the Client

Your next step is to set up, for each user, a client authentication certificate that satisfies both of the following properties:

  1. The user has a private key for the certificate.
  2. The certificate is issued by a certificate authority that is trusted by the application tier. Both conditions for the user may already be satisfied depending on how your environment is setup.

Note

If you intend to use a smart card, then it is likely that each user will have a certificate on their smart card that satisfies conditions (1) and (2). For more information about certificate set up conditions on the client see, the procedure To Access the Machine Store and Verify the Application Tier has a Sufficient Client Authentication Certificate in this topic. For more information about installation on the client see, To Request and Install a Certificate in this topic.

Step Four: Installing a Client Authentication Certificate on the Application Tier

Your next step is to set up a client authentication certificate on the application tier. You may already have a client authentication certificate installed on your application tier.) For more information about certificate set up conditions for the application tier, see the procedure To Access the Machine Store and Verify the Application Tier has a Sufficient Client Authentication Certificate in this topic. For more information about modifying certificates for the application tier, see the procedure To Access the Machine Store and Check in or Remove a Certificate from the Trusted Root Certification Authorities in this topic.

Step Five: Setting up Team Foundation Server to use a Client Certificate.

After you acquire a client authentication certificate for the application tier, your next step is to set up Team Foundation Server to use this client certificate. For more information about using Team Foundation Server client certificates, see How Team Foundation Server Uses Certificates.

To Set up Team Foundation Server to Use a Client Certificate

  1. Open the command window (type cmd in Start->Run).

  2. Navigate to the Tools directory in the Visual Studio 2008 Team Foundation Server folder (typically located in C:\Program Files\Microsoft Visual Studio 2008 Team Foundation Server\Tools).

  3. Type tfsadminutil configureconnections /clientcertificate:machine and press Enter.

  4. Click Select Certificate.

  5. Click the certificate you need to use to identify Team Foundation Server to itself.

  6. If no certificates are listed or you want a different certificate than those listed, see the procedure To Access the Machine Store and Add a Personal Certificate to the Application Tier in this article.

Step Six: Setting up Client Certificates on a Team Foundation Server Client

Your next step is to set up the client so that when the application tier is accessed the correct client authentication certificate is presented. You can use the power tool TweakUI to ensure the correct client authentication certificate is presented.

To Set up the Client for the Correct Certificate

  1. Install the current Team Foundation Server Power Tools from the Microsoft Web site: Visual Studio Team System 2008 Team Foundation Server Power Tools.

  2. Open the command window.

  3. Navigate to the folder in which the power tools are installed (typically located in, C:\Program Files\Microsoft Team Foundation Server 2008 Power Tools).

  4. Run tfpt tweakui.

  5. In the Edit Server dialog box, click the server you want to connect to.

  6. Click Edit.

  7. Change the value in the Port Number box to the appropriate value. (This is the value that you chose from the Team Foundation Server Web site in Step One: Setup Secure Sockets Layer (SSL) for Team Foundation Server.)

  8. Check the Require Secure Channel (HTTPS) box.

  9. Check the Require Certificate for Client Authentication box.

  10. Choose the certificate you want to use.

  11. Click OK.

  12. Click Apply.

Step Seven: Testing the Connection

After you have setup client certificates, it is important that your system works with both small and large file attachments. (See, The Common Failure: Error 413 if you encounter an error during this process.). A good test is to attempt to create a new project through the client.

Step Eight: Adding More Users

Now that both your server and one client have been set up, it is possible to add more users. Each additional user needs only to follow steps three, six, and seven above. Each user should verify that their system works with both small and large attachments.

The Common Failure: Error 413

The most common error encountered when setting up Team Foundation Server to use client certificates occurs when you attempt Windows SharePoint Services (WSS) file uploads, check-ins, and work item tracking updates, and has the error number 413. For reference, below is an example of the log text you may have when encountering a 413 error.

Exception Type: System.Net.WebException
Exception Message: The remote server returned an error: (413) Request Entity Too Large.
WebException: Response Status Code: RequestEntityTooLarge
WebException: Response Status Message: Request Entity Too Large
WebException: Status : ProtocolError

If this error should occur, then the value of SSLAlwaysNegoClientCert may need to be set to true on both the WSS and AT/Proxy servers. In addition, you may need to increase the value of UploadReadAheadSize on both the WSS and AT/Proxy servers to a value that is at least the maximum size of the file transferred.

To set the value of UploadReadAheadSize to 64KB on the Web server, run the command:

cscript adsutil.vbs set w3svc/1/uploadreadaheadsize 65536

To set the value of SSLAlwaysNegoClientCert to true, run the command:

cscript adsutil.vbs set w3svc/1/SSLAlwaysNegoClientCert true

For more information about this error see the Microsoft Web site: Client cannot renegotiate request and returns an HTTP 413 error. In addition, information on SSLAlwaysNegoClientCert and UploadReadAheadSize can be found at the Microsoft Web site: SSLAlwaysNegoClientCert Metabase Property and also UploadReadAheadSize Metabase Property.

Setting up Build Services with Client Certificates

In order to set up Build Services with client certificates, a few additional steps must be followed.

Step One: Set up Build Services with Server Certificates

You must first configure build services to accept server certificates by following the documentation in the Microsoft Web site: Walkthrough: Setting up Team Foundation Server to Require HTTPS and Secure Sockets Layer (SSL).

Note

In the process of completing this step, you will need to run the following commands:
wcfhttpconfig reserve Domain\Account https://+:NewPortForHttps/Build/v2.0/AgentService.asmx
The Domain\Account in your command is the domain\account for your build services account. Also, NewPortForHttps should be the port that has build services installed. For example, if your build service was installed on port 9191, and the build services account was AAA\BBB, then you need to run the following command:
wcfhttpconfig reserve AAA\BBB https://+:9191/Build/v2.0/AgentService.asmx

Note

If you have installed build services on a computer that has Windows Server 2008 installed, then instead of the command wcfhttpconfig you use the netsh command. You need to run the following command:
netsh http add sslcert ipport=0.0.0.0:9191 certhash=THUMBPRINT appid={bfbd293f-8fe8-4790-b6de-6ff1bffe0a57}
The thumbprint for the certificate that you want to use for your build services equals THUMBPRINT, (without spaces). For more information about how to access the thumbprint, see the procedure To Access the Machine Store and Access the Thumbprint in this article. One final note, the value {bfbd293f-8fe8-4790-b6de-6ff1bffe0a57} is the GUID for build services.

Note

In the referenced document, when you run the command “httpcfg” it is important that you use the flag “/f 2”.

Step Two: Set up Build Services with Client Certificates

The build agent, now with your client certificates, can be configured by following these steps:

To Set up Build Services with Client Certificates

  1. Stop the build service (go to Admin Tools-> Services, right-click Visual Studio Team Foundation Build, and then select Stop).

  2. Open the file C:\Program Files\Microsoft Visual Studio 9.0\Common7\IDE\PrivateAssemblies\tfsbuildservice.exe.config for editing.

  3. In tfsbuildservice.exe.config, change the line:

    <add key="AuthenticationScheme" value="NTLM" />

    To:

    <add key="AuthenticationScheme" value="Anonymous" />

  4. Change the line:

    <add key="RequireClientCertificate" value="false" />

    To:

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

  5. Add the following line to the file:

    <add key="VstsClientCertificate" value="thumbprint" />

    The value of “thumbprint” is the thumbprint of a client authentication certificate stored in the personal folder of the Build Server’s machine store (without spaces). For more information about how to access the thumbprint, see the procedure To Access the Machine Store and Access the Thumbprint in this article.

  6. Click Save to save your file.

  7. Start the build service.

  8. Test the account.

    Note

    If you encounter a problem, try resetting IIS on both the build agent and the application tier.

Helpful Procedures for Working with Certificates

In this section, we discuss several procedures that are useful throughout this process.

Helpful Procedures for Setting Up Secure Sockets Layer (SSL) for Team Foundation Server

To Obtain a Server Authentication Certificate for IIS 7.0

  1. Open Internet Information Services (IIS) Manager.

  2. Expand the node which has your computer’s name.

  3. In the Feature View, click Server Certificates.

  4. In the Actions pane, click Create Certificate Request…

  5. Complete the information to create a request file.

  6. Send the request file to the CA.

  7. Wait for a response from the CA.

  8. In the Actions pane, click Complete Certificate Request…

  9. Complete file location and friendly name.

  10. Click OK.

If you are using IIS 7.0, then to install the server certificate on the default Web site, Team Foundation Server Web site, and the SharePoint Central Administration Web site follow these steps:

To Install the Server Certificate with IIS 7.0

  1. Open Internet Information Services (IIS) Manager.

  2. Expand the node which has your computer’s name.

  3. Expand the node Sites.

  4. Expand the node for default Web site, Team Foundation Server Web site, or SharePoint Central Administration Web site.

  5. In the Actions pane, click Bindings.

  6. Click Add.

  7. Choose the type as https, verify that the IP Address is set to All Unassigned, and chose an appropriate port number. (You can use the command netstat –an to check all assigned ports.)

  8. Under SSL Certificate, choose the same certificate for all three of your sites.

  9. Click OK.

  10. Click Close.

  11. In the Feature View pane, open SSL Settings.

  12. Click Requires SSL.

  13. Check the Ignore check box for Client Certificates (later we will turn this on).

  14. In the Actions pane, click Apply.

  15. Repeat steps 4-14 for all three of your sites.

If you are using SQL 2008, configure Report Server for SSL Connections by following these steps:

To configure Report Server for SSL Connections in SQL 2008

  1. Click Start, point to Reporting Services Configuration Manager.

  2. Open Microsoft SQL Server 2008 and click Configuration Tools.

  3. Connect to the appropriate database.

  4. In the Connect pane, click Web Service URL.

  5. In the Web Service URL, under Report Server Web Service Site Identification, choose the appropriate SSL Certificate and choose an SSL Port that is the same as the port chosen for the default Web site.

  6. Click Apply.

  7. Close the Reporting Services Configuration Manager program.

Additional Procedures

To Verify Client Authentication Certificate Permissions

  1. If you are using a smart card, insert it now.

  2. Open the Certificate Manager.

    Click Start, click Run and type certmgr.msc.

  3. Expand the node Personal.

  4. Find the certificate that has client authentication listed as one of its intended purposes. (If you do not have a certificate listed that has client authentication as one of its intended purposes, then you do not have a certificate that is sufficient for setting up client certificates in Team Foundation Services. You must now follow the steps in the section To Request and Install a Certificate in this article.)

  5. Double-click on the certificate you have chosen.

  6. At the bottom of the General tab, ensure that the phrase “You have a private key that corresponds to this certificate,” appears.

  7. Click the Certification Path tab.

  8. Ensure that each certificate (each of which represents a certificate authority) in the Certification Path tab (except for the bottom node) is trusted by the application tier. For more information about this topic, see the procedure To Access the Machine Store and Check in or Remove a Certificate from the Trusted Root Certification Authorities in this article.

  9. If either step 6 or step 8 is not true, then you do not have a sufficient certificate, and you must either try a different client authentication certificate or follow the steps in the section To Request and Install a Certificate in this article.

To Request and Install a Client Authentication Certificate

  1. Open the Certificate Manager.

    Click Start, click Run and type certmgr.msc.

  2. Expand the node Personal.

  3. In the Certificates window, click Action.

  4. Point to All Tasks, click Request New Certificate.

    Follow the steps to acquire a new certificate. Verify that the certificate you request can be used for client authentication.

To Access the Machine Store and Verify the Application Tier has a Sufficient Client Authentication Certificate

  1. Open the Microsoft Management Console (MMC).

    Click Start, point to Run and type mmc.

  2. Click File then click Add/Remove Snap-in...

  3. Double-click Certificates in the Available Snap-ins box.

  4. Click Computer Account.

  5. Click Next.

  6. Select Local Computer.

  7. Click Finish.

  8. Click OK.

  9. Expand the node Personal.

  10. Click Action in the Certificates window.

  11. Find the certificate that has client authentication listed as one of its intended purposes. (If you do not have a certificate listed that has client authentication as one of its intended purposes, then you do not have a certificate that is sufficient for setting up client certificates in Team Foundation Server. You must now follow the steps in the section To Access the Machine Store and Add a Personal Certificate to the Application Tier in this article.)

  12. Double-click the certificate you have chosen.

  13. At the bottom of the General tab, ensure that the phrase “You have a private key that corresponds to this certificate,” appears.

  14. Click the Certification Path tab.

  15. Ensure that in the Certificate Status window the phrase “This certificate is OK,” appears.

  16. If either step 14 or step 16 is not true, then you do not have a sufficient certificate, and you must either try a different client authentication certificate or follow the directions in the procedure To Access the Machine Store and Add a Personal Certificate to the Application Tier in this article.

To Access the Machine Store and Verify the Application Tier has a Sufficient Server Authentication Certificate

  1. Open the Microsoft Management Console (MMC).

    Click Start, point to Run and type mmc.

  2. Click File then click Add/Remove Snap-in...

  3. Double-click Certificates in the Available Snap-ins box.

  4. Click Computer Account.

  5. Click Next.

  6. Select Local Computer.

  7. Click Finish.

  8. Click OK.

  9. Expand the node Personal.

  10. Click Action in the Certificates window.

  11. Find the certificate that has Server Authentication listed as one of its intended purposes. (If you do not have a certificate listed that has Server Authentication as one of its intended purposes, then you do not have a certificate that can be used for Server Authentication. You must now follow Step 17 to acquire such a certificate.)

  12. Double-click the certificate you have chosen.

  13. At the bottom of the General tab, ensure that the phrase “You have a private key that corresponds to this certificate,” appears.

  14. Click the Certification Path tab.

  15. Ensure that in the Certificate Status window the phrase “This certificate is OK,” appears.

  16. If step 12, 14, or 16 is not true, then you do not have a sufficient certificate, and you must either try a different Server Authentication certificate or obtain a server authentication certificate (If you are using IIS 6.0, see, the Microsoft Web site: Walkthrough: Setting up Team Foundation Server to Require HTTPS and Secure Sockets Layer (SSL). Alternatively, if you are using IIS 7.0, then see, Helpful Procedures for Setting Up Secure Sockets Layer (SSL) for Team Foundation Server.

To Access the Machine Store and Add a Personal Certificate to the Application Tier

  1. Open the Microsoft Management Console (MMC).

    Click Start, point to Run and type**mmc.

  2. Click File then click Add/Remove Snap-in...

  3. Double-click Certificates in the Available Snap-ins box.

  4. Click Computer Account.

  5. Click Next.

  6. Select Local Computer.

  7. Click Finish.

  8. Click OK.

  9. Expand the node Personal.

  10. Click Action in the Certificates window.

  11. Point to All Tasks, click Request New Certificate.

  12. Verify that the certificate you request can be used for client authentication.

To Access the Machine Store and Check in or Remove a Certificate from the Trusted Root Certification Authorities

  1. Open the Microsoft Management Console (MMC).

    Click Start, point to Run and type mmc.

  2. Click File then click Add/Remove Snap-in...

  3. Double-click Certificates in the Available Snap-ins box.

  4. Click Computer Account.

  5. Click Next.

  6. Select Local Computer.

  7. Click Finish.

  8. Click OK.

  9. Expand the node Trusted Root Certification Authorities.

  10. Open the folder Certificates. All the certificates in this folder represent the root certificate authorities that are trusted by this computer.

  11. To delete a certificate, right-click on the certificate and click Delete.

To Access the Machine Store and Access the Thumbprint

  1. Open the Microsoft Management Console (MMC).

    Click Start, point to Run and type mmc.

  2. Click File then click Add/Remove Snap-in...

  3. Double-click Certificates in the Available Snap-ins box.

  4. Click Computer Account.

  5. Click Next.

  6. Select Local Computer.

  7. Click Finish.

  8. Click OK.

  9. Expand the node Personal.

  10. Double-click the certificate that you want to examine.

  11. The Details tab contains the Thumbprint.

  12. Before using the Thumbprint to set up the build service with client certificates you must remove all empty spaces.

The Basics of Certificates

Certificates are one of the primary methods you can use to ensure your security on the Internet. A certificate is an electronic signature that has two purposes; one, to verify communication and two, to keep your communications private. A certificate can be used to verify the origins of an e-mail message as well as guarantee that only an intended source will be able to read the e-mail message.

Certificates consist of two components; one is a public key and two is a private key. The public key is accessible to anyone and the private key is only known to the certificate owner. When the certificate owner (CO) sends an e-mail message, they can sign their message with their private key. Another user can then verify that this e-mail message originated from the CO by using the public key. Similarly, if a user wants to verify that only the certificate owner can read the e-mail message, then a user can encrypt their message using the CO’s public key, which guarantees that the only way to decrypt the message is to use the CO’s private key.

Figure 1: Possible scenario when CA-PRIME is compromised

Dd407788.9521b494-cd2a-445d-be24-652a765a5191(en-us,VS.90).png

Certificates are generated by a certificate authority (CA). Each key is only as valid as the CA that generated it so, it is important to note that if a CA is compromised, then the certificates it generates cannot be trusted. For example, suppose that CA-PRIME is the primary CA for a company. If a hacker, such as Alice, compromised CA-PRIME, she could then create a fake certificate for herself in which she claimed to be Bob. Alice could then send an e-mail message to the employee Carl and sign it as Bob using her fake certificate. Carl would then go to CA-PRIME and ask for Bob’s certificate. Since Alice compromised CA-PRIME, Carl would get Alice’s fake public key. Carl would believe that the e-mail message came from Bob. Notice that this works even if Bob doesn’t have a certificate from CA-PRIME. As long as Carl trusts CA-PRIME, he will trust that the public key he gets from CA-PRIME belongs to Bob. Such a scenario is illustrated in Figure 1.

How Team Foundation Server Uses Certificates

The standard client certificate-enabled Team Foundation Server Setup with one client and one application tier uses three certificates. The client computer has a client authentication certificate that is used to verify its identity to the server. The server has a server authentication certificate that is used to verity its identity to clients. Additionally, the server has a client authentication certificate to verify its identity to itself. The reason the server needs to verify its identity to itself is because the server issues Web calls as the service account. Since the server is set up to require client certificates from all incoming Web calls, the server must have a client certificate for communicating.

Conclusion

This article has discussed how to setup TFS to require client certificates. In addition, this document discussed some of the basic principles associated with certificates.