opendev/system-config
Code Issues Proposed changes

Document gerrit openid login failure debugging

Browse Source 
This tries to cover a few common cases of Gerrit login failures.
Breadcrumbs for the future to make potential debugging easier.

Change-Id: If935601d4b102d41c186e43bf4c4b77054e48bba
This commit is contained in:
Clark Boylan 2024-01-24 08:49:51 -08:00
parent fb531dae6f
commit 5c02d66231
1 changed files with 38 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
doc/source/gerrit.rst
View File

@ -591,3 +591,41 @@ To run ``jstack`` and produce a thread dump do
root@review02 # docker exec -it gerrit-compose_gerrit_1 bash
gerrit@review02 $ ps -ef | grep java # find the Gerrit java process PID
gerrit@review02 $ jstack ${PID} > /tmp/dump.yearmonthday
Debugging Failed OpenID Logins
------------------------------
OpenID logins can fail for a number of reasons. This document does not aim
to comprehensively cover all possibilities, but does try to address some
common cases.
Contact Site Administrator Failures
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Login failures that redirect users to
``/SignInFailure,SIGN_IN,Contact+site+administrator`` occur for two common
reasons. The first is that the account has been disabled. It will need to
be reenabled before login can succeed. Second, there may be an email
address conflict between multiple accounts. This can happen if users end
up with a new OpenID url with the same email address as an existing Gerrit
account. The existing Gerrit account may have this email address set as
a preferred email address or as an external id. Addressing this usually
involves disabling the old account and removing the conflicting email
address from the old account.
Local Signature Verification Failed
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
We have seen this occur when Gerrit ends up with what appears to be an
invalid OpenID association with our OpenID provider. Inspecting the
Apache access logs at ``/var/log/apache2/gerrit-ssl-access.log`` we can
confirm the symptoms of this issue. The first thing to look for is a
new ``assoc_handle`` value in the URLs logged by apache. Second you should
see all login attempts redirect to
``/SignInFailure,SIGN_IN,Local+signature+verification+failed`` after the
``assoc_handle`` update. If these symptoms are present then restarting
Gerrit should force Gerrit to generate a new association with the OpenID
provider. In theory this new association will be functional and logins will
continue working again. We are unsure of why this happens in the first
place so it is theoretically possible multiple restarts will be required
as we may have consecutive errors.