Infrastructure/infra-docs-fpo
1
0
Fork 0
Code Issues 100 Pull requests 6 Projects Releases Packages Wiki Activity Actions

2-factor doc: rework completely for new 2fa setup

Browse source 
Signed-off-by: Kevin Fenzi <kevin@scrye.com>
This commit is contained in:
Kevin Fenzi 2022-03-25 10:39:44 -07:00
parent 63c719e397
commit cf3dfd270f
1 changed files with 36 additions and 81 deletions
Download patch file Download diff file Expand all files Collapse all files

117
modules/sysadmin_guide/pages/2-factor.adoc
View file

@ -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 <username>
* ipa otptoken-del <token uuid from previous step>
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 <pod> (Pick one of totpcgi pods from the above list)
.. $ totpprov delete-user <username>
____
. 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/