de40461d9a
- explicit 'list' gives way to mindmap, ... - 'fm2mt.pl' to produce master-toc.mkd from the mindmap - mkdoc no longer ignores master-toc.mkd, calls fm2mt.pl itself and LOTS of changes to the actual docs
107 lines
4.9 KiB
Markdown
107 lines
4.9 KiB
Markdown
# 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][sts].
|
|
|
|
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 about [gitolite and ssh][glssh], you
|
|
know that gitolite is meant to be invoked as:
|
|
|
|
/full/path/to/gitolite-shell 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.
|
|
|
|
## but... but... you have all that ssh stuff in gitolite!
|
|
|
|
No I don't. Not in "core" gitolite from g3 onwards :-)
|
|
|
|
The default setup does use ssh keys, but it's only helping you **setup**
|
|
ssh-based authentication **as a convenience to you**. But in fact it is a
|
|
*completely* separate program that you can disable (in the rc file) or replace
|
|
with something else of your choice.
|
|
|
|
For example, in both [smart http][http] and ldap-backed sshd, gitolite has no
|
|
role to play in creating users, setting up their passwords/keys, etc.
|
|
|
|
## 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 won't. But since it's no longer part of
|
|
"core" gitolite, I can be much more relaxed about taking patches, or even
|
|
alternative implementations.
|
|
|
|
While we're on the subject, locking someone out is *not* a security issue.
|
|
Even if you [lost the admin key][lost-key], 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.
|
|
|
|
## #otherauth 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][http], 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.
|
|
|
|
## #ldap getting user group info from LDAP
|
|
|
|
Gitolite's [groups][] are pretty convenient, but some organisations already
|
|
have similar (or sufficient) information in their LDAP store.
|
|
|
|
Gitolite can tap into that information, with a little help. Write a program
|
|
which, given a username, queries your LDAP store and returns a space-separated
|
|
list of groups that the user is a member of. Then put the full path to this
|
|
program in an [rc][] variable called `GROUPLIST_PGM`, like so:
|
|
|
|
GROUPLIST_PGM => '/home/git/bin/ldap-query-groups',
|
|
|
|
Now you can use those groupnames in access rules in gitolite, just as if you
|
|
had declared their memberships in the conf file.
|
|
|
|
Caution: your program must do its own logging if you want the audit trail of
|
|
"why/how did this user get access to this repo at this time?" to resolve
|
|
properly. Gitolite does not do any logging of the results of the queries
|
|
because for people who don't need it that would be a huge waste.
|