Skip to content

CIRCLE / django-sshkey

Go to a project
Commit 8ffef33a by Scott Duckworth
Options

replace markdown with reStructuredText

parent ded927a9
Showing with 226 additions and 197 deletions
README.md deleted 100644 → 0
# django-sshkey
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
`AuthorizedKeysCommand` feature in [OpenSSH][1] 6.2 and above.
## 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
templates for the views (example templates are provided in the source).
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
be a string containing options accepted by sshd, with `{username}` being
replaced with the username of the user associated with the incoming public key.
For instance:
SSHKEY_AUTHORIZED_KEYS_OPTIONS = 'command="my-command {username}",no-pty'
in settings.py will cause keys produced by the below commands to look similar
to:
command="my-command fred",no-pty ssh-rsa AAAAB3NzaC1yc2E...
assuming the key `AAAAB3NzaC1yc2E...` is owned by fred.
### URL Configuration
This text assumes that your project's `urls.py` maps `django_sshkey.urls` into
the URL namespace as follows:
import django_sshkey.urls
urlpatterns = patterns('',
...
url('^sshkey/', include(django_sshkey.urls)),
...
)
You will need to adjust your URLs in the examples below if you use a different
mapping.
**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).
## Tying OpenSSH to django-sshkey
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.
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`.
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`.
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`.
### Using `django-sshkey-lookup-all`
`Usage: django-sshkey-lookup-all`
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`
`Usage: django-sshkey-lookup-by-username USERNAME`
This program prints all SSH public keys that are associated with the specified
user.
This program:
* 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.
### Using `django-sshkey-lookup-by-fingerprint`
`Usage: django-sshkey-lookup-by-fingerprint`
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:
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.
This program:
* 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.
### 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.
[1]: http://www.openssh.com/
[2]: https://github.com/ScottDuckworth/openssh-akcenv
[3]: https://github.com/ScottDuckworth/openssh-stdinkey
README.rst 0 → 100644
=============
django-sshkey
=============
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
``AuthorizedKeysCommand`` feature in OpenSSH_ 6.2 and above.
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 templates for the views (example templates are provided in the source).
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 be a string containing options accepted by sshd, with ``{username}``
being replaced with the username of the user associated with the incoming
public key.
For instance::
SSHKEY_AUTHORIZED_KEYS_OPTIONS = 'command="my-command {username}",no-pty'
in settings.py will cause keys produced by the below commands to look similar
to::
command="my-command fred",no-pty ssh-rsa AAAAB3NzaC1yc2E...
assuming the key ``AAAAB3NzaC1yc2E...`` is owned by fred.
URL Configuration
-----------------
This text assumes that your project's ``urls.py`` maps ``django_sshkey.urls``
into the URL namespace as follows::
import django_sshkey.urls
urlpatterns = patterns('',
...
url('^sshkey/', include(django_sshkey.urls)),
...
)
You will need to adjust your URLs in the examples below if you use a different
mapping.
.. 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,
and only the systems that need to run the lookup commands should have access
to it.
Tying OpenSSH to django-sshkey
==============================
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.
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``.
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``.
If you would prefer not to use these external commands then there are variants
of the lookup 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``.
Using ``django-sshkey-lookup-all``
----------------------------------
``Usage: django-sshkey-lookup-all``
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``
------------------------------------------
``Usage: django-sshkey-lookup-by-username USERNAME``
This program prints all SSH public keys that are associated with the specified
user.
This program:
* 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.
Using ``django-sshkey-lookup-by-fingerprint``
---------------------------------------------
``Usage: django-sshkey-lookup-by-fingerprint``
This program prints all SSH public keys that match the given fingerprint. The
fingerprint is determined by the first of the following that is found:
1. The ``SSH_KEY_FINGERPRINT`` environment variable, which should contain
the MD5 fingerprint of the key (this is the second field 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.
This program:
* 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_ (this is the preferred patch)
- openssh-stdinkey_
* 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.
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.
.. _OpenSSH: http://www.openssh.com/
.. _openssh-akcenv: https://github.com/ScottDuckworth/openssh-akcenv
.. _openssh-stdinkey: https://github.com/ScottDuckworth/openssh-stdinkey
README.upgrading.md deleted 100644 → 0
Upgrading and Downgrading
=========================
django-sshkey is equipped with [South][1] migrations. This makes changes to
the database schema in upgrades or downgrades a simple process. Migrations
will only be present on minor version changes.
To use South migrations, you must have the south app in your project's
INSTALLED_APPS.
The following table maps django-sshkey version to migration labels:
Version App Name Label Notes
1.0.x sshkey 0001 Migrations were not present in 1.0.x
1.1.x sshkey 0002
2.0.x django_sshkey 0001 See Upgrading from 1.1.x to 2.x below
To upgrade, install the new version of django-sshkey and then migrate your
project to its corresponding label from the table above using the following
command:
python manage.py migrate <app_name> <label>
To downgrade, perform the migration down to the label of the desired version
before installing the older django-sshkey.
Upgrading from 1.1.x to 2.x
---------------------------
django-sshkey 2.x renames the sshkey app to django_sshkey. However, the
database table names are not changed.
To upgrade, all references to the sshkey module must be changed to
django_sshkey. This includes all instances of "import sshkey" or
"from sshkey import ..." and all references to sshkey in url patterns, views,
or templates, as well as updating INSTALLED_APPS in settings.py.
Once you have made those changes you will need to fake the initial migration
for django_sshkey:
python manage.py migrate --fake django_sshkey 0001_initial
This completes the upgrade process. The only thing that remains is the two
existing migration records in the south_migrationhistory table from the now
nonexistent sshkey app. These records do not cause any problems, but they can
be removed at your discrection using the following SQL statement on your
database:
DELETE FROM south_migrationhistory WHERE app_name="sshkey";
[1]: http://south.aeracode.org/
README.upgrading.rst 0 → 100644
Upgrading and Downgrading
=========================
django-sshkey is equipped with South_ migrations. This makes changes to the
database schema in upgrades or downgrades a simple process. Migrations will
only be present on minor version changes.
To use South migrations, you must have the south app in your project's
``INSTALLED_APPS``.
The following table maps django-sshkey version to migration labels:
+---------+---------------+-------+------------------------------------------+
| Version | App Name | Label | Notes |
+=========+===============+=======+==========================================+
| 1.0 | sshkey | 0001 | Migrations were not present in 1.0.x |
+---------+---------------+-------+------------------------------------------+
| 1.1 | sshkey | 0002 | |
+---------+---------------+-------+------------------------------------------+
| 2.0+ | django_sshkey | 0001 | See Upgrading from 1.1.x to 2.x below |
+---------+---------------+-------+------------------------------------------+
To upgrade, install the new version of django-sshkey and then migrate your
project to its corresponding label from the table above using the following
command::
python manage.py migrate APP_NAME LABEL
To downgrade, perform the migration down to the label of the desired version
before installing the older django-sshkey.
Upgrading from 1.1.x to 2.x
---------------------------
django-sshkey 2.x renames the sshkey app to django_sshkey. However, the
database table names are not changed.
To upgrade, all references to the sshkey module must be changed to
django_sshkey. This includes all instances of ``import sshkey`` or
``from sshkey import ...`` and all references to sshkey in URL patterns,
views, or templates, as well as updating ``INSTALLED_APPS`` in ``settings.py``.
Once you have made those changes you will need to fake the initial migration
for django_sshkey::
python manage.py migrate --fake django_sshkey 0001_initial
This completes the upgrade process. The only thing that remains is the two
existing migration records in the ``south_migrationhistory`` table from the
now nonexistent sshkey app. These records do not cause any problems, but they
can be removed at your discrection using the following SQL statement on your
database::
DELETE FROM south_migrationhistory WHERE app_name="sshkey";
.. _South: http://south.aeracode.org/
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