Integration with Hashicorp Vault¶
Relational database authentication¶
Before you start¶
Goal
- Use credentials from Vault for Relational database authentication.
Prerequisites
Hub supports using authentication credentials for the database from a secret in the KV secrets engine or the database secrets engine.
To configure Altair SLC Hub to use authentication information from Vault, it
is necessary to set the database.vaultSecret
Hub configuration parameter to the
path of the Vault secret.
KV secrets engine¶
It is expected that the secret contain username
and
password
properties.
The Hub manages a pool of database connections. Each time a new connection is required,
it will retrieve the authentication secret from Vault. In the case of the static
KV secrets engine, we recommend specifying the Hub database.maxConnLifetime
configuration parameter. This limits the lifetime of any connections that Hub makes,
and so ensures that Hub will periodically re-fetch the authentication credentials
from Vault. This ensures that if the authentication credentials are changed in Vault,
Hub will use the updated credentials.
Database secrets engine¶
Altair SLC Hub supports the Vault database secrets engine for dynamically allocated authentication roles. For details of setting up the database secrets engine, see the Vault documentation.
Due to the way that Hub manages its own database schema migrations, and due to the way that PostgreSQL handles table ownership, it is necessary to create a role in PostgreSQL that will be the owner of the tables and has full permissions on the tables. This role should not have any authentication information associated with it in PostgreSQL. For example, in a PostgreSQL command prompt, a role can be created as follows:
CREATE ROLE HUBROLE;
GRANT ALL ON ALL TABLES IN SCHEMA public TO HUBROLE;
Assuming that the database role that has been
created is called HUBROLE
, the Vault command for configuring the role in Vault should be as
follows (adjust the default_ttl
and max_ttl
values as appropriate)
vault write database/roles/hub-role \
db_name=hub-postgresql-database \
creation_statements="CREATE ROLE \"{{ name }}\" WITH LOGIN PASSWORD '{{ password }}' VALID UNTIL '{{ expiration }}'; \
GRANT HUB_ROLE TO \"{{ name }}\";" \
default_ttl="1h" \
max_ttl="24h"
It is then necessary to configure the Hub database.setRole
configuration parameter to the
name of the role. This ensures that Hub issues a PostgreSQL SET ROLE
command on each
database connection so that any commands or queries it executes are executed using
that role rather than the dynamically created role that Vault issues. This ensures
that any tables created by Hub are owned by this fixed role.
Verification¶
Verify database
- run the hubctl verify db command.
Before continuing it is necessary to verify that the connection information for the database is correct.
This can be done using the hubctl
command, as follows:
hubctl verify db