GitLab Pages: Improve Authentication Timeout User Experience

2026-03-16 Update

Thank you all your patience as we investigated this.

We reproduced the issue and identified that the 401 error occurs when the browser-side authentication cookie expires before the user completes login. As a mitigation, we increased the timeout from 10 minutes to 60 minutes across all GitLab.com environments and confirmed this resolved the reproducible scenario. However, after monitoring production logs, the overall error rate did not change significantly, indicating that the remaining errors are driven by a condition we have not been able to reproduce.

After further investigation, our team was unable to find any other way to trigger the error. Because browsers do not send expired cookies, the server has no session information to recover, and there is no additional solution available to test. A deeper change to the OAuth flow would carry security ramifications and engineering risk for a condition we cannot reproduce or validate.

The authCookieSessionTimeout setting is available via Charts configuration. Increasing this value will address the idle login scenario.

As a result, we are marking this issue as wontfix and Closing. If you discover any other way to reproduce this error, our engineering team is happy to reopen the investigation.

Problem to solve

When GitLab Pages is configured with access control, if a user's auth_cookie_session_timeout expires, they get a raw 401 response if they try to interact with the page.

This frequently happens when a user opens a Pages URL but the cookie has expired. If they refresh the 401 page, nothing happens, but if they revisit the original URL, the page loads correctly.

This seems to be a result of a check in the code from httperrors.Serve401(w).

The 401 error page can be confusing for customers. Even if they have an active auth session through their auth provider, the error page does not make it clear that they just have a stale session and need to try again. Additionally, while a 401 unauthorized response is technically correct, a user might misinterpret as similar to 403 forbidden and assume that they don't have access to the resource.

While this might not seem like a high impact issue, we log this error around 1500 times per day on weekdays on GitLab.com (see the logs in Elasticsearch (GitLab team members only)), and at least one GitLab Dedicated customer has reported this as a significant pain point since they are heavy users of GitLab Pages with access control enabled.

Steps to reproduce:

  1. Reduce auth-cookie-session-timeout to 1 minute.
  2. In incognito window, browse private pages URL, it will be navigated to login page. Do not enter username and password
  3. Wait for more than 1 minutes to expire /auth cookie.
  4. Now enter the username and password and login.
  5. As the auth cookie is expired, user is shown 401.

Proposal

We should explore making an improvement to our flow to do one or more of the following when we find an invalid state:

  • Automatically attempt to refresh the session from the authentication provider, if it is safe to do so
  • Serve a more informative page that prompts the user to re-authenticate their session

Implementation guide

A 401 status is returned when the state is invalid from here. We can investigate the values of session.Values["state"] and r.URL.Query().Get("state") to determine whether redirecting the user to a new authentication flow, as shown here, would be viable or not.

To test locally, we can reduce authCookieSessionTimeout value.

Edited by Matthew Macfarlane