Configuring Team Foundation Server to use fully-qualified domain names

This week the following question came up.  I've seen this come up before, and there are probably forum threads on it, but I figured I'd post it here.  Bill Essary provided the answer to the question.  As always, keep notes on what you do so that you can undo it if necessary.


Is there a way to configure TFS to use fully-qualified domain names (FQDN, e.g., for TFS, WSS, and Reporting Services?


1) Run "tfsadminutil activateat <FullyQualifiedDomainName>"

2) Update the following registry key with the FQDN: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\8.0\TeamFoundation\ReportServer

3) To force FQDN references in e-mail notifications, set TFSUrlPublic in the TFS root web.config file to http://<FQDN>:8080.

There are a handful of other places where the TFS URL is stored, but they typically wouldn't matter if the goal is to ensure that all public access to the server is done via FQDN.  The ones that are missed govern communication local to the TFS AT (ex: TFS scheduler prodding TFS warehouse).  If you want to get them all, use the SSL-only configuration topic for TFS as a guide.

4) Add the domain to the Intranet Zone or Trusted Sites list in IE for all clients (see KB 303650)

If you are using TFS 2008 with SharePoint 3.0 (or Microsoft Office SharePoint Services 2007), you will need to do the following as well.

After following the steps above with TFS2008 + WSS 3.0 you will observe that when you try to access the team portal using http://FQDN/sites/TeamProjectName you will be automatically redirected to http://NETBIOSNAME/sites/TeamProjectName. 

This behavior is by design and is caused by alternate access mapping. In order to avoid this you will have to create a custom alternate access mapping which has the FQDN as the internal URL and as the public URL.

  1. Open WSS3.0 Central Administration
  2. Click on Operations tab
  3. Click on Alternate access mapping
  4. Click the Add Internal URLs button
  5. In the dropdown select the default website (port 80)
  6. Enter the FQDN in the textbox
  7. Set the Zone to Custom

Additional step required when .NET 3.5 SP1 is installed 

If you have Service Pack 1 for .NET 3.5 installed on your 2008 server (and if you do, make sure you also have SP1 for TFS 2008 installed), you will need to make an additional change.  KB 926642 describes what you will need to do.  The registry change is probably the simplest approach, but you will need to decide which approach is best for you based on the security tradeoffs.

The need for this setting is due to the fact that .NET 3.5 SP1 includes changes to support Windows' features to defeat reflection attacks.  Unfortunately, that causes problems with the way FQDN support works in TFS.  You can find additional background on the Windows' security settings at Getting Caught by Loopback.  You can also read about the impact on SQL Reporting Services at Reporting Services HTTP 401 (Unauthorized) - Host Headers require your attention.

[UPDATE February 27, 2008] Ladislau Szomoru provided additional steps required when making this change with TFS 2008 and SharePoint 3.0.

[UPDATE October 17, 2008] I've added information about handling the new security checks enabled by .NET 3.5 SP1 that will prevent FQDN from working without taking additional steps.

tags: ,

