Introducing TeamCity RunAs Plugin
When building, testing, and deploying an application with TeamCity, you may need to run a build under a specific user account, different from the one used to run the build agent.
TeamCity RunAs Plugin Overview
The teamcity-runas plugin can be used to run TeamCity build steps under a specified user account on Windows or Linux.
The plugin is compatible with TeamCity 10.0 and later.
Installing Plugin
System Administrators can download the runAs.zip from here and install it on the TeamCity server as usual.
Configuring TeamCity Agents
On Windows
The teamcity-runas plugin requires the TeamCity agent’s account to have certain permissions. Depending on the way you run the agent, granting additional privileges may be required.
- If you are running the TeamCity agent as a Windows service under the Local System account, it has all required permissions and the teamcity-runas plugin works out-of-the-box.
- If you are starting the agent as a Windows service using a specified Windows account (for example AgentUser), it must have administrative privileges, must have the ability to replace a process level token (SeAssignPrimaryTokenPrivilege), and act as a part of the operating system (SeTcbPrivilege) or needs to work under the Local Service account. These privileges can be added via a security policy using Control Panel | Administrative Tools | Local Security Policy | Local Policies | User Rights Assignment | Replace a process level token. See Microsoft documentation for details.
You can also do it using the provided scripts, e.g.:runGrantAccess.cmd BuildUser.The changes will not take effect until the next login, so you’ll have to restart the agent.
- If you are starting the TeamCity agent as a Windows console application, your Windows user account must have administrative privileges.
On Linux
- With Debian/Ubuntu/Linux, the recommended setup is to run the TeamCity agent as ROOT, as in this case the account has all the required privileges and the teamcity-runas plugin works out-of-the-box (see the related section below).
- If you run the TeamCity agent as a user different from ROOT, you need to install socat using the following command:
sudo apt-get update && sudo apt-get install socat
Using Plugin
After the server restart, the plugin provides the Run As build feature and you can add it to your build configuration specifying the username and password.
For Windows the following username formats are acceptable:〈username〉or〈username@domain〉or〈domain\username〉.
For Windows-based build agents it is possible to specify the Windows Integrity Level, the logging level, and additional arguments.
Once the build is run, the plugin will run all the commands under the specified user account.
Checking Account Used to Run Build
You can enable the teamcity.runAs.log.enabled= true parameter of a build configuration (set to “false” by default) and TeamCity will print the required information into the build log.
If the credentials are invalid, the build fails with “Authentication failure” error:
Alternatively, to make sure the teamcity-runas plugin is configured properly, you can get the user whose account was used to run the build by checking the environment variables: USERNAME (for Windows) / USER, LOGNAME (for Linux).
For example, you can add a command line build step with the set USERNAME command on Windows / echo "$USER" echo “$LOGNAME” on Linux. This will print the user whose account was used to run the build into the log.
Accessing Files created by RunAs User
It is important to note that when running a build under a specified user account, all processes run in the environment specific for this user.
It means that all files created during the build (e.g. compiled classes, object files, executables, dlls, Gradle/Maven cache files, TeamCity artifacts, some test statistics and so on) will have the teamcity-runas user as the file owner.
The TeamCity agent must have the full control over the files created in the build checkout directory and ideally, over files in other locations, e.g. m2 or .gradle directories as well. Depending on the way you configured the agent (see Configuring TeamCity Agents above), the access level will differ and granting additional permissions may be required.
For Windows, the account with administrative permissions used to run the TeamCity build agent will have sufficient rights to manage the files.
For Linux, if the TeamCity agent is not running under ROOT, it may encounter problems accessing artifacts in the build checkout directory. In this case the necessary permissions can be granted by running the following command:
chmod -R a+rwX %teamcity.build.checkoutDir%.
It can be added as the last step of the build executed under the ‘Run As’ user.
Install the plugin on your TeamCity server, give it a try, and let us know what you think about it.
Happy building!
The TeamCity Team
Subscribe to TeamCity Blog updates
