From cf3dfd270f6f1ad8cda44ba99495222d28832bfe Mon Sep 17 00:00:00 2001 From: Kevin Fenzi Date: Mar 25 2022 17:39:44 +0000 Subject: 2-factor doc: rework completely for new 2fa setup Signed-off-by: Kevin Fenzi --- diff --git a/modules/sysadmin_guide/pages/2-factor.adoc b/modules/sysadmin_guide/pages/2-factor.adoc index 4f89cd4..61ff47f 100644 --- a/modules/sysadmin_guide/pages/2-factor.adoc +++ b/modules/sysadmin_guide/pages/2-factor.adoc @@ -1,98 +1,53 @@ -= Two factor auth += Two factor authentication -Fedora Infrastructure has implemented a form of two factor auth for -people who have sudo access on Fedora machines. In the future we may -expand this to include more than sudo but this was deemed to be a high -value, low hanging fruit. +The Fedora account system frontend (noggin) allows for users to enroll otp token(s). +See https://noggin-aaa.readthedocs.io/en/latest/userguide.html#two-factor-authentication +for end user documentation. -== Using two factor +Otp tokens are then stored and managed in IPA backend. -http://fedoraproject.org/wiki/Infrastructure_Two_Factor_Auth +Users who enroll a otp are then required to append it to their password +or add it in a seperate field (if available) whenever they use their +Fedora account system login. -To enroll a Yubikey, use the fedora-burn-yubikey script like normal. To -enroll using FreeOTP or Google Authenticator, go to -https://admin.fedoraproject.org/totpcgiprovision/ +Users who enroll a otp are also prohibited from removing the last otp +they have enabled on their account. This is to prevent someone from removing +the last otp to allow password only access to resources like sudo. +See https://github.com/fedora-infra/noggin/issues/579 for discussion. -=== What's enough authentication? +For this reason it's advised to enroll multipule otp tokens, +and/or to backup these tokens in case of device breakage/failure/loss. -FAS Password+FreeOTP or FAS Password+Yubikey Note: don't actually enter -a +, simple enter your FAS Password and press your yubikey or enter your -FreeOTP code. += Administration -== Administrating and troubleshooting two factor +Sometimes users will loose or otherwise no longer have access to their +last otp and will need it to be cleared to allow them to login again +and set a new one. These requests are sent into admin@fedoraproject.org. +(Be sure to 'reply all' when processing these so other sysadmin-main +members know they are processed) -Two factor auth is implemented by a modified copy of the -https://github.com/mricon/totp-cgi project doing the authentication and -pam_url submitting the authentication tokens. +Admins need to verify the users identity before processing these requests. -totp-cgi runs on the fas servers (currently fas01.stg and -fas01/fas02/fas03 in production), listening on port 8443 for pam_url -requests. +Including, but not limited to: -FreeOTP, Google authenticator and yubikeys are supported as tokens to -use with your password. +* user sends gpg signed email with gpg key attached to their Fedora account -=== FreeOTP, Google authenticator: +* user can ssh to fedorapeople.org with the ssh private key associated with +a ssh public key associated with their Fedora account -FreeOTP application is preferred, however Google authenticator works as -well. (Note that Google authenticator is not open source) +* rover verification (in case of Red Hat employee). -This is handled via totpcgi. There's a command line tool to manage -users, totpprov. See 'man totpprov' for more info. Admins can use this -tool to revoke lost tokens (google authenticator only) with 'totpprov -delete-user username' +* Video or in person meeting with admin who knows their identity on sight. -To enroll using FreeOTP or Google Authenticator for production machines, -go to https://admin.fedoraproject.org/totpcgiprovision/ +Additionally, users only in ipausers group can have their token cleared +as they don't have access to much of anything (yet). -To enroll using FreeOTP or Google Authenticator for staging machines, go -to https://admin.stg.fedoraproject.org/totpcgiprovision/ +To clear a token, admin should: -You'll be prompted to login with your fas username and password. +* login to ipa01.iad2.fedoraproject.org +* kinit admin@FEDORAPROJECT.ORG (enter the admin password) +* ipa otptoken-find --owner +* ipa otptoken-del -Note that staging and production differ. - -=== YubiKeys: - -Yubikeys are enrolled and managed in FAS. Users can self-enroll using -the fedora-burn-yubikey utility included in the fedora-packager package. - -=== What do I do if I lose my token? - -Send an email to admin@fedoraproject.org that is encrypted/signed with -your gpg key from FAS, or otherwise identifies you are you. - -=== How to remove a token (so the user can re-enroll)? - -First we MUST verify that the user is who they say they are, using any -of the following: - -* Personal contact where the person can be verified by member of -sysadmin-main. -* Correct answers to security questions. -* Email request to admin@fedoraproject.org that is gpg encrypted by the -key listed for the user in fas. - -Then: - -. For google authenticator, -+ -____ -.. ssh into batcave01 as root -.. ssh into os-master01.iad2.fedoraproject.org -.. $ oc project fas -.. $ oc get pods -.. $ oc rsh (Pick one of totpcgi pods from the above list) -.. $ totpprov delete-user -____ -. For yubikey: login to one of the fas machines and run: -/usr/local/bin/yubikey-remove.py username - -The user can then go to -https://admin.fedoraproject.org/totpcgiprovision/ and reprovision a new -device. - -If the user emails admin@fedoraproject.org with the signed request, make -sure to reply to all indicating that a reset was performed. This is so -that other admins don't step in and reset it again after its been reset -once. +Or alternately, admin can use the ipa web ui: +https://id.fedoraproject.org/ipa/ui/