From 973157d7775c7f0331b0d1c6c27b75a89b462314 Mon Sep 17 00:00:00 2001 From: Sitaram Chamarty Date: Mon, 25 Jul 2011 13:33:21 +0530 Subject: [PATCH] (doc) "authentication-vs-authorisation" "gitolite-without-ssh" doc name was misleading; rename to "authentication-vs-authorisation" also restructure the whole thing to answer the main question better, and fix up links from other places --- doc/authentication-vs-authorisation.mkd | 104 ++++++++++++++++++++++++ doc/gitolite-and-ssh.mkd | 5 +- doc/gitolite-without-ssh.mkd | 86 -------------------- doc/ssh-troubleshooting.mkd | 2 +- 4 files changed, 108 insertions(+), 89 deletions(-) create mode 100644 doc/authentication-vs-authorisation.mkd delete mode 100644 doc/gitolite-without-ssh.mkd diff --git a/doc/authentication-vs-authorisation.mkd b/doc/authentication-vs-authorisation.mkd new file mode 100644 index 0000000..fc1edd4 --- /dev/null +++ b/doc/authentication-vs-authorisation.mkd @@ -0,0 +1,104 @@ +# authentication versus authorisation + +This document will explain why an "ssh issue" is almost never a "gitolite +issue", and, indirectly, why I dont get too excited about the former. + +Note: for actual ssh troubleshooting see [this][glsts]. + +[glsts]: http://sitaramc.github.com/gitolite/doc/ssh-troubleshooting.html + +---- + +Here is a fundamental point: **Gitolite does not do +authentication. It only does authorisation**. + +So first, let's loosely define these words: + +> **Authentication** is the process of verifying that you are who you claim +> to be. An authentication system will establish that I am the user +> "sitaram" on my work system. The one behind gmail will similarly +> establish that I am "sitaramc". And so on... + +> **Authorisation** is the process of asking what you want to do and +> deciding if you're allowed to do it or not. + +Now, if you managed to read [doc/gitolite-and-ssh.mkd][gas], you know that +gitolite is meant to be invoked as: + + /full/path/to/gl-auth-command some-authenticated-gitolite-username + +(where the "gitolite username" is a "virtual" username; it does not have to +be, and usually *isn't*, an actual *unix* username). + +As you can see, authentication happens before gitolite is called. + +[gas]: http://sitaramc.github.com/gitolite/doc/gitolite-and-ssh.html + + + +### but... but... you have all that ssh stuff in there! + +The default mode of using gitolite does use ssh keys, but all it's doing is +helping you **setup** ssh-based authentication **as a convenience to you**. + +You don't have to use it, though. And many people don't. The examples I know +are [smart http][sh], and ldap-backed sshd. In both cases, gitolite has no +role to play in creating users, setting up their passwords/keys, etc. There's +even a `GL_NO_SETUP_AUTHKEYS` option to make sure gitolite doesn't meddle with +the authkeys file in such installations. + +[sh]: http://sitaramc.github.com/gitolite/doc/http-backend.html + + + +### so you're basically saying you won't support "X" + +(where "X" is some ssh related behaviour change or feature) + +Well, if it's not a security issue I *probably* won't. I'm willing to change +my mind if enough people convince me they need it. (There's a mailing list if +you want to find others who also need the same thing.) + +While we're on the subject, locking someone out is *not* a security issue. +Even if you locked yourself (the admin) out, the docs tell you how to recover +from such errors. You do need some password based method to get a shell +command line on the server, of course. + + + +### appendix: how to use other authentication systems with gitolite + +The bottom line in terms of how to invoke gitolite has been described above, +and as long as you manage to do that gitolite won't even know how the +authentication was done. Which in turn means you can use whatever +authentication scheme you want. + +It also expects the `SSH_ORIGINAL_COMMAND` environment variable to contain the +full command (typically starting with git-receive-pack or git-upload-pack) +that the client sent. Also, when using [smart http][sh], things are somewhat +different: gitolite uses certain environment variables that it expects httpd +to have set up. Even the user name comes from the `REMOTE_USER` environment +variable instead of as a command line argument in this case. + +However, it has to be an authentication system that is compatible with sshd or +httpd in some form. Why? Because the git *client* accessing the server only +knows those 2 protocols to "speak git". (Well, the `git://` protocol is +unauthenticated, and `file://` doesn't really apply to this discussion, so +we're ignoring those). + +For example, let's say you have an LDAP-based authentication system somewhere. +It is possible to make apache use that to authenticate users, so when a user +accesses a git url using `http://sitaram:password@git.example.com/repo`, it is +LDAP that does the actual authentication. [I wouldn't know how to do it but I +know it is possible. Patches to this doc explaining how are welcome!] + +There are also ssh daemons that use LDAP to store the authorised keys (instead +of putting them all in `~/.ssh/authorized_keys`). The clients will still need +to generate keypairs and send them to the admin, but they can be more +centrally stored and perhaps used by other programs or tools simultaneously, +which can be useful. + +Finally, gitolite allows you to store *group* information externally too. See +[here][ldap] for more on this. + +[ldap]: http://sitaramc.github.com/gitolite/doc/big-config.html#_storing_usergroup_information_outside_gitolite_like_in_LDAP_ diff --git a/doc/gitolite-and-ssh.mkd b/doc/gitolite-and-ssh.mkd index e8b3509..d4e07d0 100644 --- a/doc/gitolite-and-ssh.mkd +++ b/doc/gitolite-and-ssh.mkd @@ -1,11 +1,12 @@ # how gitolite uses ssh Although other forms of authentications exist (see -[doc/gitolite-without-ssh.mkd][ws]), ssh is the one that most git users use. +[doc/authentication-vs-authorisation.mkd][ws]), ssh is the one that most git +users use. ***Therefore, gitolite is (usually) heavily dependent on ssh***. -[ws]: http://sitaramc.github.com/gitolite/doc/gitolite-without-ssh.html +[ws]: http://sitaramc.github.com/gitolite/doc/authentication-vs-authorisation.html Most people didn't realise this, and even if they did they didn't know ssh well enough to help themselves. If you don't understand how ssh public key diff --git a/doc/gitolite-without-ssh.mkd b/doc/gitolite-without-ssh.mkd deleted file mode 100644 index 7ab5dfb..0000000 --- a/doc/gitolite-without-ssh.mkd +++ /dev/null @@ -1,86 +0,0 @@ -# gitolite without ssh - -Gitolite does not actually need ssh. If you managed to read -[doc/gitolite-and-ssh.mkd][gas], you may have realised that the crux of -gitolite is that it be eventually invoked as - - /full/path/to/gl-auth-command some-authenticated-gitolite-username - -(where the "gitolite username" is a "virtual" username; it does not have to -be, and usually *isn't*, an actual *unix* username). - -[gas]: http://sitaramc.github.com/gitolite/doc/gitolite-and-ssh.html - - - -### sidebar: authentication versus authorisation - -> Just for completeness, I'd like to loosely define these two animals. - -> **Authentication** is the process of verifying that you are who you claim -> to be. An authentication system will establish that I am the user -> "sitaram" on my work system. The one behind gmail will similarly -> establish that I am "sitaramc". And so on... - -> **Authorisation** is the process of asking what you want to do and -> deciding if you're allowed to do it or not. - - - -### what does gitolite actually do - -With that background, here's the truth about gitolite: - -> ***Gitolite does not do authentication. It only does authorisation.*** - -Yes, the default mode of using gitolite does use ssh keys, but all it's doing -is helping you **setup** ssh-based authentication **as a convenience to you**. -But nothing forces you to use it. The best example: gitolite does not setup -any keys or passwords if you install it in [smart http][sh] mode. - -[sh]: http://sitaramc.github.com/gitolite/doc/http-backend.html - -In other words, authentication is the job of `sshd` or `httpd`, not gitolite. - -[**SIDE NOTE**: This is why an "ssh issue" is almost never a "gitolite issue". -It is also why I often ignore emails and IRC messages that seem like just ssh -issues if I am too busy. I will never ignore core gitolite issues like that, -of course!] - - - -### using other authentication systems with gitolite - -The bottom line in terms of how to invoke gitolite has been described up at -the top, and as long as you manage to do that gitolite won't even know how the -authentication was done. Which in turn means you can use whatever -authentication scheme you want. - -[Side note: it also expects that the environment variable -`SSH_ORIGINAL_COMMAND` contain the command that the client sent (typically a -git-receive-pack or git-upload-pack command), or in some CGI variables when -using [smart http][sh] mode.] - -However, it has to be an authentication system that is compatible with sshd or -httpd in some form. Why? Because the git *client* accessing the server only -knows those 2 protocols to "speak git". (Well, the `git://` protocol is -unauthenticated, and `file://` doesn't really apply to this discussion, so -we're ignoring those). - -One common example is LDAP. Let's say you have an LDAP-based authentication -system somewhere. It is possible to make apache use that to authenticate -users, so when a user accesses a git url using -`http://sitaram:password@git.example.com/repo`, it is LDAP that does the -actual authentication. [I wouldn't know how to do it but I know it is -possible. Patches to this doc explaining how are welcome!] - -There are also ssh daemons that use LDAP to store the authorised keys (instead -of putting them all in `~/.ssh/authorized_keys`). The clients will still need -to generate keypairs and send them to the admin, but they can be more -centrally stored and perhaps used by other programs or tools simultaneously, -which can be useful. - -Finally, gitolite allows you to store *group* information externally too. See -[here][ldap] for more on this. - -[ldap]: http://sitaramc.github.com/gitolite/doc/big-config.html#_storing_usergroup_information_outside_gitolite_like_in_LDAP_ diff --git a/doc/ssh-troubleshooting.mkd b/doc/ssh-troubleshooting.mkd index d355ac1..babeecd 100644 --- a/doc/ssh-troubleshooting.mkd +++ b/doc/ssh-troubleshooting.mkd @@ -501,7 +501,7 @@ key. (Using `git@server:reponame` will end up using the default key [transcript]: http://sitaramc.github.com/gitolite/doc/install-transcript.html [openssh56]: http://www.openssh.org/txt/release-5.6 [tut]: http://sites.google.com/site/senawario/home/gitolite-tutorial -[wo]: http://sitaramc.github.com/gitolite/doc/gitolite-without-ssh.html +[wo]: http://sitaramc.github.com/gitolite/doc/authentication-vs-authorisation.html [putty]: http://sitaramc.github.com/gitolite/contrib/putty.html