Helper functionality for obtaining secrets and credentials from Hashicorp Vault in a Django project
pip install django-vault-helpers==0.8.1
This is a helper library with the goal of making it easier to retrieve secrets from Hasicorp Vault from a Django project.
Install django-vault-helpers
from pip.
$ pip install django-vault-helpers
Add the new packages to your installed apps.
INSTALLED_APPS = [ ... 'vaulthelpers', ... ]
Configure connection settings using environment variables to authenticate to Vault.
Environment Variable | Description |
---|---|
VAULT_URL | Required. The URL of the Vault API. For example,
https://vault:8200/ . |
VAULT_CACERT | Optional. File path to the Vault CA certificate. |
VAULT_SKIP_VERIFY | Optional. Set to disable validation of Vault's SSL cert. |
VAULT_DEBUG | Optional. Enable Vault debug logging. |
In addition to the settings above, you must provide environment variables for one of the authentication methods below.
Environment Variable | Description |
---|---|
VAULT_TOKEN | Token for Vault Token authentication |
VAULT_APPID, VAULT_USERID | App-ID authentication |
VAULT_ROLEID, VAULT_SECRETID | App-Role authentication |
VAULT_SSLCERT, VAULT_SSLKEY | SSL Client Cert authentication |
To use Vault to load database connection configuration and credentials, configure the Vault database secret backend as described in the Database secret backend documentation. For example:
$ vault mount database Successfully mounted 'database' at 'database'! $ CONNECTION_NAME='myapplication' $ CONNECTION_URL='postgresql://vaultuser:FOO@mydb:5432/myapplication' $ PARENT_ROLE_NAME='myapplication' $ vault write "database/config/$CONNECTION_NAME" \ plugin_name="postgresql-database-plugin" \ allowed_roles="$CONNECTION_NAME" \ connection_url="$CONNECTION_URL" $ vault write "database/roles/$CONNECTION_NAME" \ db_name="$CONNECTION_NAME" \ creation_statements="CREATE ROLE \"{{name}}\" WITH LOGIN ENCRYPTED PASSWORD '{{password}}' VALID UNTIL '{{expiration}}' IN ROLE \"${PARENT_ROLE_NAME}\" INHERIT NOCREATEROLE NOCREATEDB NOSUPERUSER NOREPLICATION;" \ default_ttl="1h" \ max_ttl="24h"
Next, add settings via the following environment variables.
Environment Variable | Description |
---|---|
VAULT_DATABASE_PATH | Vault path to read from when fetching database credentials.
For example, database/creds/myapplication . |
DATABASE_URL | Database connection string, sans the username and password.
For example, postgres://mydb:5432/myapplication . |
DATABASE_OWNERROLE | For PostgreSQL, the name of the role to assume after
connecting using SET ROLE
|
Finally, edit your projects settings.py
file to load database configuration using Vault.
import vaulthelpers # Load database credentials from Vault DATABASES = { 'default': vaulthelpers.database.get_config(), }
To add additional keys to the database configuration, pass in a dictionary to the get_config
call. For example:
import vaulthelpers # Load database credentials from Vault DATABASES = { 'default': vaulthelpers.database.get_config({ 'ATOMIC_REQUESTS': True, 'CONN_MAX_AGE': 3600, }), }
To use Vault to load IAM or STS credentials for AWS, configure the Vault AWS secret backend as described in the AWS secret backend documentation.
$ vault mount aws Successfully mounted 'aws' at 'aws'! $ vault write aws/config/root \ access_key=AKIAJWVN5Z4FOFT7NLNA \ secret_key=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 \ region=us-east-1 $ vault write aws/roles/myapplication \ arn=arn:aws:iam::ACCOUNT-ID-WITHOUT-HYPHENS:role/MyApplicationRoleName
Next, add settings via the following environment variables.
Environment Variable | Description |
---|---|
VAULT_AWS_PATH | Vault path to read from when fetching AWS credentials.
For example, aws/sts/myapplication . |
Finally, configure you Django project to load AWS credentials using Vault. To do this, edit the settings.py
file to include the following line.
import vaulthelpers # Load AWS credentials from Vault vaulthelpers.aws.init_boto3_credentials()
This will override the credential resolve code in boto3
and botocore
so that it will fetch credentials from Vault instead of the usual means, like environment variables or the EC2 metadata service.
To directly access the authentication hvac
client connector, fetch it from the vaulthelpers.common
module.
import vaulthelpers vault_auth = vaulthelpers.common.get_vault_auth() verify = vaulthelpers.common.VAULT_CACERT or vaulthelpers.common.VAULT_SSL_VERIFY vcl = vault_auth.authenticated_client(vaulthelpers.common.VAULT_URL, verify=verify) result = vcl.read('secret/data/apps/myaplication') print(result)
12factor-vault
and django-postgresql-setrole
. When upgrading to this version, it is recommended to uninstall these packages.common.EnvironmentConfig
storages.backends.s3boto3.S3Boto3Storage
.