How to authenticate build.vnext agent to on-premise TFS

Question

We have an on-premise TFS2015RC installation. The server is part of our domain.

When configuring a build agent (build.vnext) on another server in the same domain, everything works as expected.

However, when configuring a build agent on a server outside of this domain, the following happens:

Using ConfigureAgent.ps1:

1. accept all defaults
2. choose interactive mode (e.i. not installed as Windows Service)
3. then an authentication dialog shows up:
   • I enter a domain user (domain\user) which is administrator of TFS
   • I provide the domain password for this user. If the password is wrong, the dialog will say so and I need to correct it (default behavior in Windows)
4. The script proceeds, but after starting the agent it says:

ERROR:
VS30063: You are not authorized to access http://{server}:8080/tfs

Why is the authentication failing? How can I find out with which user it is trying to authenticate?

I have tried:

• looking at the logfile in the _diag folder. The log file states exactly the same, without more usable info.
• tried the advice from this link to enable Basic Authentication on IIS on the TFS server. I did this (reluctantly) but it does not resolve the issue.

Answer 1

OK I managed to resolve the issue like this:

1. create a user TFS\remotebuild on the TFS server
2. gave this local user access to the TFS Agent Pools
3. gave this local user access to TFS Source Control
4. created a user BUILD\remotebuild on the Build server with same password as TFS\remotebuild
5. when running the build agent configuration script, when it ask for the service accounts, choose the BUILD\remotebuild user
6. when it ask for TFS authentication, provide the TFS\remotebuild user credentials

Like this, it is working! However, I somehow cannot get it to run in "console mode" (i.e. not starting it as a windows service). This is not a big issue.

There was one small issue after this: in the logfile I could see it was trying to connect to http://NAME-OF-TFS:8080/tfs instead of http://IP-ADDRESS:8080/tfs, but I could resolve that issue by adding a line to the hosts file on the build machine.

Answer 2

Identities

This potentially involves up to three different identities, defined below:

• PoolAdmin - The account used to add the agent to the agent pool. This user must be part of the Agent Pool Administrators role for the pool that you want to use.
• TfsServiceAccount - The account that the agent should use to connect to TFS. This account should belong to the Agent Pool Service Accounts role for the pool that you want to use. Although the docs indicate that this role membership should be established automatically, that may not be the case in this workgroup scenario.
• LocalServiceAccount - The service account under which the agent will run on the build agent machine. This may be either a local account or an account on a second domain, depending on your configuration.

Note: Depending on how your TFS instance is set up, the first two might end up being the same account.

Configuration

Follow the steps below to configure the agent. These steps assume you've already unzipped the agent software to C:\agent.

1. Log on to the build agent machine as LocalServiceAccount.
2. Remove any saved credentials for the TFS server.
   • Open Control Panel > User Accounts > Credential Manager.
   • Click Windows Credentials.
   • Delete any saved credentials for your TFS server.
3. Delete C:\agent\settings.json, if it exists.
4. Open an administrative command prompt to C:\Agent and run ConfigureAgent.cmd.
5. Follow the prompts. When prompted to install as a service, enter Y.
6. When prompted for the user account, enter the credentials for LocalServiceAccount.

7. When you see the pop up prompt to authenticate to TFS, enter the credentials for PoolAdmin. Important: Uncheck the Remember my credentials checkbox.

   If PoolAdmin and TfsServiceAccount are the same, instead you can remember the credentials and skip the remaining steps.

8. Stop the VSO Agent service.

9. Using Internet Explorer, open the URL to your TFS server.
10. When prompted to authenticate to TFS, enter the credentials for TfsServiceAccount. Important: This time, check the Remember my credentials checkbox.
11. Start the VSO Agent service.

Your new agent should now be listed in the pool as online.

References:

• Deploy an agent on Windows

• Administer your build and deployment system on TFS 2015