TFS 2017 build agent in untrusted domain

This week I was faced with a scenario where a TFS build/release agent was used to deploy software from TFS Release management. This agent was running in the same Windows domain as the servers where the software needed to be deployed. The TFS server itself was running in a different Windows domain. Because of security considerations (these are production servers we’re talking about), these two Windows domain did not have a domain trust configured between them.

So how to authenticate the build agent to the TFS server? In the past (TFS 2015 and before), you would have to configure shadow accounts by creating service accounts on the TFS server and each and every build agent, with identical usernames and passwords. While this works, it has two major problems:

1. You need to manage these accounts on all servers separately, making enforcing of password policies and such difficult.
2. If you need your build agent to do stuff (like copying files, creating websites, etc) on servers in the target domain, you’ll probably want to run the agent as a domain account, so that you can easily authenticate on your target servers.

Unfortunately, before TFS 2017 it was not possible to run your build agent under a domain account, and authenticate to a TFS server running in a different, untrusted, domain.
This is a fairly common scenario, and there wasn’t a really good solution. Until now! With TFS 2017, Microsoft has made it possible to use Personal Access Tokens (PAT) for on-premise deployments (VSTS has had this concept for quite a while already).

Using a PAT to authenticate a build agent

In order for this to work, you’ll need to run your TFS server on HTTPS. Fortunately the TFS 2017 configuration wizard lets you easily configure this. Make sure that you’re using a SSL certificate that’s trusted on the build agents as well as on all clients, or you’ll be treated to some nasty certificate errors.
Once you have your TFS up and running on HTTPS, you can go ahead and configure your build agent. To get going, start by generating a PAT from the security settings:

Try to minimize the amount of selected scopes for each PAT that you create, to minimize security risks. For installing a build agent, the only required scope is “Agent Pools (read, manage)”:

Copy / paste the generated PAT and store it somewhere safe (like in a password safe). If you lose it, there is no way to retrieve it. You’ll have to generate a new one. By the way: this PAT is only needed when registering a new build agent to TFS. Once the build agent is up and running, you don’t need the PAT anymore, and you could even revoke it.
On the build agent, download and extract the build agent bits. Then, start the configuration by running “.config.cmd”. Enter the following:

• Server URL: the URL to the root of your TFS server, so without the “/DefaultCollection” bit. Remember, this needs to be a HTTPS URL.
• Authentication type: PAT
• User account to use for the service: enter an account in the domain where the agent will be running.
• The rest of the options should be fairly self explanatory

The result is a running build agent, using a domain account as the service account. In my case, I have the build agent running in domain TFS-LAB-BUILD, connecting to a TFS server running in the TFS-LAB domain:

The agent also shows up in the “Agent pools” section of the TFS web administration:

There you have it! I hope this helps!
Happy building!