gitolite/doc/extras/auth.mkd

# 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.