fa9c5dc67c
* docs: Update Database Capabilities to include username customization * add operator/diagnose to the index file
112 lines
4.2 KiB
Plaintext
112 lines
4.2 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Snowflake - Database - Secrets Engines
|
|
description: |-
|
|
Snowflake is one of the supported plugins for the database secrets engine.
|
|
This plugin generates database credentials dynamically based on configured
|
|
roles for Snowflake hosted databases.
|
|
---
|
|
|
|
# Snowflake Database Secrets Engine
|
|
|
|
Snowflake is one of the supported plugins for the database secrets engine. This
|
|
plugin generates database credentials dynamically based on configured roles for
|
|
Snowflake hosted databases, and also supports [Static
|
|
Roles](/docs/secrets/databases#static-roles).
|
|
|
|
See the [database secrets engine](/docs/secrets/databases) docs for
|
|
more information about setting up the database secrets engine.
|
|
|
|
The Snowflake secrets engine uses
|
|
[gosnowflake](https://pkg.go.dev/github.com/snowflakedb/gosnowflake).
|
|
|
|
A properly formatted data source name (DSN) needs to be provided during configuration of the
|
|
database. This DSN is typically formatted with the following options:
|
|
|
|
```text
|
|
{{username}}:{{password}}@account/db_name
|
|
```
|
|
|
|
`{{username}}` and `{{password}}` will typically be used as is during configuration. The
|
|
special formatting is replaced by the username and password options passed to the configuration
|
|
for initial connection.
|
|
|
|
`account` is your Snowflake account identifier. You can find out more about this value by reading
|
|
the `server` section of
|
|
[this document](https://docs.snowflake.com/en/user-guide/odbc-parameters.html#connection-parameters).
|
|
|
|
`db_name` is the name of a database in your snowflake instance.
|
|
|
|
Please note: the user being utilized should have `ACCOUNT_ADMIN` privileges, and should be different
|
|
from the root user you were provided when making your Snowflake account. This allows you to rotate
|
|
the root credentials and still be able to access your account should something go awry.
|
|
|
|
## Capabilities
|
|
|
|
| Plugin Name | Root Credential Rotation | Dynamic Roles | Static Roles | Username Customization |
|
|
| --------------------------- | ------------------------ | ------------- | ------------ | ---------------------- |
|
|
| `snowflake-database-plugin` | Yes | Yes | Yes | Yes (1.8+) |
|
|
|
|
## Setup
|
|
|
|
1. Enable the database secrets engine if it is not already enabled:
|
|
|
|
```text
|
|
$ vault secrets enable database
|
|
Success! Enabled the database secrets engine at: database/
|
|
```
|
|
|
|
By default, the secrets engine will enable at the name of the engine. To
|
|
enable the secrets engine at a different path, use the `-path` argument.
|
|
|
|
1. Configure Vault with the proper plugin and connection information:
|
|
|
|
```text
|
|
$ vault write database/config/my-snowflake-database \
|
|
plugin_name=snowflake-database-plugin \
|
|
allowed_roles="my-role" \
|
|
connection_url="{{username}}:{{password}}@ecxxxx.west-us-1.azure/db_name" \
|
|
username="vaultuser" \
|
|
password="vaultpass"
|
|
```
|
|
|
|
1. Configure a role that maps a name in Vault to an SQL statement to execute to
|
|
create the database credential:
|
|
|
|
```text
|
|
$ vault write database/roles/my-role \
|
|
db_name=my-snowflake-database \
|
|
creation_statements="CREATE USER {{name}} PASSWORD = '{{password}}' DAYS_TO_EXPIRY = {{expiration}} DEFAULT_ROLE=myrole;
|
|
GRANT ROLE myrole TO USER {{name}};" \
|
|
default_ttl="1h" \
|
|
max_ttl="24h"
|
|
Success! Data written to: database/roles/my-role
|
|
```
|
|
|
|
## Usage
|
|
|
|
After the secrets engine is configured and a user/machine has a Vault token with
|
|
the proper permission, it can generate credentials.
|
|
|
|
1. Generate a new credential by reading from the `/creds` endpoint with the name
|
|
of the role:
|
|
|
|
```text
|
|
$ vault read database/creds/my-role
|
|
Key Value
|
|
--- -----
|
|
lease_id database/creds/my-role/2f6a614c-4aa2-7b19-24b9-ad944a8d4de6
|
|
lease_duration 1h
|
|
lease_renewable true
|
|
password SsnoaA-8Tv4t34f41baD
|
|
username v_root_my_role_fU0jqEy4wMNoAY2h60yd_1610561532
|
|
```
|
|
|
|
## API
|
|
|
|
The full list of configurable options can be seen in the [Snowflake database
|
|
plugin API](/api/secret/databases/snowflake) page.
|
|
|
|
For more information on the database secrets engine's HTTP API please see the
|
|
[Database secrets engine API](/api/secret/databases) page.
|