(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
This commit is contained in:
Sitaram Chamarty
parent
6b65ffbab4
commit
973157d777
104
doc/authentication-vs-authorisation.mkd
Normal file
104
doc/authentication-vs-authorisation.mkd
Normal 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_
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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_
|
||||
|
|
@ -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
|
||||
|
||||
<a name="_appendix_5_why_bypassing_gitolite_causes_a_problem"></a>
|
||||
|
|
|
|||
Loading…
Reference in a new issue