The following sections give you an overview of the main concepts of Bank-Vaults. Most of these apply equally to the bank-vaults
CLI and to the Vault operator, because under the hood the operator often uses the CLI tool with the appropriate parameters.
This is the multi-page printable view of this section. Click here to print.
Concepts
- 1: Initialize Vault and store the root token and unseal keys
- 2: Cloud permissions
- 3: External configuration for Vault
- 3.1: Fully or partially purging unmanaged configuration in Vault
- 3.2: Audit devices
- 3.3: Authentication
- 3.4: Plugins
- 3.5: Policies
- 3.6: Secrets engines
- 3.7: Startup secrets
1 - Initialize Vault and store the root token and unseal keys
Vault starts in an uninitialized state, which means it has to be initialized with an initial set of parameters. The response to the init request is the root token and unseal keys. After that, Vault becomes initialized, but remains in a sealed state.
Bank-Vaults stores the root token and the unseal keys in one of the following:
- AWS KMS keyring (backed by S3)
- Azure Key Vault
- Google Cloud KMS keyring (backed by GCS)
- Alibaba Cloud KMS (backed by OSS)
For development and testing purposes, the following solutions are also supported. Do not use these in production environments.
- Kubernetes Secrets (should be used only for development purposes)
- Dev Mode (useful for
vault server -dev
dev mode Vault servers) - Files (backed by files, should be used only for development purposes)
Keys stored by Bank-Vaults
Bank-Vaults stores the following keys:
vault-root
, which is Vault’s root token.vault-unseal-N
unseal keys, whereN
is a number, starting at 0 up to the maximum defined minus 1. For example, 5 unseal keys will bevault-unseal-0 ... vault-unseal-4
.
HashiCorp recommends revoking the root tokens after the initial set up of Vault has been completed.
Note: The
vault-root
token is not needed to unseal Vault, and can be removed from the storage if it was put there via the--init
call tobank-vaults
.
If you want to decrypt the root token for some reason, see Decrypt the root token.
Unseal Vault
Unsealing is the process of constructing the master key necessary to read the decryption key to decrypt data, allowing access to Vault. (From the official Vault documentation)
After initialization, Vault remains in a sealed state. In sealed state no secrets can reach or leave Vault until a person, possibly more people than one, unseals it with the required number of unseal keys.
Vault data and the unseal keys live together: if you delete a Vault instance installed by the operator, or if you delete the Helm chart, all your data and the unseal keys to that initialized state should remain untouched. For details, see the official documentation.
Note: If you change the unseal configuration after initializing Vault, you may have to move the unseal keys from the old location to the new one, or reinitialize vault.
The Bank-Vaults Init and Unseal process
Bank-Vaults runs in an endless loop and does the following:
- Bank-Vaults checks if Vault is initialized. If yes, it continues to step 2, otherwise Bank-Vaults:
- Calls Vault init, which returns the root token and the configured number of unseal keys.
- Encrypts the received token and keys with the configured KMS key.
- Stores the encrypted token and keys in the cloud provider’s object storage.
- Flushes the root token and keys from its memory with explicit garbage control as soon as possible.
- Bank-Vaults checks if Vault is sealed. If it isn’t, it continues to step 3, otherwise Bank-Vaults:
- Reads the encrypted unseal keys from the cloud provider’s object storage.
- Decrypts the unseal keys with the configured KMS key.
- Unseals Vault with the decrypted unseal keys.
- Flushes the keys from its memory with explicit garbage control as soon as possible.
- If the external configuration file was changed and an OS signal is received, then Bank-Vaults:
- Parses the configuration file.
- Reads the encrypted root token from the cloud provider’s object storage.
- Decrypts the root token with the configured KMS key.
- Applies the parsed configuration on the Vault API.
- Flushes the root token from its memory with explicit garbage control as soon as possible.
- Repeats from the second step after the configured time period.
1.1 - Decrypt the root token
If you want to decrypt the root token for some reason, see the section corresponding to the storage provider you used to store the token.
AWS
To use the KMS-encrypted root token with Vault CLI:
Required CLI tools:
- aws
Steps:
-
Download and decrypt the root token (and the unseal keys, but that is not mandatory) into a file on your local file system:
-
Save it as an environment variable:
Google Cloud
To use the KMS-encrypted root token with vault CLI:
Required CLI tools:
gcloud
gsutil
Kubernetes
There is a Kubernetes Secret backed unseal storage in Bank-Vaults, you should be aware of that Kubernetes Secrets are base64 encoded only if you are not using a EncryptionConfiguration in your Kubernetes cluster.
1.2 - Migrate unseal keys between cloud providers
Note: If you change the unseal configuration after initializing Vault, you may have to move the unseal keys from the old location to the new one, or reinitialize vault.
If you need to move your Vault instance from one provider or an external managed Vault, you have to:
- Retrieve and decrypt the unseal keys (and optionally the root token) in the Bank-Vaults format. For details, see Decrypt the root token.
- Migrate the Vault storage data to the new provider. Use the official migration command provided by Vault.
All examples assume that you have created files holding the root-token and the 5 unseal keys in plaintext:
vault-root.txt
vault-unseal-0.txt
vault-unseal-1.txt
vault-unseal-2.txt
vault-unseal-3.txt
vault-unseal-4.txt
AWS
Move the above mentioned files to an AWS bucket and encrypt them with KMS before:
2 - Cloud permissions
The operator and the bank-vaults
CLI command needs certain cloud permissions to function properly (init, unseal, configuration).
Google Cloud
The Service Account in which the Pod is running has to have the following IAM Roles:
- Cloud KMS Admin
- Cloud KMS CryptoKey Encrypter/Decrypter
- Storage Admin
A CLI example how to run bank-vaults based Vault configuration on Google Cloud:
Azure
The Access Policy in which the Pod is running has to have the following IAM Roles:
- Key Vault All Key permissions
- Key Vault All Secret permissions
AWS
Enable IAM OIDC provider for an EKS cluster
To allow Vault pods to assume IAM roles in order to access AWS services the IAM OIDC provider needs to be enabled on the cluster.
Getting the root token
After Vault is successfully deployed, you can query the root-token for admin access.
The Instance profile in which the Pod is running has to have the following IAM Policies:
- KMS:
kms:Encrypt, kms:Decrypt
- S3:
s3:GetObject, s3:PutObject
,s3:DeleteObject
on object level ands3:ListBucket
on bucket level
An example command how to init and unseal Vault on AWS:
When using existing unseal keys, you need to make sure to kms encrypt these with the proper EncryptionContext
.
If this is not done, the invocation of bank-vaults
will trigger an InvalidCiphertextException
from AWS KMS.
An example how to encrypt the keys (specify --profile
and --region
accordingly):
From this point on copy the encrypted files to the appropriate S3 bucket. As an additional security measure make sure to turn on encryption of the S3 bucket before uploading the files.
Alibaba Cloud
A CLI example how to run bank-vaults based Vault unsealing on Alibaba Cloud:
Kubernetes
The Service Account in which the bank-vaults Pod is running has to have the following Roles rules:
3 - External configuration for Vault
In addition to the standard Vault configuration, the operator and CLI can continuously configure Vault using an external YAML/JSON configuration. That way you can configure Vault declaratively using your usual automation tools and workflow.
The following sections describe the configuration sections you can use.
3.1 - Fully or partially purging unmanaged configuration in Vault
Bank-Vaults gives you a full control over Vault in a declarative style by removing any unmanaged configuration.
By enabling purgeUnmanagedConfig
you keep Vault configuration up-to-date.
So if you added a policy using Bank-Vaults then removed it from the configuration,
Bank-Vaults will remove it from Vault too. In other words, if you enabled purgeUnmanagedConfig
then any changes not in Bank-Vaults configuration will be removed (including manual changes).
WARNING:
This feature is
destructive
, so be careful when you enable it especially for the first time because it can delete all data in your Vault. Always test it a non-production environment first.
This feature is disabled by default and it needs to be enabled explicitly in your configuration.
Mechanism
Bank-Vaults handles unmanaged configuration by simply comparing what in Bank-Vaults configuration (the desired state) and what’s already in Vault (the actual state), then it removes any differences that are not in Bank-Vaults configuration.
Fully purge unmanaged configuration
You can remove all unmanaged configuration by enabling the purge option as following:
Partially purge unmanaged configuration
You can also enable the purge feature for some of the config by excluding any config that you don’t want to purge its unmanaged config.
It could be done by explicitly exclude the Vault configuration that you don’t want to mange:
This will remove any unmanaged or manual changes in Vault but it will leave secrets
untouched.
So if you enabled a new secret engine manually (and it’s not in Bank-Vaults configuration),
Bank-Vaults will not remove it.
3.3 - Authentication
You can configure Auth Methods in Vault.
Currently the following auth methods are supported:
AppRole auth method
Allow machines/apps to authenticate with Vault-defined roles. For details, see the official Vault documentation.
AWS auth method
Creating roles in Vault which can be used for AWS IAM based authentication.
Azure auth method
The Azure auth method allows authentication against Vault using Azure Active Directory credentials for more information.
GCP auth method
Create roles in Vault which can be used for GCP IAM based authentication.
GitHub auth method
Create team mappings in Vault which can be used later on for the GitHub authentication.
JWT auth method
Create roles in Vault which can be used for JWT-based authentication.
Kubernetes auth method
Use the Kubernetes auth method to authenticate with Vault using a Kubernetes Service Account Token.
LDAP auth method
Create group mappings in Vault which can be used for LDAP based authentication.
- To start an LDAP test server, run: docker run -it –rm -p 389:389 -e LDAP_TLS=false –name ldap osixia/openldap
- To start an LDAP admin server, run: docker run -it –rm -p 6443:443 –link ldap:ldap -e PHPLDAPADMIN_LDAP_HOSTS=ldap -e PHPLDAPADMIN_LDAP_CLIENT_TLS=false osixia/phpldapadmin
3.4 - Plugins
To register a new plugin in Vault’s plugin catalog, set the plugin_directory option in the Vault server configuration to the directory where the plugin binary is located. Also, for some plugins readOnlyRootFilesystem Pod Security Policy should be disabled to allow RPC communication between plugin and Vault server via Unix socket. For details, see the Hashicorp Go plugin documentation.
3.5 - Policies
You can create policies in Vault, and later use these policies in roles for the Kubernetes-based authentication. For details, see Policies in the official Vault documentation.
3.6 - Secrets engines
You can configure Secrets Engines in Vault. The Key-Value, Database, and SSH values are tested, but the configuration is free form, so probably others work as well.
AWS
The AWS secrets engine generates AWS access credentials dynamically based on IAM policies.
Consul
The Consul secrets engine generates Consul ACL tokens dynamically based on policies created in Consul.
Database
This plugin stores database credentials dynamically based on configured roles for the MySQL/MariaDB database.
Identity Groups
Allows you to configure identity groups.
Note:
Only external groups are supported at the moment through the use of group-aliases. For supported authentication backends (for example JWT, which automatically matches those aliases to groups returned by the backend) the configuration files for the groups and group-aliases need to be parsed after the authentication backend has been mounted. Ideally they should be in the same file to avoid of errors.
Key-Values
This plugin stores arbitrary secrets within the configured physical storage for Vault.
Non-default plugin path
Mounts a non-default plugin’s path.
PKI
The PKI secrets engine generates X.509 certificates.
RabbitMQ
The RabbitMQ secrets engine generates user credentials dynamically based on configured permissions and virtual hosts.
To start a RabbitMQ test server, run: docker run -it –rm -p 15672:15672 rabbitmq:3.7-management-alpine
SSH
Create a named Vault role for signing SSH client keys.
3.7 - Startup secrets
Allows writing some secrets to Vault (useful for development purposes). For details, see the Key-Value secrets engine.