README.md 5.79 KB
Newer Older
1
# django-sshkey
Scott Duckworth committed
2

3 4 5 6
django-sshkey allows you to associate multiple SSH public keys with Django
user accounts.  It provides views to list, add, edit, and delete keys, each of
which is intended for end-user consumption.  It also provides a lookup view
and corresponding lookup commands that are suitable for use with the
7
`AuthorizedKeysCommand` feature in [OpenSSH][1] 6.2 and above.
Scott Duckworth committed
8

9
## The Django app
Scott Duckworth committed
10

11 12 13
To use django-sshkey in your Django project, simply add `django_sshkey` to
`INSTALLED_APPS` in `settings.py`, map the URLs into your project, and provide
templates for the views (example templates are provided in the source).
Scott Duckworth committed
14 15

In order to associate an incoming public key with a user you must define
16 17
`SSHKEY_AUTHORIZED_KEYS_OPTIONS` in your project's `settings.py`.  This should
be a string containing options accepted by sshd, with `{username}` being
18
replaced with the username of the user associated with the incoming public key.
Scott Duckworth committed
19 20

For instance:
21

22
    SSHKEY_AUTHORIZED_KEYS_OPTIONS = 'command="my-command {username}",no-pty'
23

Scott Duckworth committed
24 25
in settings.py will cause keys produced by the below commands to look similar
to:
26

27
    command="my-command fred",no-pty ssh-rsa AAAAB3NzaC1yc2E...
28

29
assuming the key `AAAAB3NzaC1yc2E...` is owned by fred.
Scott Duckworth committed
30

31
### URL Configuration
Scott Duckworth committed
32

33 34
This text assumes that your project's `urls.py` maps `django_sshkey.urls` into
the URL namespace as follows:
Scott Duckworth committed
35

36
    import django_sshkey.urls
37 38 39 40 41
    urlpatterns = patterns('',
      ...
      url('^sshkey/', include(django_sshkey.urls)),
      ...
    )
Scott Duckworth committed
42

43 44
You will need to adjust your URLs in the examples below if you use a different
mapping.
Scott Duckworth committed
45

46 47 48 49
**WARNING**: The `/sshkey/lookup` URL can expose all public keys that have
been uploaded to your site.  Although they are public keys, it is probably a
good idea to limit what systems can access this URL via your web server's
configuration (most of the lookup methods below require access to this URL).
Scott Duckworth committed
50

51
## Tying OpenSSH to django-sshkey
Scott Duckworth committed
52

53 54 55 56 57
There are multiple methods of connecting OpenSSH to django-sshkey.  All of the
methods listed here require the use of the `AuthorizedKeysCommand` directive
in `sshd_config` present in OpenSSH 6.2 and above.  Please note that the
command that is referenced by this directive and its ancestor directories must
be owned by root and writable only by owner.
Scott Duckworth committed
58

59 60 61 62 63 64
Unless otherwise stated, all of the methods below use the `SSHKEY_LOOKUP_URL`
environment variable to determine the URL of the `/sshkey/lookup` URL.  If
this environment variable is not defined then it will default to
`http://localhost:8000/sshkey/lookup`.  If this environment variable is
defined in the sshd process then it will be inherited by the
`AuthorizedKeysCommand`.
Scott Duckworth committed
65

66 67
Additionally, all of the methods below use either `curl` (preferred) or `wget`.
Some commands also use `ssh-keygen`.  These commands must be present in `PATH`.
Scott Duckworth committed
68

69 70 71 72
If you would prefer not to use these external commands then there are variants
of these commands implemented purely in Python.  However, they are *much*
slower.  To use the variants, replace `lookup` with `pylookup`.  For example,
use `django-sshkey-pylookup-all` instead of `django-sshkey-lookup-all`.
Scott Duckworth committed
73

74
### Using `django-sshkey-lookup-all`
Scott Duckworth committed
75

76
`Usage: django-sshkey-lookup-all`
Scott Duckworth committed
77

78 79 80 81 82 83 84 85 86 87 88 89 90
This program prints all SSH public keys that are defined on your site.  sshd
will have to scan through all of them to find the first match, so with many
keys this method will be slow.  However, it does not require a patched OpenSSH
server.

This program:

  * can be used directly with `AuthorizedKeysCommand` (the username parameter
    is ignored).
  * does not require a patched OpenSSH server.
  * does not scale well to a large number of user keys.

### Using `django-sshkey-lookup-by-username`
91

92
`Usage: django-sshkey-lookup-by-username USERNAME`
Scott Duckworth committed
93

94 95
This program prints all SSH public keys that are associated with the specified
user.
96

97
This program:
Scott Duckworth committed
98

99 100 101
  * can be used directly with `AuthorizedKeysCommand`.
  * does not require a patched OpenSSH server.
  * is ideal if each Django user corresponds to a system user account.
Scott Duckworth committed
102

103
### Using `django-sshkey-lookup-by-fingerprint`
104

105
`Usage: django-sshkey-lookup-by-fingerprint`
106

107 108
This program prints all SSH public keys that match the given fingerprint.  The
fingerprint is determined by the first of the following conditions that is met:
Scott Duckworth committed
109

110 111 112 113 114 115 116
  1. The `SSH_KEY_FINGERPRINT` environment variable, which should contain the
     MD5 fingerprint of the key (this is what is generated by `ssh-keygen -l`).
  2. The `SSH_KEY` environment variable, which should contain the key in
     standard openssh format (the same format as `~/.ssh/id_rsa.pub`), is sent
     to `ssh-keygen -l` to determine the fingerprint.
  3. The key in standard openssh format is read from standard input and is
     sent to `ssh-keygen -l` to determine the fingerprint.
Scott Duckworth committed
117

118
This program:
Scott Duckworth committed
119

120 121 122 123 124 125 126 127
  * can be used directly with `AuthorizedKeysCommand` (the username parameter
    is ignored).
  * requires a patched OpenSSH server; compatible patches can be found at one
    of the following locations:
      * [openssh-akcenv][2] (this is the preferred patch)
      * [openssh-stdinkey][3]
  * is ideal if you want all Django users to access SSH via a shared system
    user account and be identified by their SSH public key.
Scott Duckworth committed
128

129 130 131 132 133 134 135 136 137 138 139 140
### Using `django-sshkey-lookup`

`Usage: django-sshkey-lookup URL [USERNAME]`

This program is a wrapper around the previous two commands.  The first
parameter is placed in the `SSHKEY_LOOKUP_URL` environment variable.  If the
second parameter is present then `django-sshkey-lookup-by-username` is
executed; otherwise `django-sshkey-lookup-by-fingerprint` is executed.

This command is compatible with the old script `lookup.sh` but was renamed to
have a less ambiguous name when installed system-wide. A symlink is left in
its place for backwards compatibility.
Scott Duckworth committed
141

142 143 144
[1]: http://www.openssh.com/
[2]: https://github.com/ScottDuckworth/openssh-akcenv
[3]: https://github.com/ScottDuckworth/openssh-stdinkey