diff --git a/website/content/api-docs/secret/databases/redis.mdx b/website/content/api-docs/secret/databases/redis.mdx new file mode 100644 index 000000000..b059c80f1 --- /dev/null +++ b/website/content/api-docs/secret/databases/redis.mdx @@ -0,0 +1,76 @@ +--- +layout: api +page_title: Redis - Database - Secrets Engines - HTTP API +description: >- + The Redis plugin for Vault's database secrets engine generates [ACL credentials](https://redis.io/docs/manual/security/acl/) + to access Redis servers. +--- + +# Redis Database Plugin HTTP API + +The Redis database plugin is one of the supported plugins for the database +secrets engine. This plugin generates database credentials dynamically based on +configured roles for the Redis database. + +## Configure Connection + +In addition to the parameters defined by the [Database +Secrets Engine](/api-docs/secret/databases#configure-connection), this plugin +has a number of parameters to further configure a connection. + +| Method | Path | +| :----- | :----------------------- | +| `POST` | `/database/config/:name` | + +### Parameters + +- `host` `(string: )` – Specifies the host to connect to. + +- `port` `(int: )` – Specifies the port number of the connection. + +- `username` `(string: )` – Specifies the username for Vault to use. + +- `password` `(string: )` – Specifies the password corresponding to the given username. + +- `tls` `(bool: false)` – Specifies whether to use TLS when connecting to Redis. + +- `insecure_tls` `(bool: false)` – Specifies whether to skip verification of the +server certificate when using TLS. + +### Sample Payload + +```json +{ + "plugin_name": "redis-database-plugin", + "host": "localhost://127.0.0.1", + "username": "user", + "password": "pass", + "allowed-roles": "my-*-role" +} +``` + +### Sample Request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/database/config/redis +``` + +## Statements + +Statements are configured during role creation and are used by the plugin to +determine what is sent to the database on user creation, renewing, and +revocation. For more information on configuring roles see the [Role +API](/api/secret/databases#create-role) in the database secrets engine docs. + +### Parameters + +The following are the statements used by this plugin. If not mentioned in this +list the plugin does not support that statement type. + +- `creation_statements` `(list: [])` – Specifies a JSON string containing +[Redis ACL rules](https://redis.io/commands/acl-cat) to assign to created users. If not provided, defaults to +a read-only user that can read any key. diff --git a/website/content/docs/plugins/plugin-portal.mdx b/website/content/docs/plugins/plugin-portal.mdx index 873f8bd7e..ac1e13b28 100644 --- a/website/content/docs/plugins/plugin-portal.mdx +++ b/website/content/docs/plugins/plugin-portal.mdx @@ -62,6 +62,7 @@ exists within the Vault repository, the plugin can be built as instructed in - [MySQL/MariaDB](/api-docs/secret/databases/mysql-maria) - [Oracle Database](https://github.com/hashicorp/vault-plugin-database-oracle) - [PostgreSQL](/api-docs/secret/databases/postgresql) +- [Redis](/api-docs/secret/databases/redis) - [Redis ElastiCache](/api-docs/secret/databases/rediselasticache) - [Redshift](/api-docs/secret/databases/redshift) - [Snowflake](https://github.com/hashicorp/vault-plugin-database-snowflake) diff --git a/website/content/docs/secrets/databases/index.mdx b/website/content/docs/secrets/databases/index.mdx index 5905e7009..b7556069a 100644 --- a/website/content/docs/secrets/databases/index.mdx +++ b/website/content/docs/secrets/databases/index.mdx @@ -146,6 +146,7 @@ and private key pair to authenticate. | [MySQL/MariaDB](/docs/secrets/databases/mysql-maria) | Yes | Yes | Yes | Yes (1.7+) | password | | [Oracle](/docs/secrets/databases/oracle) | Yes | Yes | Yes | Yes (1.7+) | password | | [PostgreSQL](/docs/secrets/databases/postgresql) | Yes | Yes | Yes | Yes (1.7+) | password | +| [Redis](/docs/secrets/databases/redis) | Yes | Yes | Yes | No | password | | [Redis ElastiCache](/docs/secrets/databases/rediselasticache) | No | No | Yes | No | password | | [Redshift](/docs/secrets/databases/redshift) | Yes | Yes | Yes | Yes (1.8+) | password | | [Snowflake](/docs/secrets/databases/snowflake) | Yes | Yes | Yes | Yes (1.8+) | password, rsa_private_key | diff --git a/website/content/docs/secrets/databases/redis.mdx b/website/content/docs/secrets/databases/redis.mdx new file mode 100644 index 000000000..ebf358c5f --- /dev/null +++ b/website/content/docs/secrets/databases/redis.mdx @@ -0,0 +1,126 @@ +--- +layout: docs +page_title: Redis - Database - Secrets Engines +description: |- + Redis is one of the supported plugins for the database secrets engine. + This plugin generates database credentials dynamically based on configured + roles for the Redis database, and also supports [Static Roles](https://developer.hashicorp.com/vault/docs/secrets/databases#static-roles). +--- + +# Redis Database Secrets Engine + +Redis is one of the supported plugins for the database secrets engine. This +plugin generates database credentials dynamically based on configured roles for +the Redis database. + +See the [database secrets engine](/docs/secrets/databases) docs for +more information about setting up the database secrets engine. + +## Capabilities + +| Plugin Name | Root Credential Rotation | Dynamic Roles | Static Roles | Username Customization | +| --------------------------- | ------------------------ | ------------- | ------------ | ---------------------- | +| `redis-database-plugin` | Yes | Yes | Yes | No | + +## Setup + +1. Enable the database secrets engine if it is not already enabled: + + ```shell-session + $ 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 configuration: + + ```shell-session + $ vault write database/config/my-redis-database \ + plugin_name="redis-database-plugin" \ + host="localhost" \ + port=6379 \ + tls=true \ + ca_cert="$CACERT" + username="user" \ + password="pass" \ + allowed_roles="my-*-role" + ``` + +1. You should consider rotating the admin password. Note that if you do, the + new password will never be made available through Vault, so you should + create a Vault-specific database admin user for this. + + ```shell-session + vault write -force database/rotate-root/my-redis-database + ``` + +## Usage + +After the secrets engine is configured, write dynamic and static roles +to Vault to enable generating credentials. + +### Dynamic roles + +1. Configure a dynamic role that maps a name in Vault to a JSON string + containing the Redis ACL rules, which are either documented [here](https://redis.io/commands/acl-cat) or in the output + of the `ACL CAT` Redis command. + + ```shell-session + $ vault write database/roles/my-dynamic-role \ + db_name="my-redis-database" \ + creation_statements='["+@admin"]' \ + default_ttl="5m" \ + max_ttl="1h" + Success! Data written to: database/roles/my-dynamic-role + ``` + + Note that if a creation_statement is not provided the user account will + default to a read only user, `'["~*", "+@read"]'` that can read any key. + +1. Generate a new set of credentials by reading from the `/creds` endpoint with the name + of the role: + + ```shell-session + $ vault read database/creds/my-dynamic-role + Key Value + --- ----- + lease_id database/creds/my-dynamic-role/OxCTXJcxQ2F4lReWPjbezSnA + lease_duration 5m + lease_renewable true + password dACqHsav6-attdv1glGZ + username V_TOKEN_MY-DYNAMIC-ROLE_YASUQUF3GVVD0ZWTEMK4_1608481717 + ``` + +### Static roles + +1. Configure a static role that maps a name in Vault to an existing Redis + user. + + ```shell-session + $ vault write database/static-roles/my-static-role \ + db_name="my-redis-database" \ + username="my-existing-redis-user" \ + rotation_period=5m + Success! Data written to: database/static-roles/my-static-role + ``` + +1. Retrieve the credentials from the `/static-creds` endpoint: + + ```shell-session + $ vault read database/static-creds/my-static-role + Key Value + --- ----- + last_vault_rotation 2020-12-20T10:39:49.647822-06:00 + password ylKNgqa3NPVAioBf-0S5 + rotation_period 5m + ttl 4m39s + username my-existing-redis-user + ``` + +## API + +The full list of configurable options can be seen in the [Redis Database Plugin API](/api-docs/secret/databases/redis) page. + +For more information on the database secrets engine's HTTP API please see the [Database Secrets Engine API](/api-docs/secret/databases) page. diff --git a/website/data/api-docs-nav-data.json b/website/data/api-docs-nav-data.json index c26ee1f94..fe79196ee 100644 --- a/website/data/api-docs-nav-data.json +++ b/website/data/api-docs-nav-data.json @@ -97,6 +97,10 @@ "title": "PostgreSQL", "path": "secret/databases/postgresql" }, + { + "title": "Redis", + "path": "secret/databases/redis" + }, { "title": "Redis ElastiCache", "path": "secret/databases/rediselasticache" diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index f1677bf6b..c9109a20c 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -1011,6 +1011,10 @@ "title": "PostgreSQL", "path": "secrets/databases/postgresql" }, + { + "title": "Redis", + "path": "secrets/databases/redis" + }, { "title": "Redis ElastiCache", "path": "secrets/databases/rediselasticache"