User Tools

Site Tools


userdoc:gitolite_2fa

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
userdoc:gitolite_2fa [2014-06-12 19:01]
korgadmin
userdoc:gitolite_2fa [2020-05-08 14:01] (current)
mricon
Line 1: Line 1:
 +~~REDIRECT>​https://​korg.docs.kernel.org/​gitolite/​2fa.html~~
 +
 ====== 2-factor authentication with gitolite.kernel.org ====== ====== 2-factor authentication with gitolite.kernel.org ======
  
-**Notice: opt-in ​beta**+:!: The preferred mechanism for 2-factor authentication is via an SSH key stored on a smartcard device. If you have an account on kernel.org, you qualify for a free [[nitrokey]],​ so we strongly recommend that instead of setting up TOTP/HOTP you switch to using the Nitrokey for your ssh access instead. 
 + 
 +===== HOTP/TOTP ip-based push validation ===== 
 + 
 +**Notice: opt-in**
  
-We are rolling out 2-factor authentication for access to gitolite.kernel.org. At this pointthis feature ​is still in testing stage and will probably always remain opt-in instead of being required across the board.+^Command^Summary^ 
 +|**enroll** //​[mode]//​|Enroll with 2-factor authentication ​(mode=totp or yubikey)| 
 +|**val** //​[token]//​|Validate your current IP address ​for 24 hours| 
 +|**val-session** //​[token]//​|Validate your current ssh ControlMaster session| 
 +|**val-for-days** //[days]// //​[token]//​|Validate your current IP address for arbitrary number of days (max=30)| 
 +|**val-subnet** //[/cidr]// //​[token]//​|Validate a larger subnet for 8 hours| 
 +|**list-val** //​[all]//​|List current validations ("​all"​ includes expired)| 
 +|**inval** //​[ip-address]//​|Invalidate specific IP address (can be "​myip"​"​all"​ or "all purge"​)| 
 +|**isval**|Check if your current IP is validated| 
 +|**unenroll** //​[token]//​|Unenroll from 2-factor authentication|
  
 ===== Core concepts ===== ===== Core concepts =====
Line 47: Line 62:
 The only HOTP devices currently tested and supported are yubikeys. Any of the currently listed products should support HOTP authentication:​ The only HOTP devices currently tested and supported are yubikeys. Any of the currently listed products should support HOTP authentication:​
  
-  * [[http://​www.yubico.com/​products/​yubikey-hardware/​yubikey/|Standard]] (cheapest) +  * [[https://​www.yubico.com/​products/​yubikey-hardware/​yubikey4/|Yubikey 4]] either standard or Nano form-factors ​(also supports ​OpenPGP ​functionality)
-  * [[http://​www.yubico.com/​products/​yubikey-hardware/​yubikey-nano/​|Nano]] (smallest) +
-  * [[http://​www.yubico.com/​products/​yubikey-hardware/​yubikey-neo/​|NEO]] ​(also works as an OpenPGP ​card)+
  
-We recommend the NEO, as you can also configure it as an [[https://​github.com/​herlo/​ssh-gpg-smartcard-config/​blob/​master/​YubiKey_NEO.rst|OpenPGP card]], but laptop ​users may find that using the Nano is more comfortable.+Laptop ​users may find that using the Nano form factor ​is more comfortable.
  
 ===== Provisioning your 2-factor token ===== ===== Provisioning your 2-factor token =====
Line 104: Line 117:
 ==== Yubikeys ==== ==== Yubikeys ====
  
-To initialize a yubikey, run the following command instead: +To initialize a yubikey, run the following command instead. Note, that you will need [[https://​developers.yubico.com/yubikey-personalization/​|ykpersonalize]] to configure your key.
- +
-  ssh git@example.com 2fa enroll ​yubikey+
  
 +  ssh git@gitolite.kernel.org 2fa enroll yubikey
  
 The output of the yubikey command is slightly different: The output of the yubikey command is slightly different:
Line 220: Line 232:
 Listed non-expired entries only. Run "​list-val all" to list all. Listed non-expired entries only. Run "​list-val all" to list all.
 </​code>​ </​code>​
 +
 +Note: this command only works from a whitelisted IP address.
  
 To invalidate an IP, use the "​inval"​ command, e.g.: To invalidate an IP, use the "​inval"​ command, e.g.:
Line 226: Line 240:
   Force-expired 24.x.x.x   Force-expired 24.x.x.x
  
-Instead of the IP address, you may also use "​myip"​ to invalidate the current IP you're connecting from, or "​all"​ to force-expire all active IP validations.+Instead of the IP address, you may also use "​myip"​ to invalidate the current IP you're connecting from, or "​all"​ to force-expire all active IP validations. ​If you run "inval all purge",​ this will additionally purge all your current and expired entries -- handy if you would like to leave no trace of your travel history. 
 + 
 +===== SSH session validation ===== 
 +If you are travelling and happen to be behind a single NAT exit point with a lot of other people, it is preferable to validate only your SSH session instead of the whole public exit point. This will also help if the exit point is not static but changes between tcp sessions (as is sometimes common in very large NAT-ed networks). 
 + 
 +Before you can use this feature, you will need to make sure you enabled **ssh multiplexing** in the client, by adding the following entries to your gitolite.kernel.org section: 
 + 
 +  ControlPath ~/​.ssh/​cm-%r@%h:​%p 
 +  ControlMaster auto 
 +  ControlPersist 30m 
 + 
 +You can use longer than 30m if necessary -- the session will be validated for up to 8 hours. Please see [[userdoc:​ssh_access]] for more ssh setup details. 
 + 
 +===== Using in scripts ===== 
 +You can check if your current IP is valid from inside a script, by using the **isval** check, e.g. like so: 
 + 
 +<code bash> 
 +echo -n "​Checking if 2fa validation is current: " 
 +if ! ssh git@gitolite.kernel.org 2fa isval; then 
 +    echo "​Error:​ kernel.org 2fa validation expired"​ 
 +    exit 1 
 +fi 
 +</​code>​ 
 + 
 +Note that there'​s an inherent race condition here: your validation may expire between this check and the actual git push. 
  
 ===== Switching devices and Unenrolling ===== ===== Switching devices and Unenrolling =====
Line 246: Line 285:
  
 ===== Requesting 2-factor protection for your repository ===== ===== Requesting 2-factor protection for your repository =====
-During this beta-testing ​period, send mail to [[userdoc:​support]] to request that your repository is added to the 2fa list. +During this opt-in period, send mail to [[userdoc:​support]] to request that your repository is added to the 2fa list.
userdoc/gitolite_2fa.1402599701.txt.gz · Last modified: 2014-06-12 19:01 by korgadmin