Gitolite usernames in authorized_keys file

Question 1

User names and repo names are as simple as possible; they must start with an alphanumeric, but after that they can also contain ., _, or -.

Usernames can optionally be followed by an @ and a domainname containing at least one . (this allows you to use an email address as someone's username).

Your naming convention doesn't follow the proper syntax for having an '@'.

You can see this rule in action in src/triggers/post-compile/ssh-authkeys

sub optionise {
    my $f = shift;

    my $user = $f;
    $user =~ s(.*/)(); # foo/bar/baz.pub -> baz.pub
    $user =~ s/(\@[^.]+)?\.pub$//; # baz.pub, baz@home.pub -> baz

    my @line = slurp($f);
    if ( @line != 1 ) {
        _warn "$f does not contain exactly 1 line; ignoring";
        return '';
    }
    chomp(@line);
    return "command=\"$glshell $user" . ( $kfn ? " $f" : "" ) . "\",$auth_options $line[0]";
}

Question 2

You should really never need to directly modify the Gitolite section of the authorized_keys file.

The idea of the @suffix addition to keyfile pathnames is that it allows the administrator to easily add multiple keys for a single Gitolite user. In your case, keydir/alex@workbox.pub and keydir/alex@homebox.pub are both mapped to a single Gitolite user named alex. This is usually what you want if both of those keys are “owned” by the same person; it lets you just use alex in the configuration file instead of having to mention both keyfile names. If those keys are owned by different people (or you want to enforce different access restrictions for a person’s different keys), then you will need to name them slightly differently (either use a separator other than @, or include at least one period between the @ and .pub).

Multiple Keys per User

The Gitolite documentation section named “multiple keys per user” describes the ways you can configure multiple keys for a single Gitolite user. There are two main ways:

put files named username.pub in different subdirectories of keydir (the newer method),
put an @ suffix after the username (the older method, which has sometimes been difficult for Gitolite admins to grok).

With the subdirectory method, you would use pathnames like these:

keydir/workbox/alex.pub
keydir/homebox/alex.pub

With the suffix method, you would use pathnames like these:

keydir/alex@workbox.pub
keydir/alex@homebox.pub

All of the above pathnames supply keys that will authenticate as the Gitolite user named alex (no @ in the user’s name); you would use (e.g.) RW+ = alex in the configuration file. These methods (only using a portion of the key’s pathname to form the Gitolite username) let the admin add (and remove) keys for Gitolite users without having to edit the configuration file every time someone wants to use a new key (or loses access to (or control of) an old key).

For example, if alex gets a new mobile device, you could add keydir/mobile/alex.pub or keydir/alex@mobile.pub to give that key access to everything that alex can already access.

Email-style Usernames

There is a limitation to the suffix method: the suffix must not contain a period. This limitation exists so that you can use email addresses as usernames; you can still use suffixes (or subdirectories) with such usernames. The following key pathnames could be used to supply keys for the username jane@gmail.com (@gmail.com is a part of username):

keydir/external/jane@gmail.com.pub
keydir/jane@gmail.com@remotebox.pub

This jane@gmail.com user is distinct from a plain jane user.

Note: By manually adding an @workbox suffix to the authorized_keys entry, you effectively forced Gitolite to use an email-type username that contained no period (based on how the keydir pathnames are parsed into usernames, this is normally impossible).

Which to Use?

It seems like subdirectories make the most sense when you expect to be able to fit your users’ keys into a limited number of categories (home, work, mobile, etc.). The @-suffixes seem useful if you have one-off keys that do not fit in any particular category.

Independent of subdirectory/suffix, email-style usernames might be useful for anyone that does not otherwise have a canonical username inside your organization (e.g. a temporary outside contractor).

Summary

Gitolite usernames are derived from the pathnames under keydir, but the are not identical to the filenames used there. Specifically, the keydir pathnames are mapped to usernames by stripping any subdirectories and removing the .pub extension along with any @ suffixes (as long as there is no period after the @—otherwise the @ is treated as part of an email-style username).

If you have a situation where a single person wants to use multiple keys, then you should probably use one of the above methods (subdirectories, or @ suffix (without a period)) to let you map multiple keys to a single Gitolite username.

Example: install keydir/workbox/alex.pub and keydir/homebox/alex.pub, then use alex in the configuration file (giving equal access to both keys).

If you have keys for different people that you want to give similar names, or you want to authorize different access for a single person’s various keys (home access is read only?), then you should use a separator other than @ between the distinguishing parts of the username (or make sure there is a period after the @ so it is treated as an email-style username).

Example: install keydir/workbox/alex.pub, keydir/homebox/alex-ro.pub, and mobile/alex-ro.pub, then use alex and alex-ro in the configuration file (e.g. in some way that gives alex-ro read-only access, while alex gets read-write access).