End-User Documentation

This chapter contains instructions targeted at users of projects that are using this library, so that you can link to thse from your onw documentation.

Configuration of Authentication Credentials

Credentials Lookup Details

When using HTTP APIs or other secured web resources, you usually want to store your credentials in a secure but still convenient fashion. Given a target that requires authentication in the form of a username and password or API token, the application will try several methods to find matching credentials in ‘common’ places.

For URLs (http, https, ftp, or ftps), the following steps will be taken:

  • The URL’s user@pwd part is checked first and used if present.

  • Next, the system’s keyring is queried for an entry under the URL’s host name.

  • Similarly, ~/.netrc is scanned for matching entries next.

  • If nothing can be found, you will be prompted on the console.

As a general fallback, any given target that is not an URL will ask for a username / password pair.

The keyring and netrc file are queried for an entry matching the hostname and account name, with the latter being taken from the URL if present, else the user’s login name is used. This allows you to easily assume different roles on a target system, e.g. to access a normal and a privileged account. So for an admin account, use something like https://admin@service.example.com/ and a matching password entry for admin on service.example.com.

In netrc files, the machine entries must be unique, so the name user@host is queried before the plain host name. This way you can provide credentials for several accounts on the same target in one file.

Installation Procedures

For using netrc files and prompting, nothing extra has to be installed, because Python has everything needed on board. By using keyring credentials, you gain more security (stored passwords are encrypted and only available after you logged in to your account), at the possible price of installing additional software. Consult the manual of your application whether any of the following installation steps are actually necessary and suitable — at least the keyring Python package will normally be included when you install an application.

On Windows and Mac OS X, you don’t need to install extra system software, but on a Linux system the OS package necessary for installing the dbus-python Python package has to be made available. On Debian-type systems, that means calling this command:

sudo apt-get install libdbus-glib-1-dev python-dev libffi-dev build-essential

For the Python packages, use pip as follows:

pip install secretstorage dbus-python keyring

For Windows and Mac OS X, only keyring is needed. To test that you installed all supporting libraries in a Linux setup, try this:

$ python -c "import keyring; print keyring.get_keyring()"
<keyring.backends.SecretService.Keyring object at 0x7f091526bcd0>

If it doesn’t work or the essential components are not installed, in the output you’ll get keyring.backends.fail.Keyring instead. A successful installation on other operating systems will show some different back-end that is not the ‘fail’ one.

On a Gnome desktop (e.g. Ubuntu 14.04 and up), the end-user application to manage passwords is seahorse a/k/a “Passwords and Keys”. It can be used to check that your passwords are stored correctly, and to change and delete them.