Thanks to visit codestin.com
Credit goes to chromium.googlesource.com

Google Git
Sign in
chromium / chromium / src / main / . / docs / gerrit_reauth.md
blob: 983a61b83f468448345852d41796c5cdbff08719 [file] [log] [blame] [view]
Jiewei Qiand76b2b332025-08-29 01:37:40[diff] [blame]1# Gerrit ReAuth
2
Jiewei Qian68acdc82025-09-30 08:16:56[diff] [blame]3*** note
4**Googlers:**
5
6If you use your @google.com account, or a @chromium.org account linked to your
7@google.com account: You already ReAuth during your daily `gcert`, no further
8action is required. Feel free to stop reading now.
9
Jiewei Qian268dc132025-10-15 04:34:17[diff] [blame]10If you use a @chromium.org account that isn't linked to your google.com account,
11with a Google-issued security key, on devices managed by Google (e.g. gLinux),
12simply run `git credential-luci reauth`, follow the prompts to complete ReAuth.
13You need to ReAuth every 20 hours (just like `gcert`).
14
Jiewei Qian91bc65f2025-10-21 03:51:13[diff] [blame]15If you use a terminal persistence tool, such as screen, tmux, or shpool, refer
16to [the internal guide](go/gerrit-reauth#bookmark=id.gohr0ejjvi49) for
17additional instructions.
18
Jiewei Qian68acdc82025-09-30 08:16:56[diff] [blame]19Otherwise, follow this guide to ReAuth locally or remotely.
20
21If you aren't sure if your account is linked, follow
22[the steps here](http://go/chromium-account-support#how-can-i-check-if-my-gerrit-accounts-are-linked).
23
Jiewei Qian268dc132025-10-15 04:34:17[diff] [blame]24For more information, see this internal doc:
25[go/gerrit-reauth](http://go/gerrit-reauth).
Jiewei Qian2d2ca0f2025-08-29 05:00:34[diff] [blame]26***
27
Jiewei Qiand76b2b332025-08-29 01:37:40[diff] [blame]28[TOC]
29
30## Background
31
32To further protect the integrity of Chromium’s codebase and other related
33projects, including Git repositories, a significant security enhancement is
34being implemented. This enhancement requires all **committers** who write or
35review code to utilize a security key for two-factor authentication on their
36associated Google account.
37
38This new approach, referred to as ReAuth, mandates a security key tap once every
3920 hours to obtain a fresh set of credentials for interactions with Git and
40Gerrit. Specifically, actions requiring committer powers, such as reviewing
41Change Lists (CLs) for submission and uploading CLs (which counts as the
42uploader self-reviewing the CL), will necessitate ReAuth.
43
44The primary goal of this policy is to establish a robust layer of protection
45against unauthorized access, significantly diminishing the risk of compromised
46accounts, supply chain attacks, and malicious activities stemming from stolen
47committer credentials.
48
Jiewei Qian0c6c4142025-10-02 03:23:03[diff] [blame]49## Overview
50
51You are required to ReAuth when using git-cl to upload your change. You
52ReAuth to git-cl by running `git credential-luci reauth`.
53
54Gerrit Web UI may show [ReAuth popups](#reauth-in-gerrit-web-ui) when you
55perform actions like voting Code-Review or editing change descriptions.
56In this case, please follow the popup's instructions.
57
58*** promo
59ReAuth is valid for 20 hours, so we recommend ReAuth once when you start your
60day with `git credential-luci reauth`.
61***
62
63*** note
64If you work remotely over SSH or remote desktop, please follow steps in
65[ReAuth in git-cl remotely](#ReAuth-in-git_cl-remotely) to setup your
66environment.
67
Jiewei Qiana6bdd632025-10-07 04:32:17[diff] [blame]68If you use Linux:
69
701. You need to install a GUI-based `pinentry` program to enter security key
71 PINs. Certain security keys models mandate PIN entry at all times.
72
731. You might also need to [configure your system](#linux-security-keys-access)
74 to make security keys usable.
Jiewei Qian0c6c4142025-10-02 03:23:03[diff] [blame]75***
Jiewei Qiand76b2b332025-08-29 01:37:40[diff] [blame]76
77## Prerequisites
78
79### Physical Security Key
80
81You must have a physical
82[FIDO security key](https://www.google.com/search?q=FIDO+security+key)
83registered with your Google account.
84
85To register a key or check your existing keys, go to
86[https://myaccount.google.com/signinoptions/passkeys](https://myaccount.google.com/signinoptions/passkeys)
87
88![Security key registration](./images/gerrit_reauth_key_registration.png)
89
90The line "This key can only be used with a password" indicates a **U2F**
91security key. If the line is missing, the key is a **FIDO2** security key.
92Please include this info when reporting issues.
93
Jiewei Qian13e6e40d2025-10-14 04:09:14[diff] [blame]94*** promo
Jiewei Qiand76b2b332025-08-29 01:37:40[diff] [blame]95**Important Note**: Passkeys won't be supported by ReAuth. A physical security
96key is required.
Jiewei Qian13e6e40d2025-10-14 04:09:14[diff] [blame]97***
Jiewei Qiand76b2b332025-08-29 01:37:40[diff] [blame]98
Jiewei Qian13e6e40d2025-10-14 04:09:14[diff] [blame]99**If you use Firefox**: You need to **allow** the website to request "extended
100information about your security key" when registering your security key (refer
101to the screenshot below).
102Otherwise the key won't be able to ReAuth (you'll see BAD_REQUEST error in the
103log). If you've already registered the key, remove it from the security key
104list, then add it again.
Jiewei Qiand1e33d3f2025-10-07 00:48:37[diff] [blame]105
Jiewei Qian13e6e40d2025-10-14 04:09:14[diff] [blame]106![Firefox security key popup](./images/gerrit_reauth_firefox_sk.png)
107
108**If you’re using a Google Workspace account**, make sure
Jiewei Qiand76b2b332025-08-29 01:37:40[diff] [blame]109"[2-Step Verification](https://myaccount.google.com/signinoptions/twosv)" is
110turned on.
111
112![Two-step verification](./images/gerrit_reauth_2sv.png)
113
Jiewei Qian13e6e40d2025-10-14 04:09:14[diff] [blame]114*** note
Jiewei Qian236299ef2025-10-08 04:09:05[diff] [blame]115**Known Issue:** If you sign in to your Google account via an external identity provider
116such as **Active Directory, Entra ID, or Okta**, you may see `NO_AVAILABLE_CHALLENGES` error
117when you ReAuth immediately after registering your security key.
118
119You may need to **wait for a few hours** before your first ReAuth can proceed. We're still
120investigating the cause.
Jiewei Qian13e6e40d2025-10-14 04:09:14[diff] [blame]121***
Jiewei Qian236299ef2025-10-08 04:09:05[diff] [blame]122
Jiewei Qiand76b2b332025-08-29 01:37:40[diff] [blame]123### Accurate Timezone / Time
124
125Make sure your device's timezone and time are set correctly.
126
127If you’re behind a corporate network or network proxy, your system’s auto
128configured timezone might be incorrect. If this is the case, go to your system’s
129settings and set timezone and/or time manually.
130
Allen Li7da6849d2025-09-09 00:35:23[diff] [blame]131### Latest Git
132
133Ensure you have the latest version of Git (or at least later than 2.46.0). Use
134the package manager for your system or download from the [Git
135website](https://git-scm.com/downloads). (Note: if you are on Ubuntu LTS you may
136need to follow the instructions on the Git website to install from PPA)
137
Jiewei Qiana68889742025-09-04 01:11:58[diff] [blame]138### Latest depot_tools
139
140Ensure you
141[have depot_tools](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up)
142installed and configured on PATH.
143
144Then run:
145
146```
147update_depot_tools
148```
149
150### Git config for Gerrit
151
152Make sure your Git is configured for Gerrit. You only need to do this once.
153
154```
155git cl creds-check --global
156```
157
158Please follow the prompts from the tool and resolve any issues.
159
Jiewei Qian0c6c4142025-10-02 03:23:03[diff] [blame]160### Log into Gerrit
161
162Check if you're already logged in (this is likely if you have already logged
163in with depot_tools):
164
165```
166git credential-luci info
167```
168
169This should print a line containing `email=<your email>`. If not, you'll need to
170login first:
171
172```
173git credential-luci login
174```
175
Jiewei Qian4c42c99ad2025-09-30 07:58:03[diff] [blame]176### Linux: security keys access
177
178Check depot_tools can access your security keys by running:
179
180```
181luci-auth-fido2-plugin --list-devices
182```
183
184If the above command lists your security keys, you’re good to go.
185
186If not, you need to configure your Linux system to grant access to security
187keys.
188
189The configuration steps vary by Linux distributions. We recommend following
190[Yubico’s guide](https://support.yubico.com/hc/en-us/articles/360013708900-Troubleshooting-using-your-YubiKey-with-Linux)
191, which we confirmed to be working on Ubuntu 24.04 LTS Desktop.
192
Jiewei Qiana6bdd632025-10-07 04:32:17[diff] [blame]193### Linux: security key PIN entry program
194
195ReAuth doesn't require security key PINs. But PINs entry might be enforced by
196the security key manufacturer, or if you have configured your key to do so.
197
198On Linux, you need the `pinentry` program to input PINs. If you don't have this
199program, your security key will refuse to complete the ReAuth challenge. You
200typically see `BAD_REQUEST` or `PinRequiredError` in the logs depending on the
201security key.
202
203For the best experience, we recommend using a **GUI based pinentry** program.
204
205Terminal based pinentry only works with local ReAuth. If you don't need to
206ReAuth over SSH, feel free to use one.
207
208To install a GUI-based pinentry program:
209
210* Ubuntu, Debian: `sudo apt install pinentry-gnome3`
211* Fedora: `sudo dnf install pinentry-qt`
212
213After installing the package, your system should default to the newly installed
214GUI-based pinentry program.
215
216You can check the current pinentry program by running:
217
218```
219readlink -f $( which pinentry )
220```
221
222The output path's suffix should be a GUI based name, such as "-gnome" or "-qt".
223
224If the above path ends with terminal based name, such as "tty" or "curses", set
225`LUCI_AUTH_PINENTRY=pinentry-gnome3` environment variable to override.
226
Jiewei Qian0c6c4142025-10-02 03:23:03[diff] [blame]227## ReAuth in Gerrit Web UI
Jiewei Qiand76b2b332025-08-29 01:37:40[diff] [blame]228
Jiewei Qian0c6c4142025-10-02 03:23:03[diff] [blame]229When performing actions such as voting Code-Review or editing commit
230descriptions on Gerrit Web UI, you may see popups like:
Jiewei Qiand76b2b332025-08-29 01:37:40[diff] [blame]231
Jiewei Qian0c6c4142025-10-02 03:23:03[diff] [blame]232![Gerrit UI prompt](./images/gerrit_reauth_ui_prompt.png)
Jiewei Qiand76b2b332025-08-29 01:37:40[diff] [blame]233
Jiewei Qian0c6c4142025-10-02 03:23:03[diff] [blame]234Click "Continue". You'll be asked to touch your security key to perform ReAuth,
235after which everything will proceed as normal.
Jiewei Qiand76b2b332025-08-29 01:37:40[diff] [blame]236
Jiewei Qian0c6c4142025-10-02 03:23:03[diff] [blame]237## ReAuth in git-cl locally
238
239This is for performing ReAuth locally, on a machine with your security key
240inserted.
Jiewei Qiand76b2b332025-08-29 01:37:40[diff] [blame]241
Jiewei Qiana68889742025-09-04 01:11:58[diff] [blame]242First, make sure you have the [latest depot_tools](#latest-depot_tools) and
Jiewei Qian0c6c4142025-10-02 03:23:03[diff] [blame]243have [set up Git to access Gerrit](#git-config-for-gerrit), and is
244[logged into Gerrit](#log-into-gerrit). If you're using Linux, make sure
Jiewei Qian4c42c99ad2025-09-30 07:58:03[diff] [blame]245[depot_tools can access your security keys](#linux_security-keys-access).
Jiewei Qiand76b2b332025-08-29 01:37:40[diff] [blame]246
Jiewei Qiand76b2b332025-08-29 01:37:40[diff] [blame]247To perform ReAuth, run the following command inside your terminal:
248
249```
250git credential-luci reauth
251```
252
253You will be prompted to touch your security key. If you see “ReAuth succeed.”,
254then it works\!
255
256If it doesn't work, please refer to [Troubleshooting](#troubleshooting) to turn
257on debug logs, then retry the command.
258
Jiewei Qian0c6c4142025-10-02 03:23:03[diff] [blame]259## ReAuth in git-cl remotely
Jiewei Qiand76b2b332025-08-29 01:37:40[diff] [blame]260
261This is for completing ReAuth when:
262
263- You plug-in a security key to a local client machine machine
264- You SSH or remote desktop into a remote development machine (where the
265 chromium/src checkout lives)
266
Jiewei Qiana68889742025-09-04 01:11:58[diff] [blame]267First, make sure you have the [latest depot_tools](#latest-depot_tools)
268installed on **both local and remote** machines.
Jiewei Qiand76b2b332025-08-29 01:37:40[diff] [blame]269
Jiewei Qian4c42c99ad2025-09-30 07:58:03[diff] [blame]270If you're using a Linux local machine (i.e. the machine you inserts security
271keys into), make sure
272[depot_tools can access your security keys](#linux_security-keys-access).
273
Jiewei Qian0c6c4142025-10-02 03:23:03[diff] [blame]274Then, on the remote machine, make sure you have
275[set up Git to access](#git-config-for-gerrit) and have
276[logged into Gerrit](#log-into-gerrit).
Jiewei Qiand76b2b332025-08-29 01:37:40[diff] [blame]277
Jiewei Qian0c6c4142025-10-02 03:23:03[diff] [blame]278Then, refer to sections below for your SSH or remote desktop workflow.
Jiewei Qiand76b2b332025-08-29 01:37:40[diff] [blame]279
Jiewei Qian0c6c4142025-10-02 03:23:03[diff] [blame]280### I’m using a Linux / Mac client, I want to SSH into Linux
Jiewei Qiand76b2b332025-08-29 01:37:40[diff] [blame]281
Jiewei Qian4c42c99ad2025-09-30 07:58:03[diff] [blame]282If you’re using a Linux client, please check and make sure
283[depot_tools can access your security keys](#linux_security-keys-access).
Jiewei Qiand76b2b332025-08-29 01:37:40[diff] [blame]284
Jiewei Qian88cb1b62025-09-30 08:02:49[diff] [blame]285Then, use `luci-auth-ssh-helper` to SSH into the remote machine. You can
286specify SSH options (such as port forwarding) after a double dash.
Jiewei Qiand76b2b332025-08-29 01:37:40[diff] [blame]287
288```
289luci-auth-ssh-helper [-- ssh_options...] [user@]host
290```
291
292In this SSH session, run the following command to ReAuth:
293
294```
295git credential-luci reauth
296```
297
298You should be prompted to touch your security key. If you see "ReAuth succeed",
299then it works\!
300
301For the first security key touch, there might be a delay before your security
302key starts blinking. This is caused by `luci-auth-fido2-plugin` bootstrapping.
303
Jiewei Qian0c6c4142025-10-02 03:23:03[diff] [blame]304### I’m using a Linux / Mac client, I want to remote desktop into Windows
Jiewei Qiand76b2b332025-08-29 01:37:40[diff] [blame]305
306If you’re using a Linux client, ensure you’ve completed
307["Linux Client Prerequisites"](#linux-client-prerequisites) and made your
308security keys available to applications.
309
310You need a remote desktop client that supports WebAuthn forwarding.
311
312For example,
313[Thincast Remote Desktop Client](https://thincast.com/en/products/client)
314(available free of charge for non-commercial use):
315
316- On Linux, install the **flatpak version**
317 ([instructions](https://thincast.com/en/documentation/tcc/latest/index#install-linux)).
318 Snapcraft version doesn’t work with security keys (as of 2025 August)
319- On MacOS, download and install the universal dmg package
320 ([instructions](https://thincast.com/en/documentation/tcc/latest/index#install-linux))
321
322Then, launch the Thincast remote desktop client, enable the "WebAuthn" option in
323"Local Resource \> Local devices and resource \> More…" (refer to screenshots
324below).
325
326Click "OK" to save your settings, then go back to the "General" tab, input the
327remote desktop server with your development machine’s hostname (or IP address)
328and user name, then click "Connect".
329
330![](./images/gerrit_reauth_thincast1.png)
331
332![](./images/gerrit_reauth_thincast2.png)
333
334In the remote desktop session, open a command prompt (CMD), then run the
335following command to ReAuth:
336
337```
338git credential-luci reauth
339```
340
341Wait for your security key to blink, then touch it to complete ReAuth. You
342should see "ReAuth succeed" in the command prompt.
343
344For the first security key touch, there might be a delay before your security
345key starts blinking. This is caused by `luci-auth-fido2-plugin` bootstrapping.
346
Jiewei Qian33461d92025-10-24 04:44:47[diff] [blame]347### I’m using a Windows client, I want to SSH into Linux
Jiewei Qiand76b2b332025-08-29 01:37:40[diff] [blame]348
349First, start `luci-auth-ssh-helper` in daemon mode on a TCP port (we use 10899
350in the example). The helper will listen for incoming ReAuth challenges.
351
352```
Jiewei Qiand76b2b332025-08-29 01:37:40[diff] [blame]353luci-auth-ssh-helper -mode=daemon -port=10899
354```
355
356Then, use your SSH client and port-forward a port (here we use the same port
357number for convenience) on your remote Linux machine to the helper’s port on the
358local machine.
359
360Note, you might need to update your SSH server config to allow port-forwarding
361(if not enabled by default).
362
363If you’re using the an OpenSSH client (e.g. built-in to Windows, or included in
364Git-on-Windows):
365
366```
367ssh -R 10899:localhost:10899 [user@]remote_host
368```
369
370If you’re using PuTTY, set up port-forwarding on the "Connection \> SSH \>
371Tunnels" page in the connection dialog (see screenshot). Remember to "Save" your
372configuration in the "Session" page if you want to persist the configuration.
373
374![](./images/gerrit_reauth_putty.png)
375
376Inside your SSH session, set `SSH_AUTH_SOCK` to the forwarding port, then run
377the ReAuth command.
378
379```
380export SSH_AUTH_SOCK=localhost:10899
381git credential-luci reauth
382```
383
384Windows will prompt you to touch the security key. Touch the security to
385complete ReAuth. If you see "ReAuth succeed", then it works.
386
387For the first security key touch, there might be a delay before your security
388key starts blinking. This is caused by `luci-auth-ssh-plugin` and
389`luci-auth-fido2-plugin` bootstrapping.
390
391You need to make sure `luci-auth-ssh-helper` is running on your local machine
392when you want to perform ReAuth challenges over a SSH session. For convenience,
393you can register it to start as a service on login.
394
Jiewei Qian0c6c4142025-10-02 03:23:03[diff] [blame]395### I’m using a Windows client, I want to remote desktop into Windows
Jiewei Qiand76b2b332025-08-29 01:37:40[diff] [blame]396
397Use the built-in Windows Remote Desktop Connection application (also known as
398`mstsc`), make sure "WebAuthn (Windows Hello or security keys)" is enabled in
399"Show Options \> Local Resources \> More…" (refer to screenshots below). Then
400connect to the remote Windows machine as usual.
401
402![](./images/gerrit_reauth_rdp1.png)
403
404![](./images/gerrit_reauth_rdp2.png)
405
406Then, in the remote desktop session, run the following command in command prompt
407(CMD):
408
409```shell
410git credential-luci reauth
411```
412
413Windows will prompt you to touch the security key. Touch it to complete ReAuth.
414
415If you see "ReAuth succeed", then it works\!
416
Jiewei Qian0c6c4142025-10-02 03:23:03[diff] [blame]417### None of the above
Jiewei Qiand76b2b332025-08-29 01:37:40[diff] [blame]418
419SSH / remote desktop workflows not listed above aren’t tested. We’re working on
420adding instructions for more workflows.
421
422If you have suggestions or feedback, please report to:
423[https://issues.chromium.org/issues/new?component=1456702&template=2176581](https://issues.chromium.org/issues/new?component=1456702&template=2176581).
424
425## Troubleshooting
426
427Please set `LUCI_AUTH_DEBUG` environment variable to enable debug logs.
428
429In Linux / Mac, run:
430
431```
432export LUCI_AUTH_DEBUG=1
433```
434
435In Windows (CMD), run:
436
437```
438set LUCI_AUTH_DEBUG=1
439```
440
441Then, retry the failed command (e.g. `git credential-luci reauth`).
442
443If you run into issues, please report to
Allen Li61a86a962025-09-23 21:25:41[diff] [blame]444[https://issues.chromium.org/issues/new?component=1456702&template=2176581](https://issues.chromium.org/issues/new?component=1456702&template=2176581)
Jiewei Qiand76b2b332025-08-29 01:37:40[diff] [blame]445
446**Please be sure to include**:
447
448- The debug logs produced by setting `LUCI_AUTH_DEBUG`
449- The security key you're using (e.g. manufacturer, model, etc.)
450- Whether the security key is registered as a FIDO2 or U2F key (see
451 [Prerequisites](#prerequisites))
Jiewei Qian91bc65f2025-10-21 03:51:13[diff] [blame]452- The following environment variables: `SSH_AUTH_SOCK`, `SSH_CONNECTION` and
453 `GOOGLE_AUTH_WEBAUTHN_PLUGIN`
Jiewei Qiand76b2b332025-08-29 01:37:40[diff] [blame]454
455Note, when sharing debug logs, please edit out the value after `Signature:`
456field (if it's present) and any other values if you wish.
457
458## FAQs
459
Jiewei Qian91bc65f2025-10-21 03:51:13[diff] [blame]460**ReAuth in `screen`, `tmux`, `shpool`, etc.**
461You need to manually set `GOOGLE_AUTH_WEBAUTHN_PLUGIN` environment variable for
462ReAuth to work. This is in addition to the instructions above.
463
464If you're a Googler, follow
465[the internal guide](go/gerrit-reauth#bookmark=id.gohr0ejjvi49).
466
467Otherwise, set the environment variable depending on your situation:
468
Allen Lid1b4da82025-11-10 23:08:45[diff] [blame]469* Inside `screen`, etc., running locally:
470 `GOOGLE_AUTH_WEBAUTHN_PLUGIN=luci-auth-fido2-plugin`
471* Inside `screen`, etc., running remotely with `luci-auth-ssh-helper`:
472 `GOOGLE_AUTH_WEBAUTHN_PLUGIN=luci-auth-ssh-plugin`
Jiewei Qian91bc65f2025-10-21 03:51:13[diff] [blame]473
474Then run `git credential-luci reauth`.
475
Jiewei Qiand76b2b332025-08-29 01:37:40[diff] [blame]476**I accidentally shared the `Signature:` in the debug logs\!**
477
478Do not worry too much if you share this. This can be used in a very small time
479frame to exchange for a token that only lasts for 20 hours, and both the
480exchange and any subsequent use of the token also requires your actual/regular
481credentials in addition to the token. Furthermore, as of this writing, no
482actions can be authorized with this token yet.
483
484Of course, we do recommend avoiding sharing this as a general safety precaution.
485
486**Can I use other forms of 2-Step Verification (2SV)?**
487
488For ReAuth: No. You must use a physical security key. SMS, authenticator app,
489passkeys won't satisfy ReAuth requirement (e.g. when uploading code, doing code
490reviews).
491
492You can still add and use other 2SV methods to sign into your Google account.
Andrew Mitchell771d9222025-09-03 04:25:09[diff] [blame]493
494**What should I expect to see when ReAuth is required?**
495
496ReAuth is required every 20 hours. When ReAuth is required you will see the
497following error when performing Gerrit remote operations like uploading CLs:
498
499```
500ReAuth is required
501
502If you are running this in a development environment, you can fix this by running:
503
504git credential-luci reauth
505```
506
507You will need to run `git credential-luci reauth` every 20 hours to avoid or
508resolve this issue. We recommend you ReAuth when you start your day.