deac/gitolite
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

(doc) "authentication-vs-authorisation"

Browse source 
"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
This commit is contained in:
Sitaram Chamarty 2011-07-25 13:33:21 +05:30
parent 6b65ffbab4
commit 973157d777
4 changed files with 108 additions and 89 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

104
doc/authentication-vs-authorisation.mkd Normal file
View file

@ -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: <font color="red">**Gitolite does not do
authentication. It only does authorisation**.</font>
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
<a name="_but_but_you_have_all_that_ssh_stuff_in_there_"></a>
### 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
<a name="_so_you_re_basically_saying_you_won_t_support_X_"></a>
### 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.
<a name="_appendix_how_to_use_other_authentication_systems_with_gitolite"></a>
### 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_

5
doc/gitolite-and-ssh.mkd
View file

@ -1,11 +1,12 @@
# how gitolite uses ssh # how gitolite uses ssh
Although other forms of authentications exist (see 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***. ***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 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 well enough to help themselves. If you don't understand how ssh public key

86
doc/gitolite-without-ssh.mkd
View file

@ -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
<a name="_sidebar_authentication_versus_authorisation"></a>
### 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.
<a name="_what_does_gitolite_actually_do"></a>
### 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!]
<a name="_using_other_authentication_systems_with_gitolite"></a>
### 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_

2
doc/ssh-troubleshooting.mkd
View file

@ -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 [transcript]: http://sitaramc.github.com/gitolite/doc/install-transcript.html
[openssh56]: http://www.openssh.org/txt/release-5.6 [openssh56]: http://www.openssh.org/txt/release-5.6
[tut]: http://sites.google.com/site/senawario/home/gitolite-tutorial [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 [putty]: http://sitaramc.github.com/gitolite/contrib/putty.html
<a name="_appendix_5_why_bypassing_gitolite_causes_a_problem"></a> <a name="_appendix_5_why_bypassing_gitolite_causes_a_problem"></a>