gitolite/contrib/real-users/password-access.mkd

# F=password_access password access to gitolite

(a.k.a: turning real users into gitolite users)

## problems

*Problem 1*: Here's one type of problem some admins have:

  * Some of your users already have a real (unix) userid on the *same server*
    as the gitolite hosting user.
  * They don't all use ssh keys; some may still be using passwords and don't
    want to change.
  * They want to use this existing userid to access the gitolite served repos.

This document has a solution to this problem!

*Problem 2*: And here's a somewhat different one:

  * Some of your users are not willing to use ssh keys; they're only
    comfortable with passwords.
  * But gitolite *requires* ssh key-based access; it can't work if you use a
    password to get access (because then there is no way to distinguish one
    user from another).

Well, as the math folks say, "reduce it to a known problem".  Give them all
Unix userids on the same server as gitolite, with password access, so that
problem 2 reduces to problem 1 ;-)

<font color="gray">If you created these Unix accounts *only* to solve this
pesky password problem, and do not wish them to actually have shell access or
be able to do anything else on the server, don't worry -- that's easy to
handle too.</font>

## solution

Briefly, the Unix userid is made to act like a "gitolite proxy".

Here's a more detailed explanation.

Normal gitolite flow, for a user called Alice, is like this:

                                ssh key
        alice     ---------------------------------------->    git
    (workstation)              (REQUIRED)                    (server)

However, if Alice has her own real (unix) userid on the server, and the admin
sets things up according to this document, then Alice can do this:

                      password
        alice     ------ OR ----->  alice
    (workstation)     ssh key      (server)

The **important** thing to note here is that she doesn't need ssh keys; she
can use passwords if she wants to.

Behind the scenes, the gitolite/git conversation is being transparently
forwarded to the gitolite hosting user, so it is *actually* like this:

                      password                  ssh key
        alice     ------ OR ----->  alice   - - - - - - - >    git
    (workstation)     ssh key      (server)    (REQUIRED)  (localhost)

The second connection is transparent to Alice; she still thinks she is talking
to her own userid.  In git URL terms, she simply uses `alice@server:reponame`,
without realising that behind the scenes this is getting forwarded to
`git@server:reponame`.

This second connection *does* require ssh keys, but since they're all on the
server, it's scriptable and automatable so the user doesn't have to deal with
these pesky ssh keys.

## some hints, notes and caveats

  * This doesn't mean all your users have to be like this.  You can have
    normal users also.  In fact, you can have users who give you a pub key
    from their workstation the normal way, as well as use this method.

## what the 2 scripts actually do

  * `gl-shell` will become the new login shell for these users.  This shell
    will forward git clone/fetch/push requests to the gitolite server.

    This redirection is so transparent that I had to explicitly code a message
    ("forwarding to git@server") to make troubleshooting easier.

  * `gl-shell-setup` is run by root, once for each user.  (You can run it
    multiple times; it's designed to be idempotent).  As root, it changes the
    user's shell to `gl-shell` (full path), then sets up an RSA key for the
    user if one is not already present.  Then it runs as `git` (or whatever
    the hosting user is) and takes the pubkey and adds it as (to continue our
    example) `alice@localhost.pub` in keydir of the admin repo, which is then
    pushed.

    Notice the use of [this trick][oldmultikeys] to allow Alice to allow users
    to have other (gitolite normal) keys as well, such as perhaps from a
    laptop.

## setting up password access

Here's how to set this up.  First, the **one-time** tasks:

  * Do this first, or you'll forget :-)  Add the host key for 'localhost' to
    `/etc/ssh/ssh_known_hosts`.  And if it ever changes, update it.

  * Install gitolite as normal, if not already installed.  This will require
    you to use ssh keys for your (admin's) own access, but I assume that's ok.

  * As root, copy the program `contrib/real-users/gl-shell` to
    `/usr/local/bin`.

  * As root, customise the program `/usr/local/bin/gl-shell`.  You will need
    to change some variables at the top in a section clearly marked
    'site-local changes'.

  * As root, copy `contrib/real-users/gl-shell-setup` to some place on root's
    `$PATH` and customise it similarly to gl-shell.  Note that there are many
    more configurable values in this script.  **NOTE** also that this includes
    fixing the `chsh` command, which may be OS/distro dependent.  The supplied
    command is good for Fedora.

Now, for each user 'alice' that has her own real (unix) userid, and also needs
to access gitolite *via* her own id, run the command `gl-shell-setup alice`.

And that's really all there is to it.