search

inbo / tutorials

A collection of technical tutorials for INBO (and anyone who's interested)
https://inbo.github.io/tutorials/
Creative Commons Attribution 4.0 International
22 stars 9 forks source link

Issue 287 git authentication #309

Closed hansvancalster closed 2 years ago

hansvancalster commented 2 years ago

Description

Tutorial about Git / GitHub authentication.

Related Issue

Closes #287

Task list

Previewing the pull request

Thanks to GitHub Actions, an artifact (=zip file) of the rendered website is automatically created for each pull request.

Instructions

1) On the PR page, you can find a "details" link under "checks - On PR, build the site and ...". Go there, click on the top link in the left sidebar ("Summary"), and download the generated artifact at the bottom of the page. 2) Decompress it and make sure the target directory is called 'tutorials' (you may need to rename it) 3) From the parent directory (just above the tutorials folder you created/renamed), run python -m http.server 8887, or launch the Google Chrome Web Server app and point it at the parent directory. 4) Point your browser to http://localhost:8887/tutorials. 5) Review the updated website and accept/refuse/comment the PR

Note: for step 3, you can use any other simple HTTP server to serve the current directory if you don't have a Python 3 environment or Google Chrome available.

hansvancalster commented 2 years ago

@ThierryO , @florisvdh I think most is covered but maybe something about checklist package can be added or about GHA? @peterdesmet I wasn't sure who best to ask as reviewer from your team. Feel free to dispatch.

hansvancalster commented 2 years ago

Note to self:

hansvancalster commented 2 years ago

start with mentioning the different options, and group these options in such way that readers can just choose one of these options without having to struggle through the whole manual to figure out which steps they have to take to make it all work. In my opinion this can be done in one sentence or one alinea in 'before we start'. maybe instead of the difficult section 'modes of authentication' (with a lot of difficult terminology that is hardly explained),

See 8707beb and 66379b1

shortly explain the mechanisms behind 2FA and SSH (key-value-pair with public and private key), give some examples where they use it already at INBO, and add some links for further reading. It may help some people to know what they are doing. But as not everyone may be interested, make sure they can also use the manual without it. And maybe this part can also contain advantages and disadvantages of the different options, or a link to it?

Everybody at INBO already knows about 2FA, because it is used for our Google account. Regarding SSH, the weblink you provided is added.

for the practical sections: just enumerate ALL steps that have to be done for a certain option in one list, don't expect readers to search for additional steps written in full text everywhere in the document, or figure out which parts have to be combined. For this, keep in mind that when giving git courses or in package manuals, it would be nice to be able to refer to a step-by-step guide without overload.

See the rewritten TL;DR section which has this purpose. The SSH option is still included for completeness, but is not really needed (but it's a different story for Linux users) and therefor not mentioned in the TL;DR section.

hansvancalster commented 2 years ago

I would suggest to promote checklist as it sets the .gitignore per project.

@ThierryO See 095c785 (your comments somehow got messed up apparently)

florisvdh commented 2 years ago

afbeelding

_(copy from https://github.com/inbo/tutorials/pull/309#discussion_r865719144)_

These are two different things: 2FA is not needed, but recommended as an extra security layer next to the password when logging into github.com. AFAIK it's unrelated to git operations. See https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa.

Maybe this separation can be made more clear in the tutorial, but maybe it's clear already.

hansvancalster commented 2 years ago

@ElsLommelen can you try out the steps in the TL;DR section of the tutorial on your machine? If you still think 2FA needs more guidance, can you document what you did to make it work (possibly including some screenshots)?

ElsLommelen commented 2 years ago

Below my notes on the installation of 2FA. I described the installation of the TOTP into detail, as this is not described at all in the manual. I leave it up to you to decide on to what detail it should be added to the manual. The github manual on 2FA is very well documented, here I only listed possible caveats and where decisions have to be made.

einde_2FA_github

(I'll try logging out and back in on github now (step 10), after which I'll continue your TL;DR section, so other comments may follow)

florisvdh commented 2 years ago

step 8: save recovery codes: it is recommended to save them with a secure password manager

Actually any decent (and locally controlled) encryption approach will suffice to guard against compromises. Many are available, e.g. with password managers such as KeepassXC, or with general disk or file encryption programs like Veracrypt, CryFS, LUKS. Unencrypted files can be considered less safe. Having backups (e.g. in the cloud) is another aspect, it guards against loss.