Configuring Session Timeout in TeamCity

Question

How can I configure the timeout setting for automatically logging out a user from the TeamCity UI after a period of inactivity?

Answer

TeamCity has no dedicated UI option for automatic logout. You configure it with a Tomcat HTTP session timeout plus cookie settings that stop the session from being silently renewed. The session timeout on its own is not enough: while a TeamCity tab is open, the UI's periodic background requests and the auto-renewing "Remember me" cookie keep the session alive, so it never actually expires. Apply all three steps below together.

1. Set the session timeout and cookie lifetime (web.xml)

<session-timeout> sets the server-side inactivity timeout. Add a <cookie-config> <max-age> as well: the JSESSIONID cookie has no explicit max-age by default (it lasts for the browser session), so the browser keeps presenting it and the session outlives the timeout.

1. Open <TeamCity_home>/webapps/ROOT/WEB-INF/web.xml.

2. Back up the file before editing.

3. Find the <session-config> section (add it if it is not there) and set both values:

   <session-config>
       <session-timeout>30</session-timeout>    <!-- minutes -->
       <cookie-config>
           <max-age>1800</max-age>              <!-- seconds; keep aligned with session-timeout -->
       </cookie-config>
   </session-config>
   

   The example is 30 minutes. Replace both values with your own window, noting the different units: <session-timeout> is in minutes, <max-age> is in seconds.

2. Stop the "Remember me" cookie from renewing the session (internal.properties)

By default, the "Remember me" cookie lasts 14 days and is renewed on every HTTP request, so it logs the user back in after the HTTP session expires. Configure it in <TeamCity Data Directory>/config/internal.properties:

teamcity.user.rememberMe.setOnExplicitLoginOnly=true   # stop prolonging the cookie on each request
teamcity.user.rememberMe.maxAge.seconds=1800           # cookie expiry in seconds; align with the window above
teamcity.user.rememberMe.checkedByDefault=false        # do not pre-tick "Remember me" on the login form

Set teamcity.user.rememberMe.setOnExplicitLoginOnly and teamcity.user.rememberMe.maxAge.seconds together; setOnExplicitLoginOnly has no effect on its own. Unlike web.xml, internal.properties lives in the Data Directory and survives upgrades.

3. Restart the server

Restart TeamCity for the changes to take effect.

Important notes

• The web.xml file ships with TeamCity and is overwritten on upgrade, so re-apply the <session-config> edit after each upgrade. The internal.properties settings persist.
• This setup enforces an absolute window, not pure inactivity. The TeamCity UI sends periodic background (AJAX) requests that keep resetting the inactivity clock while a tab is open, so users are logged out a fixed period after login regardless of whether they were active.