README.md 3.05 KB
Newer Older
Scott Duckworth committed
1 2 3 4 5 6 7 8 9 10 11 12 13
django-sshkey lets you use a patched OpenSSH server to authenticate incoming
SSH connections via public key authentication and identify the Django User that
owns that key.

# The OpenSSH Patch

At the top level of this repository is a patch for OpenSSH 6.2p2 which modifies
the AuthorizedKeysCommand config option so that the incoming SSH public key is
passed to the command via standard input.  The incoming username will still be
passed as the first argument to the specified command.

# The Django app

14 15 16
The Django app is located in the django\_sshkey directory at the top level of
this repository.  You should point Django to it in your project's settings.py
or copy it into your project's directory.
Scott Duckworth committed
17 18

In order to associate an incoming public key with a user you must define
19 20 21
SSHKEY\_AUTHORIZED\_KEYS\_OPTIONS in your project's settings.py.  This should
be a string containing options accepted by sshd, with "{username}" being
replaced with the username of the user associated with the incoming public key.
Scott Duckworth committed
22 23

For instance:
24

25
    SSHKEY_AUTHORIZED_KEYS_OPTIONS = 'command="my-command {username}",no-pty'
26

Scott Duckworth committed
27 28
in settings.py will cause keys produced by the below commands to look similar
to:
29

30
    command="my-command fred",no-pty ssh-rsa BLAHBLAHBLAH
31 32

assuming the key "BLAHBLAHBLAH" is owned by fred.
Scott Duckworth committed
33 34 35

## URL Configuration

36
This text assumes that your Django project's urls.py maps django\_sshkey.urls into the
Scott Duckworth committed
37 38
url namespace as follows:

39 40 41 42 43
    urlpatterns = patterns('',
      ...
      url('^sshkey/', include(django_sshkey.urls)),
      ...
    )
Scott Duckworth committed
44 45 46

You will need to adjust your URLs if you use a different mapping.

47
# Tying OpenSSH's AuthorizedKeysCommand to the django-sshkey
Scott Duckworth committed
48 49 50 51 52 53

There are three provided ways of connecting AuthorizedKeysCommand to Django.
In all cases it is recommended and/or required that the command specified with
AuthorizedKeysCommand be a shell script that is owned by and only writable by
root which invokes one of the commands below:

54
## Using lookup.sh
Scott Duckworth committed
55

56
*Usage: lookup.sh URL [USERNAME]*
Scott Duckworth committed
57 58 59 60 61 62 63 64 65 66 67 68 69 70 71

URL should be the full URL to /sshkey/lookup on your Django web server running
the sshkey app.

If USERNAME is specified, lookup keys owned by that user and print them to
standard output. Any standard input is ignored.

If USERNAME is not specified, the incoming public key should be provided on
standard input; if the key is found it is printed to standard output.

This command assumes that some fairly standard commands, like ssh-keygen and
curl, are found in $PATH.

This is generally the fastest method.

72 73 74
## Using lookup.py

*Usage: lookup.py URL [USERNAME]*
Scott Duckworth committed
75 76 77 78

Same as above, but it's all written in Python and doesn't rely on external
commands.

79
The parent directory of the django\_sshkey app must be in PYTHONPATH.
80

Scott Duckworth committed
81 82
This is generally the second fastest method.

83
## Using manage.py sshkey\_authorized\_keys\_command
Scott Duckworth committed
84

85
*Usage: PATH\_TO\_DJANGO\_PROJECT/manage.py sshkey\_authorized\_keys\_command [USERNAME]*
Scott Duckworth committed
86 87 88 89 90 91 92

Same semantics for USERNAME as above.

This method does not rely on the /sshkey/lookup URL, and instead creates its
own database connection each time it is invoked.

This is generally the slowest method.