Vault 12factor and Django integration

This project provides helper classes for integrating Hashicorp Vault <https://vaultproject.io/>__ with your Python projects and Django.

Please note that this is still under active development and APIs are subject to change.

Installation

This has been uploaded to the Cheeseshop aka Pypi as 12factor-vault <https://pypi.python.org/pypi/12factor-vault>__. So just add 12factor-vault to your requirements.txt or setup.py.

pip install 12factor-vault also works.

Environment variables +++++++++++++++++++++ ============================ ========================= ====================== Environment Variable Vault auth backend Direct configuration static method on BaseVaultAuthenticator ============================ ========================= ====================== VAULT_TOKEN Token authentication token(str) VAULT_APPID, VAULT_USERID App-id authenticaion app_id(str, str) VAULT_ROLEID, VAULT_SECRETID Approle authentication approle(str, str, str, bool) VAULT_SSLCERT, VAULT_SSLKEY SSL Client authentication ssl_client_cert(str, str) ============================ ========================= ======================

The Django example below uses the following environment variables:

=========================== ================================================== Environment Variable Description =========================== ================================================== VAULT_DATABASE_PATH The path to Vault's credential-issuing backend VAULT_CA The CA issuing Vault's HTTPS SSL certificate (for CA pinning) DATABASE_NAME Name of the database to connect to on the database server. DATABASE_OWNERROLE The PostgreSQL role to use for SET ROLE after connecting to the database =========================== ==================================================

General usage

Basically after configuring a BaseVaultAuthenticator instance which creates authenticated Vault clients (relying on the excellent hvac library <https://github.com/ianunruh/hvac>__) you can use that to create VaultCredentialProvider instances which manage leases and renew credentials as needed (e.g. database credentials managed by one of Vault's secrets backends).

VaultAuth12Factor is a subclass of BaseVaultAuthenticator that reads all necessary configuration from environment variables.

Django

Integrating with Django requires a small monkeypatch that retries failed database connections after refreshing the database credentials from Vault. The vault12factor Django App will install that patch automatically. You also have to wrap your database settings dict in a DjangoAutoRefreshDBCredentialsDict instance that knows hot to refresh database credentials from Vault.

vault12factor will check if an instance of DjangoAutoRefreshDBCredentialsDict is configured in settings.DATABASES before monkey-patching Django. So if you want to use vault12factor but configure your databases in separate Django apps or other things that this code can't detect, you will want to call vault12factor.monkeypatch_django() yourself.

Here is an example for integrating this with Django, using Vault to get database credentials. When using PostgreSQL you will also want to look at django-postgresql-setrole <https://github.com/jdelic/django-postgresql-setrole>__.

.. code-block:: python

# in settings.py
INSTALLED_APPS += ['django_dbconn_retry', 'vault12factor',]

from vault12factor import \
    VaultCredentialProvider, \
    VaultAuth12Factor, \
    DjangoAutoRefreshDBCredentialsDict

if DEBUG and not VaultAuth12Factor.has_envconfig():
    SECRET_KEY = "secretsekrit"  # FOR DEBUG ONLY!
    DATABASES = {
        'default': {
            'ENGINE': 'django.db.backends.sqlite3',
            'NAME': 'authserver.sqlite3',
        }
    }
else:
    if DEBUG:
        SECRET_KEY = "secretsekrit"  # FOR DEBUG ONLY!

    VAULT = VaultAuth12Factor.fromenv()
    CREDS = VaultCredentialProvider("https://vault.local:8200/", VAULT,
                                    os.getenv("VAULT_DATABASE_PATH",
                                    "db-mydatabase/creds/fullaccess"),
                                    os.getenv("VAULT_CA", None), True,
                                    DEBUG)

    DATABASES = {
        'default': DjangoAutoRefreshDBCredentialsDict(CREDS, {
            'ENGINE': 'django.db.backends.postgresql',
            'NAME': os.getenv("DATABASE_NAME", "mydatabase"),
            'USER': CREDS.username,
            'PASSWORD': CREDS.password,
            'HOST': '127.0.0.1',
            'PORT': '5432',
            # requires django-postgresql-setrole
            'SET_ROLE': os.getenv("DATABASE_OWNERROLE", "mydatabaseowner")
        }),
    }

Running the tests

The tests in test_project connect a Django project to PostgreSQL through Vault, configured like the example above, and use the Django test client. They need a PostgreSQL server and a Vault server. The GitHub Actions workflow in .github/workflows/django.yml sets both up. To run the tests locally, start a Vault dev server and run, as a PostgreSQL superuser, the SQL in .ci/postgresql_setup.sql. Then:

.. code-block:: shell

pip install -r requirements-test.txt -e .
export VAULT_ADDR=http://127.0.0.1:8200 VAULT_ROOT_TOKEN=<root token>
eval "$(.ci/configure_vault.sh)"
cd test_project
python manage.py test

.ci/configure_vault.sh and the tests use DATABASE_HOST and DATABASE_PORT (default 127.0.0.1:5432) to find PostgreSQL. Don't set VAULT_TOKEN, because the test project must authenticate using AppRole.

License

Copyright (c) 2016-2017, Jonas Maurus All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.