Distinguishing users from each other

Gitolite uses ssh to authenticate its users. However, while ssh normally allows authentication using either a password or an ssh key pair, Gitolite requires that a key pair be used for authentication; passwords are not accepted.

Each Gitolite user has an ssh key pair on their desktop or laptop. A key pair consists of two files, typically called id_rsa (the private key), and id_rsa.pub (the public key).

The public key file contains a single, very long line of text; here's a shortened example:

ssh-rsa AAAAB3NzaC1[...]LBkU1XGGPnX adam@lab1.example.com

The key is actually too long to print here, so we removed about 350 characters from the middle, replacing them with ellipsis, but this should still give you a good idea of what it looks like.

The preceding figure illustrates the sequence of events that happens when a user connects to a Gitolite server to access a Git repository, and how this sequence is enabled. First, each user sends their public key to the Gitolite administrator. When the Gitolite administrator adds these users to Gitolite, Gitolite adds the keys to a file called .ssh/authorized_keys in the home directory of the hosting user. It then prefixes to the beginning of each line a string that looks somewhat like the following line (for the user Adam) and similarly for other users:

command="/home/gitolite/bin/gitolite-shell adam",[...] ssh-rsa [...]

This first step is what enables the access control. It is a one-time action, and needs to be repeated only when the administrator adds or removes users. Notice the command option, containing a program name (gitolite-shell using its full path), and its argument (the username, adam in this example)—this will be relevant a bit later.

The second step shows what happens when, say, Bob tries to connect to the server. Bob runs the ssh command, whether directly or via his local git client, in the form of a clone, fetch, or push command. The ssh daemon on the server handles the connection attempt. Bob's ssh client will offer a public key, and the ssh daemon will go looking for it in the authorized keys file, finding it eventually. In our example, it finds a match on the second line.

Next, the ssh daemon notices the command option on the matched line in the authorized keys file. This tells the ssh daemon that, instead of running the program that the client asked for, it should instead run the command mentioned in that option, including any arguments supplied. This means the gitolite-shell program is executed with the Gitolite username (in our example, Bob) as the first argument. This is how the gitolite-shell program knows who is connecting.