Comments (19)

  1. Amadeu Campanelli on VSS to TFS Migration – A Start. Buck Hodges on Version Control Server blog: Orcas…

  2. Dennis van der Stelt says:

    Check out Mike Glaser his weblog on FQDN and TFS/SharePoint and more! His weblog has great tutorials on how to enable it and much more!

  3. Buck, we gave this a try and for the most part it worked fine.  The one issue we’re running into right now though is in Team Explorer we’re seeing the dreaded big red "X" on "Documents."  Oddly enough when we’ve seen this before (can’t remember exactly when) but it seemed to affect both "Reports" and "Documents."  This time it’s just "Documents."

    What is also odd is we can connect fine via Teamprise and targeting the site via IE works perfect.  We can also load "Documents" when running Team Explorer right on the App Tier (just for testing).

    Could we have missed some update that needs to be made for SharePoint?  We did the Reporting Services reg hack as you suggested so I’m wondering if a similar act needs to take place for SharePoint?

  4. Bill Essary says:

    The dreaded big red “X” on the Documents and Reports node is often due to a problem with absolute URL information for those services stored in TFS registration data.  The tfsadminutil command should have updated the machine name component of the URLs that we store in registration data both for SharePoint and for Reporting Services.  To check, open IE on the TFS AT and invoke the GetRegistrationEntries web method with no parameters at using http://<server>/services/v1.0/registration.asmx.  You should find the FQDN stored in five URLs in that XML document.  Two of the references will be in a SSRS section and three will be in a section that describes where the SharePoint services live.  If the URLs are wrong for some reason, the TFS topic on configuring a system for SSL will tell you how to edit them (we have to update the protocol information in that case, not the machine name).  I suspect that you will find that the URL for SharePoint was properly updated since the Reports change seems to have worked as expected.  In that case, we have to look elsewhere for the red X on the Documents node.  One explanation would be the client-side cache of registration data.  The update may take up to two hours to show up on the client without manual intervention – registration data normally does not change too often.  The other thing that could be happening is that the red X appears because the account used on when testing from the client does not have access to all of the document libraries in SharePoint.  Try using the same account if you weren’t already or verify that it is possible to access every document library in the top-level site associated with the team project (http://<server>/sites/<teamprojectname&gt;.

  5. Thanks for the response Bill!  I checked the URL values after evoking the Registration web service and all values are correct (i.e.

    We made this change yesterday so I’m thinking the client cache is refreshed.  Just to make sure I deleted everything under "C:Documents and Settings<myusername>Local SettingsApplication DataMicrosoftTeam Foundation1.0Cache".  I also had a colleague try to get in and he is getting the exact same behavior.

    We both are able to use SharePoint via IE (http://<server>/sites/<teamprojectname&gt;) with the same user accounts.  We are also able to connect with Teamprise just fine.  It seems like the issue is isolated to team explorer.

    Are there any logs we can look at?  I see nothing in the Event Viewer on either the client or server side.  The exception has be logged someplace right?

  6. Here is some more information I found when digging through some logs.

    1)  This is the ISS log when running locally on the App Tier and it works.

    2007-04-13 21:59:58 W3SVC1 EE-MYSERVER-B01 111.321.87.99 POST /_vti_bin/Lists.asmx – 80 ….

    2)  This is the ISS log when running from a client machine that does not work.

    2007-04-13 22:02:07 W3SVC1 EE-MYSERVER-B01 111.321.87.99 POST /sites/STK/_vti_bin/Lists.asmx – 80 ….

    I wonder why running from the client we get "/sites" while running from the App Tier we don’t?

  7. Bill Essary says:

    It is not enough to just be able to see the top-level site for a project to avoid the dreaded big red "X", you actually have to have rights to view the contents of every document library in the site.  The way to test this is to just click on the Documents link at the top of the quick launch section of the site (near the upper left corner normally).  You will get a list of all document libraries.  Click through to view the contents of each one.  If you get access denied or any other error in this process, that will roll-up in the Team Explorer as a red "X" on the top level Documents node.  That issue has been fixed for in the upcoming Orcas release, but it is still present in SP1.

  8. says:

    I’ve clicked through each of the Documents (e.g. Development, Requirements, etc.) and they all work just fine with IE and Teamprise. I’m able to add/edit/delete items just fine.

    Any other things we can check?  I’ll note that we’re running only V1.0 as our backend Data Tier is a cluster and we’re waiting for the install patch to SP1 for clustered Data Tiers.

    I’m still curious why the App Tier works and has /_vti_bin/Lists.asmx in the IIS log while the Client machine does not work at has /sites/STK/_vti_bin/Lists.asmx in the IIS log.

    1)  This is the ISS log when running locally on the App Tier and it works.

    2007-04-13 21:59:58 W3SVC1 EE-MYSERVER-B01 111.321.87.99 POST /_vti_bin/Lists.asmx – 80 ….

    2)  This is the ISS log when running from a client machine that does not work.

    2007-04-13 22:02:07 W3SVC1 EE-MYSERVER-B01 111.321.87.99 POST /sites/STK/_vti_bin/Lists.asmx – 80 ….

    3)  This is the ISS log when running from a client machine using Teamprise or IE that does work

    2007-04-13 21:59:58 W3SVC1 EE-MYSERVER-B01 111.321.87.99 POST /_vti_bin/Lists.asmx – 80 ….

  9. Mike's Blog says:

    Since Brian Keller and Brian Harry requested me to test Configuring Visual Studio 2005 Team Foundation

  10. 1)  The Red X on the Documents was solved by putting ** in IE’s list of local websites to exclude from the web proxy server.  * worked for SharePoint, Teamplain, and Teamprise, but Visual Studio needed ** to connect?  Why?  I’m not 100% sure, but I’ve left my hypothesis on the following forum.

    2)  In Buck’s Step 3 I’m not sure if it’s the TFSUrlPublic value that needs to be changed.  Instead we set the TFSNameUrl value to get alerts to use the FQDN.  E.g. <add key="TFSNameUrl" value="; />

  11. Bill Essary says:

    Most people should not find it necessary to explicitly manage the proxy list when moving TFS to a FQDN.  As I understand Mac’s environment, there was a hardware load balancer in the equation that may have contributed to the difficulty of getting this to work cleanly.  Still, Mac’s experience is worthy of note – take the instructions as a rough guide and test before implementing this in a production environment.

    The update of TfsUrlPublic as listed in step 3 is correct.  That will change the server name used in links that are included in e-mail notifications generated in response to events.  Updating TfsNameUrl should not hurt as long as the FQDN can be resolved by the server itself, but it also should not be necessary.  

    It is important to note that there are effectively two flavors of a URI update for TFS.  One is what we might call a “shallow” update.  In that one, we strive to change the public face of TFS by editing a handful of URIs that impact the protocol/servername/port that we show to client machines.  That is what you get when following the topic which describes how to configure TFS to run using SSL (  The other flavor is a “deep” update.  In that one, we also change how server-to-server communication paths are configured.  To get a feeling for the difference, compare the previous SSL configuration topic with the topic on configuring TFS to use SSL-only (  The “only” is key – it means that server to server communication will be forced down the SSL path as well as external HTTPS connections.  That is when we start to touch things like TFSNameUrl.

    I did ask Buck to add a fourth step to these instructions to address issues that some may encounter when moving TFS to a FQDN.  The presence of periods in the address can cause access to resources on the server to be treated differently than when using a NetBIOS name.

    Finally, Mike pointed out in a blog post that referenced this one that there were limitations to the instructions.  Specifically, he noted that the simple set of three instructions (now four) would not accommodate semi-custom deployments of TFS where SharePoint was hosted on a separate machine.  That is right.  The instructions posted here will only work on a standard single or dual server deployment of TFS.

  12. Bill Essary says:

    A few TFS team members investigated the difficulties that Mac reported with the proxy bypass list.  They found that there is a difference between IE and System.Net (which TFS uses) handling of the proxy list.  Here is an explanation:

    1) IE’s bypasslist contains strings that describe server addresses that “START WITH” So technically, http://<servername&gt;:8080/Services/v1.0/ServerStatus.asmx?op=CheckAuthentication

    qualifies and IE works fine

    2) System.Net converts the IE expressions (Shell Expressions) into .NET regular expressions for bypasslist.  As such, <servername> is turned into “<servername>$” which in .NET regular expressions

    means any string that ENDS WITH <servername>. So the host:port combination <servername>:8080 does not qualify and does not match and hence the proxy is used – instead of bypassing it.

    In this case IE and System.Net behaves differently. This is the problem that Mac was seeing.

    3) When you enter <servername>* into the IE, you get the .NET reg ex as <servername>.*$ and hence the IE and System.Net works fine. Although this is a workaround, this is not intuitive

  13. A while back I promised to blog about how to configure TFS with fully qualified domain names (particularly

  14. Today I decided to create a TFS 2008 VPC environment using Windows Server 2008 and SQL 2008. In general

  15. gary says:

    I am attempting to upgrade to TFS 2008. the documentaion states "Before you upgrade a deployment that is configured with FQDNs, you must first reconfigure it to use either computer names or IP addresses".

    How do i do this?

  16. buckh says:

    Gary, it should just be the reverse of the steps documented at


  17. Gary says:

    Buck, thanks for the information.

  18. This is strange – my Default Web Site where my TFS Sites collection is working perfectly with fqdn/ssl, reports working etc etc.  But calls to the TFS Website and Central Admin site which I’ve also attempted to expose via fqdn/ssl come back page cannot be found.  I added firewall exceptions on the server, still can’t access the tfs services or central admin.  Everything works locally, but only TFS Sites work remotely outside of network.  Thoughts?

  19. Aaron Block says:

    Hi Andrew,

    Can you shoot me an e-mail, and I’ll see if I can help you (ablock[~~~at~~~]microsoft[~~~dot~~~]com)?



Skip to main content