Skip to content

CIRCLE / django-sshkey

Go to a project
Commit 76a1dd88 by Scott Duckworth
Options

update readme for new lookup commands

parent 1bc2e8d1
Showing with 99 additions and 55 deletions
README.md
django-sshkey lets you use a patched OpenSSH server to authenticate incoming # django-sshkey
SSH connections via public key authentication and identify the Django User that
owns that key.
# The OpenSSH Patch django-sshkey allows you to associate SSH public keys to 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
`AuthorizedKeysCommand` feature in [OpenSSH][1] 6.2 and above.
At the top level of this repository is a patch for OpenSSH 6.2p2 which modifies ## The Django app
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 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
The Django app is located in the django\_sshkey directory at the top level of templates for the views (example templates are provided in the source).
this repository. You should point Django to it in your project's settings.py
or copy it into your project's directory.
In order to associate an incoming public key with a user you must define In order to associate an incoming public key with a user you must define
SSHKEY\_AUTHORIZED\_KEYS\_OPTIONS in your project's settings.py. This should `SSHKEY_AUTHORIZED_KEYS_OPTIONS` in your project's `settings.py`. This should
be a string containing options accepted by sshd, with "{username}" being be a string containing options accepted by sshd, with `{username}` being
replaced with the username of the user associated with the incoming public key. replaced with the username of the user associated with the incoming public key.
For instance: For instance:
...@@ -27,74 +24,121 @@ For instance: ...@@ -27,74 +24,121 @@ For instance:
in settings.py will cause keys produced by the below commands to look similar in settings.py will cause keys produced by the below commands to look similar
to: to:
command="my-command fred",no-pty ssh-rsa BLAHBLAHBLAH command="my-command fred",no-pty ssh-rsa AAAAB3NzaC1yc2E...
assuming the key "BLAHBLAHBLAH" is owned by fred. assuming the key `AAAAB3NzaC1yc2E...` is owned by fred.
## URL Configuration ### URL Configuration
This text assumes that your Django project's urls.py maps django\_sshkey.urls into the This text assumes that your project's `urls.py` maps `django_sshkey.urls` into
url namespace as follows: the URL namespace as follows:
import django_sshkey.urls
urlpatterns = patterns('', urlpatterns = patterns('',
... ...
url('^sshkey/', include(django_sshkey.urls)), url('^sshkey/', include(django_sshkey.urls)),
... ...
) )
You will need to adjust your URLs if you use a different mapping. You will need to adjust your URLs in the examples below if you use a different
mapping.
# Tying OpenSSH's AuthorizedKeysCommand to the django-sshkey **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).
There are three provided ways of connecting AuthorizedKeysCommand to Django. ## Tying OpenSSH to django-sshkey
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:
## Using django-sshkey-lookup 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.
*Usage: django-sshkey-lookup URL [USERNAME]* 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`.
URL should be the full URL to /sshkey/lookup on your Django web server running Additionally, all of the methods below use either `curl` (preferred) or `wget`.
the sshkey app. Some commands also use `ssh-keygen`. These commands must be present in `PATH`.
If USERNAME is specified, lookup keys owned by that user and print them to If you would prefer not to use these external commands then there are variants
standard output. Any standard input is ignored. 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`.
If USERNAME is not specified, the incoming public key should be provided on ### Using `django-sshkey-lookup-all`
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 `Usage: django-sshkey-lookup-all`
curl, are found in $PATH.
This command is equivalent to the old script `lookup.sh` but was renamed to This program prints all SSH public keys that are defined on your site. sshd
have a less ambiguous name when installed system-wide. A symlink is left in will have to scan through all of them to find the first match, so with many
its place for backwards compatibility. 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`
This is generally the fastest method. `Usage: django-sshkey-lookup-by-username USERNAME`
## Using django-sshkey-pylookup This program prints all SSH public keys that are associated with the specified
user.
*Usage: django-sshkey-pylookup URL [USERNAME]* This program:
Same as above, but it's all written in Python and doesn't rely on external * can be used directly with `AuthorizedKeysCommand`.
commands. * does not require a patched OpenSSH server.
* is ideal if each Django user corresponds to a system user account.
This script is generated by setuptools when this package is installed. The old ### Using `django-sshkey-lookup-by-fingerprint`
equivalent, `lookup.py` is available with a deprecation warning for backwards
compatibility.
The parent directory of the django\_sshkey app must be in PYTHONPATH. `Usage: django-sshkey-lookup-by-fingerprint`
This is generally the second fastest method. 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:
## Using manage.py sshkey\_authorized\_keys\_command 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.
*Usage: PATH\_TO\_DJANGO\_PROJECT/manage.py sshkey\_authorized\_keys\_command [USERNAME]* This program:
Same semantics for USERNAME as above. * 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.
This method does not rely on the /sshkey/lookup URL, and instead creates its ### Using `django-sshkey-lookup`
own database connection each time it is invoked.
`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.
This is generally the slowest method. [1]: http://www.openssh.com/
[2]: https://github.com/ScottDuckworth/openssh-akcenv
[3]: https://github.com/ScottDuckworth/openssh-stdinkey
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or sign in to comment