Issue 287 git authentication #309
Conversation
|
@ThierryO , @florisvdh I think most is covered but maybe something about |
There was a problem hiding this comment.
As I'm not a Windows user, I can't verify how clear the tutorial is. Maybe ask @ElsLommelen or @pietervsd to review that.
| 1. Allow tools to store and retrieve your credentials from the Git Credential Manager. | ||
|
|
||
| This deserves some further explanation. | ||
| The first recommendation essentially is an extra layer of security compared to a simple username and password only authentication. |
There was a problem hiding this comment.
@peterdesmet can't we enforce 2FA at the organisation level?
There was a problem hiding this comment.
I noticed I need either 2FA or SSH to be able to push changes to GitHub. Is there a reason why it is useful to also enforce 2FA for other use of GitHub (reading, cloning repo's,... I'm not sure what else can be done without 2FA)?
There was a problem hiding this comment.
To my current understanding, 2FA is not needed per se for anything on GitHub. The only thing that's needed for remote git operations to work over HTTPS protocol is a PAT. The book happy git with R never mentions 2FA. It is only a recommendation of GitHub (and the authors of the usethis package). GitHub is actively promoting users to use 2FA as a general safety precaution.
There was a problem hiding this comment.
You're right: yesterday I made some minor changes using GitHub and I made a PR. This can all be done without 2FA. In my previous post I supposed 2FA was always needed to make changes (I forgot about the possibility to make changes online), but this is apparently not the case. So if an account would be hacked, someone can make changes to the code as well.
There was a problem hiding this comment.
2FA is not that intrusive. It only kicks in when you login from a new device or when your last login on a devive was a long time ago.
If someone steals your username and password, they still can't login using that combination from their device due to 2FA. If they obtain your PAT or private key (without password), they can authenticate as you regardsless of 2FA. In case your PAT or private key is stolen, you should deactivate it ASAP on GitHub.
| 1. Allow tools to store and retrieve your credentials from the Git Credential Manager. | ||
|
|
||
| This deserves some further explanation. | ||
| The first recommendation essentially is an extra layer of security compared to a simple username and password only authentication. |
There was a problem hiding this comment.
@peterdesmet can't we enforce 2FA at the organisation level?
There was a problem hiding this comment.
It's possible. But at this point it would be more interesting to know how many people have 2FA enabled already. One of the INBO organisation owners/administrators can check this
Co-authored-by: Thierry Onkelinx <ThierryO@users.noreply.github.com>
|
Note to self:
|
There was a problem hiding this comment.
To be honest, I haven't read the whole manual yet. As you will see below, somewhere I got lost, and I'm afraid it is all too difficult and too confusing for people that are not familiar with authentication. I would recommend to give the manual a clear structure first, afterwards I will have a new look on it. Some advice for this:
- 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), 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?
- 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.
| - Go to https://github.com/inbo/tutorials press clone button and copy the URL (default is HTTPS: https://github.com/inbo/tutorials.git) | ||
| - Open RStudio -> File -> New project -> Version control -> Git -> paste https://github.com/inbo/tutorials.git -> create project |
There was a problem hiding this comment.
I tried this on a newly installed laptop, and I was unable to push to the repo:
- first I got a dialogue box with the text 'Connect to GitHub', 'GitHub', and 'Sign in' and a button 'Sign in with your browser'
- when pressing this button, my browser opened and the site showed 'Deze site kan geen beveiligde verbinding leveren' and 'localhost heeft een ongeldige reactie verzonden'
Some weeks ago I had similar problems with another repo, and after some hours of troubleshooting, I moved to SSH again.
So these steps seem easy and very promising, but I'm sure one needs additional steps to make this function properly...
Edit: after continuing my read, I notice I should have completed 2FA... To be honest, up to now the manual has been rather confusing (and I know what 2FA and SSL are, or at least the principles behind it, I can imagine that it is even less clear for someone who hardly heard of authentication):
- concerning the ways of authentication that are recommended for the ways of accessing your GitHub resources: this overview contains a lot of terminoloty that is unknown to a lot or readers, and I honestly also have no clue what is recommended when. E.g. to access (read) a public GitHub repo via the browser, I suppose a login is not needed at all? So it would be helpful here to distinguish between 'reading' and 'contributing', I think, and maybe make it more specific by mentioning some example actions.
- then these recommendations given in the usethis package: by just copying them without any explanation, it seems they are some voluntarily actions, but only now things don't work out well, I realise they may as well be different steps that have to be done all to have a working system
- then you casually mention the SSH protocol, which you obviously don't like, but the reason stays unclear. Personally I'm not a in favour of 2FA because you need to install additional software and save recovery codes somewhere, while SSH is a commonly used protocol that is at INBO for instance also used to access databases (instead of using VPN). So either explain clearly why 2FA is preferred, or just explain both methods clearly, so the reader can choose which method to use.
- in the seemingly introductionary part of 'modes of authentication', there are a lot of links with additional information, and as it is all hard to understand, a reader will likely miss the link 'these steps' that is apparently part of the manual to use the HTTPS protocol... A step by step manual in which all steps are brought together in a clear step-by-step guide, would be helpful. (Certainly for people who want to use it without fully understanding the background of it.)
There was a problem hiding this comment.
Thanks for these suggestions.
I will make some changes so that everything you need to do is in the TL;DR section.
I forgot to place 2FA in that section, which is why it failed in your case.
For me this was also very confusing when reading about this stuff on internet, but I tried to make sense and explain the more difficult terms.
Some more explanation and corrections are needed, but I'm not a specialist (just someone who volunteered to write this at some point).
Regarding SSH / HTTPS I'm just following / echoing the advice of people more authoritative than me on this matter (people working at RStudio, ropensci and GitHub mainly). For instance see: https://docs.ropensci.org/gert/#should-i-use-https-or-ssh-remotes.
BTW I didn't know we can use SSH to make connections to INBO databases instead of VPN. Is this common knowledge? Is this documented somewhere? I've never been told this was possible.
There was a problem hiding this comment.
Regarding SSH: I searched on 'SSH explained for dummies', and I found this explication (with among others a link to a nice explication on the key-pair). I leave it up to you to just link to it, or try to explain it in some words. And hopefully you find a similar one for HTTPS?
For the database: it was for a Postgresql database that was set up for one project (and only open to the collaborators of one project). Instead of first passing VPN to get to the server and secondly setting up security for the database, the db admin choosed to use SSH. So we had a meeting with the collaborators in which we set up this and everyone exchanged the keys with the db admin. In databases, other software is used than on GitHub, of course, but the principle stays the same: first you somehow have to exchange keys (so sender and receiver can translate the message), afterwards you can exchange encrypted messages (that only the 2 parties with the keys can translate).
So it is not commonly used at INBO, it mainly depends on the easiest method to set up in a specific case (and probably not only for databases, it can be used everywhere if you need to send encrypted messages), but collegues that did it once, may remember the fact that they exchanged this public key. Other than that, it is just following the recipe. ;-)
Ah, and now that you mention it: I already saw TL;DR in some of the tutorials, but I don't know the meaning or what it refers to. This may have to do with my limited knowledge of English, but if it is not commonly known at INBO, you may want to either explain it or replace it by something more commonly known.
There was a problem hiding this comment.
Everybody at INBO already knows about 2FA, because it is used for our Google account. Regarding SSH, the weblink you provided is added.
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. |
| @@ -42,29 +42,49 @@ If you want to get some intuition about what you are doing, you will need to rea | |||
|
|
|||
| Enable two-factor authentication for your GitHub account, follow [these steps](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-a-totp-mobile-app). | |||
| Another two-factor authentication app that is not mentioned on that website but easy to use is Google Authenticator. | |||
| You probably already use a two-factor authentication app, just use that. | |||
There was a problem hiding this comment.
(Just trying to imitate a user a limited knowledge of authentication:)
I guess I may use two-factor authentication for my email, or was it for my computer login? I don't know exactly, and I have absolutely no idea what authentication app I use there (I just followed the manual of IT). Anyway, I'll just try the manual...
- scanning the QR code gives that the requested application cannot be started and that the 'barcode' can be wrong (I suppose we don't have this app on our smartphones, as we buy and install them ourselves...)
- with 'enter this text code', I get a code, but I have no idea where I should enter it? (I probably can't install a app for it myself, as I don't have admin rights on my laptop)
- I have to add a 6-digit code, but the recovery codes I got for the two-factor authentication of my my email, are 8-digit codes, so I suppose this won't work.
So yes, I suppose in the best case users know that they indeed use 2FA already, but I doubt if they know which authentication app they are using, and how to apply it to this situation without any further explanation. Without searching for which app we are using at INBO or installing an authentication app myself, I don't get it enabled, so unless users are really motivated and the app can be installed without admin rights, they won't succeed either, I think.
So I would really advise to make it a step-by-step manual applied to the situation of INBO that simply can be followed by executing the described steps. Don't expect users to choose, install and use an app themselves without any manual: at least recommend an option or explain how they can use the app that is already present on their computer.
There was a problem hiding this comment.
Mmmh, I tend to disagree with you on this one: (i) the choice of 2FA / TOTP app is up to the user, (ii) anyone who is savvy and brave enough to be using Git, should be able to figure this out. Our IT recommended Google Authenticator (which I mention as well in the text), but really, the choice is up to you. Many password managers include a TOTP generator on board. I can add guidelines here for - say - Google Authenticator, but it would be foolish to follow them if you happen to use KeePassXC or 1password already.
But I can be convinced otherwise. I might also be biased because I use these things regularly. What do others think?
There was a problem hiding this comment.
I agree with the fact that tech savvy people should have the choice and use whatever they have installed already (we don't force people to use this manual!), but the majority of the INBO users haven't installed their own tools, they just use whatever they are taught or told to use. (They are not computer scientists, it is our task to support them with that if we want them to learn using Github because we think it is useful!)
I thought the purpose of your manual was to make it easier for these less tech savvy people to also use Github to collaborate with their tech savvy teammates in for instance reports? If people have to figure out part of the manual themselves anyway because it is not explained, what is the sense of making a manual specific for INBO anyway? There are already a lot of manuals with general and sometimes rather vague explications on how to set up authentications (that don't always work out well), so if you can't give any additional value, why doing the effort of making another manual like that? The purpose of a INBO manual should in my opinion at least be to have less people that need additional help (we should gain at least the time needed for making a manual in a lower need for support). (Also, don't forget: by leaving the choice up to them, we should be able to give support on all the different apps.)
It is your choice of supporting https, and honestly, if I see the complexity, I get less and less convinced that this is the right choice: when moving to a new laptop, for ssh I needed nothing but the general email instructions sent by IT support when getting a new laptop to get it functioning again. For https it seems a lot of struggling, even with your manual. So try to convince me https is easier than ssh (by providing a good manual), up to now it feels the opposite for me, and I'm sure this struggle will certainly not convince collegues to start using Github. ;-)
All other INBO manuals are very straightforward and easy to use because choices are made, so why not doing the same with this manual? You can give alternative options in the full text below TL;DR, where you also give the alternative of ssh.
There was a problem hiding this comment.
It is your choice of supporting https, and honestly, if I see the complexity, I get less and less convinced that this is the right choice: when moving to a new laptop, for ssh I needed nothing but the general email instructions sent by IT support when getting a new laptop to get it functioning again. For https it seems a lot of struggling, even with your manual. So try to convince me https is easier than ssh (by providing a good manual), up to now it feels the opposite for me, and I'm sure this struggle will certainly not convince collegues to start using Github. ;-)
OK, let's take this back one step. In my head the choice for https stems from (i) it's the GitHub default, (ii) it's what I've been taught when learning Git at INBO, (iii) as far as I know it is still what's taught at INBO. In that respect it seemed logical to me to follow the recommendations put forward by the usethis package and the book happy git with R. But your comment makes me unsure. I'm certainly not the person to decide this for everyone at INBO. So before I proceed, someone needs to give me a green light to go ahead with this or not. Also, I'd rather discuss these things in person.
I am OK with adding a step by step instruction that explains how to setup the 2FA and I suggest we explain it using the Google Authenticator app (?), but first I would like to hear confirmation or not from other people to go ahead with HTTPS.
Now that I looked up the INBO material about the INBO Git Workshop, I also realize that some or all of the material in this tutorial might better be integrated there?
There was a problem hiding this comment.
OK, let's take this back one step. In my head the choice for https stems from (i) it's the GitHub default, (ii) it's what I've been thought when learning Git at INBO, (iii) as far as I know it is still what's thought at INBO.
https was indeed what has been taught at INBO, but this was before 2FA was required by Github. And I suppose this was not yet required a year ago, when I did a Github coaching, as I didn't come across difficulties at that time...
At this point I can't tell which is the easiest: apparently I never enabled 2FA in Github (and I never did the effort to figure it out), and I already installed ssh some years ago, so this was the way of the least effort in my case. Probably there is not a lot of difference (it both needs a lot of configuration steps once) except for packages that use one or another method, and the easiest one for a user is generally the one that has the clearest step-by-step manual. ;-)
(For now I have one package that relies on git2r (and an old version of git2rdata) to read and write to a git repo for starting r users, so I will have to adapt this if https will be used at INBO, but on the other hand I still need to write a clear manual on the installation of the authentication stuff... So in the end I gain by just relying on your manual and adapting my package. ;-) )
So I'm fine with either https/2FA or ssh, the most important in my opinion is to have a clear step-by-step manual that can just be followed. If 2FA and the use of Google Authenticator is advised by people who know it and it has no conflicts with commonly used packages at INBO, than it is fine for me. Except for me (and I am mainly arguing for a clear manual, not against the method itself!) there seems not a lot of objection against it in this PR, so go ahead with HTTPS (of ask some more Windows users for their opinion???).
Now that I looked up the INBO material about the INBO Git Workshop, I also realize that some or all of the material in this tutorial might better be integrated there?
Good idea!
There was a problem hiding this comment.
Thanks for mentioning @florisvdh! I did the same, so I'm relieved to hear it also supports HTTPS. (However, if git2rdata moved to gert, I may decide on moving to gert anyway to limit the number of depencencies in my package...)
There was a problem hiding this comment.
The argument for HTTPS seems well explained in https://docs.ropensci.org/gert/#should-i-use-https-or-ssh-remotes. As is the argument for using gert.
There was a problem hiding this comment.
Indeed - contrary to what I was thinking - git2r does support https. But, I would still go for gert. A quote from https://docs.ropensci.org/gert/#automatic-authentication:
To authenticate with a remote in git2r, you often need to manually pass your credentials in every call to, e.g., git2r::clone(). This is always the case for an https remote and is often the case even for an ssh remote.
There was a problem hiding this comment.
That is statement is rubbish in case of an ssh remote.
There was a problem hiding this comment.
That is statement is rubbish in case of an ssh remote.
Yes, it is advised to use ssh-agent to provide the private key (and the passphrase if set), cf. https://happygitwithr.com/ssh-keys.html#add-key-to-ssh-agent and https://docs.github.com/en/authentication/connecting-to-github-with-ssh. The agent will remember the key only during the user session (OS level), so this is to be done again in the next login session before doing remote operations. If this is not done, you won't be offered some alternative:
$ git remote -v
origin git@github.com:inbo/tutorials.git (fetch)
origin git@github.com:inbo/tutorials.git (push)
$ ssh-add -D
All identities removed.
$ git fetch
git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.
Please make sure you have the correct access rights
and the repository exists.
Co-authored-by: Els Lommelen <els.lommelen@inbo.be>
There was a problem hiding this comment.
Thanks for this interesting tutorial @hansvancalster! Some minor things require further attention.
Co-authored-by: Floris Vanderhaeghe <floris.vanderhaeghe@inbo.be>
|
(copy from #309 (comment)) 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. |
- 2FA = about GitHub authentication
There was a problem hiding this comment.
Nice work @hansvancalster, sorry for the late follow-up. Approving so that you can proceed; some minor remaining points need to be addressed before merging (+ once again knitting md). Thanks!
Co-authored-by: Floris Vanderhaeghe <floris.vanderhaeghe@inbo.be>
| This tutorial assumes you have a GitHub account, and have Git, R and RStudio installed on your system. | ||
| The purpose of this tutorial is to make clear recommendations about authentication for employees at INBO who use Git version control in their workflows. | ||
|
|
||
| If you do not have a GitHub account, you can [sign up for a new GitHub account](https://docs.github.com/en/get-started/signing-up-for-github/signing-up-for-a-new-github-account). |
There was a problem hiding this comment.
I'm not sure it is mentioned elsewhere in the git course tutorials, but if not, we should recommend here to (request to) join to the INBO group and the team. Otherwise it would be better to refer here to the INBO git course where this is mentioned, rather than a general github tutorial.
|
@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)? |
|
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.
(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) |
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. |
| scope = "user", | ||
| user.name = "Your Name", | ||
| user.email = "your@email.com", | ||
| init.defaultbranch = "main" |
There was a problem hiding this comment.
I already had init.defaultbranch = master on a system level (but didn't notice it beforehand); by running this command (where I deleted user.name and user.email as they were already set) I get an additional init.defaultbranch = main on the global level. What consequences could this have?
There was a problem hiding this comment.
Git has three levels of configuration: system, global and local. The local configuration overwrites global which in turn overwrites system-level configuration. So: it's no problem.
There was a problem hiding this comment.
Ok, then there is no need for further explanation in the tutorial.
| # you can ignore this warning | ||
| # Warning message: | ||
| # In orig[nm] <- git_cfg_get(nm, "global") %||% list(NULL) : | ||
| # number of items to replace is not a multiple of replacement length |
There was a problem hiding this comment.
Just for the information: I didn't get this warning.
| If you plan to use functions that create something on GitHub (a repo, an issue, a pull request, a branch, ...) and for all remote operations from the command line (`git pull`, `git push`, `git clone`, `git fetch`), you can use the following commands to create a Personal Access Token (PAT) and add it to the Git Credential Manager: | ||
|
|
||
| ```{r} | ||
| ?usethis::create_github_token() # read the help file |
There was a problem hiding this comment.
The documentation mentions: GitHub is encouraging the use of PATs that expire after, e.g., 30 days, so prepare yourself to re-generate and re-store your PAT periodically. Should we then run these commands again, or is it easier done in our account on github?
There was a problem hiding this comment.
Not sure ... I think I would head over to https://github.com/settings/tokens, click on the PAT that is expired and than click regenerate token.
There was a problem hiding this comment.
And how would you then store the new token (code) in your computer? I suppose it doesn't reuse the same token, as then it seems the old one could better be kept?
I just opened an expired token, and near the Regenerate token button, a message mentions: If you've lost or forgotten this token, you can regenerate it, but be aware that any scripts or applications using this token need to be updated. So I suppose it indeed generates a new unique code.
There was a problem hiding this comment.
I included a section explaining this in 9631f16
| **WARNING**: handle your Personal Access Token (PAT) as a secret. | ||
| Anyone who has your token, has access to your GitHub account. |
There was a problem hiding this comment.
Is it needed to store it somewhere, or don't we need it anymore after we set it in gitcreds?
There was a problem hiding this comment.
After you have set it in gitcreds, the credential manager stores the PAT. No need to store it elsewhere.
There was a problem hiding this comment.
Maybe it would good to mention this in the tutorial as well. Due to this warning, I was not sure if whether or not to store it.
There was a problem hiding this comment.
Done in 9631f16
Co-authored-by: Els Lommelen <els.lommelen@inbo.be>
Co-authored-by: Els Lommelen <els.lommelen@inbo.be>
Co-authored-by: Els Lommelen <els.lommelen@inbo.be>
There was a problem hiding this comment.
Before it had been suggested to add this tutorial as part of git-course, but as this is not the case, I would certainly give it some more context and at least mention in the beginning of the tutorial that the setup is meant for people who use github in RStudio.
(And as requested, I approve without reviewing the whole tutorial.)
Description
Tutorial about Git / GitHub authentication.
Related Issue
Closes #287
Task list
tutorials/contentindex.md. In case of an Rmarkdown tutorial I have knitted myindex.Rmdtoindex.md(both files are pushed to the repo).tagsin the YAML header (see the tags listed in the tutorials website side bar for tags that have been used before)categoriesto the YAML header and my category tags are from the list of category tagsPreviewing the pull request
Thanks to GitHub Actions, an artifact (=zip file) of the rendered website is automatically created for each pull request.
Instructions
tutorialsfolder you created/renamed), runpython -m http.server 8887, or launch the Google Chrome Web Server app and point it at the parent directory.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.