Skip to content
GitLab
Unverified Commit 0d54c1ff authored by Robert's avatar Robert Committed by GitHub
Browse files

docs: consul secret engine improvements, database secrets engine... 

docs: consul secret engine improvements, database secrets engine disable_escaping parameter (#14260)

* Update consul secrets engine docs and api-docs
* Update databases secrets engine docs and api-docs
parent a0268c93
Hide whitespace changes
Inline Side-by-side
Showing
with 197 additions and 78 deletions
+197 -78
website/content/api-docs/secret/consul.mdx
+ 31
- 1
View file @ 0d54c1ff
......@@ -73,6 +73,36 @@ updated attributes.
| :----- | :-------------------- |
| `POST` | `/consul/roles/:name` |
### Parameters for Consul versions 1.7 and above
- `consul_namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the Consul namespace the token
will be generated within. The namespace must exist, and the policies or roles assigned to the
Vault role must also exist inside the given Consul namespace. If not provided, the "default"
namespace is used.
### Parameters for Consul versions 1.11 and above
- `partition` `(string: "")` <EnterpriseAlert inline /> - Specifies the Consul admin partition the token
will be generated within. The partition must exist, and the policies or roles assigned to the
Vault role must also exist inside the given partition. If not provided, the "default"
partition is used.
To create a client token within a particular Consul namespace:
```json
{
"consul_namespace": "ns1"
}
```
To create a client token within a particular Consul admin partition:
```json
{
"partition": "admin1"
}
```
### Parameters for Consul versions 1.4 and above
- `name` `(string: <required>)` – Specifies the name of an existing role against
......@@ -84,7 +114,7 @@ updated attributes.
Defaults to `"client`".
- `policy` `(string: <policy>)` – Specifies the base64-encoded ACL policy. This is
required unless the `token_type` is `"management"`. [Deprecated as of Consul 1.4 and
required unless the `token_type` is `"management"`. [Deprecated as of Consul 1.4 and
removed as of Consul 1.11.](https://www.consul.io/api/acl/legacy)
- `policies` `(list: <policy or policies>)` – The list of policies to assign to the
......
website/content/api-docs/secret/databases/hanadb.mdx
+ 4
- 0
View file @ 0d54c1ff
......@@ -44,6 +44,10 @@ has a number of parameters to further configure a connection.
- `password` `(string: "")` - The root credential password used in the connection URL.
- `disable_escaping` `(boolean: false)` - Turns off the escaping of symbol characters inside of the username
and password fields. See the [databases secrets engine docs](/docs/secrets/databases#disable-character-escaping)
for for information. Defaults to `false`.
### Sample Payload
```json
......
website/content/api-docs/secret/databases/index.mdx
+ 46
- 25
View file @ 0d54c1ff
......@@ -84,6 +84,12 @@ are supported and any additional details about them.
configuration. This is typically used in the `connection_url` field via the templating
directive `{{password}}`.
- `disable_escaping` `(boolean: false)` - Determines whether symbol characters in the
username and password fields will be escaped. Useful for alternate connection string
formats like ADO. More information regarding this parameter can be found on the
[databases secrets engine docs.](/docs/secrets/databases#disable-character-escaping)
Defaults to `false`.
### Sample Payload
```json
......@@ -98,7 +104,7 @@ are supported and any additional details about them.
### Sample cURL Request
```console
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
......@@ -108,7 +114,7 @@ $ curl \
### Sample CLI Request
```console
```shell-session
$ vault write database/config/mysql \
plugin_name="mysql-database-plugin" \
allowed_roles="readonly" \
......@@ -117,6 +123,17 @@ $ vault write database/config/mysql \
password="secretpassword"
```
### Sample CLI Request with ADO-style Connection String
```shell-session
$ vault write database/config/mssql \
plugin_name="mssql-database-plugin" \
connection_url='server=localhost;port=1433;user id={{username}};password={{password}};database=mssql;' \
username="vaultuser" \
password='#secret(password)' \
disable_escaping="true"
```
## Read Connection
This endpoint returns the configuration settings for a connection.
......@@ -132,7 +149,7 @@ This endpoint returns the configuration settings for a connection.
### Sample Request
```console
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
......@@ -165,7 +182,7 @@ are returned, not any values.
### Sample Request
```console
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
......@@ -197,7 +214,7 @@ This endpoint deletes a connection.
### Sample Request
```console
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
......@@ -220,7 +237,7 @@ with the configuration stored in the barrier.
### Sample Request
```console
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
......@@ -247,7 +264,7 @@ recommended that you create a user for Vault to utilize rather than using the ac
### Sample Request
```console
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
......@@ -314,7 +331,7 @@ This endpoint creates or updates a role definition.
### Sample Request
```console
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
......@@ -337,7 +354,7 @@ This endpoint queries the role definition.
### Sample Request
```console
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/database/roles/my-role
......@@ -373,7 +390,7 @@ returned, not any values.
### Sample Request
```console
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
......@@ -409,7 +426,7 @@ This endpoint deletes the role definition.
### Sample Request
```console
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
......@@ -432,7 +449,7 @@ role.
### Sample Request
```console
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/database/creds/my-role
......@@ -488,16 +505,18 @@ this in order to know the password.
```json
{
"db_name": "mysql",
"username": "static-database-user",
"rotation_statements": ["ALTER USER \"{{name}}\" WITH PASSWORD '{{password}}';"],
"rotation_period": "1h"
"db_name": "mysql",
"username": "static-database-user",
"rotation_statements": [
"ALTER USER \"{{name}}\" WITH PASSWORD '{{password}}';"
],
"rotation_period": "1h"
}
```
### Sample Request
```console
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
......@@ -520,7 +539,7 @@ This endpoint queries the static role definition.
### Sample Request
```console
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/database/static-roles/my-static-role
......@@ -532,9 +551,11 @@ $ curl \
{
"data": {
"db_name": "mysql",
"username":"static-user",
"rotation_statements": ["ALTER USER \"{{name}}\" WITH PASSWORD '{{password}}';"],
"rotation_period":"1h"
"username": "static-user",
"rotation_statements": [
"ALTER USER \"{{name}}\" WITH PASSWORD '{{password}}';"
],
"rotation_period": "1h"
}
}
```
......@@ -550,7 +571,7 @@ returned, not any values.
### Sample Request
```console
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
......@@ -584,7 +605,7 @@ must be cleaned up manually.
### Sample Request
```console
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
......@@ -606,7 +627,7 @@ This endpoint returns the current credentials based on the named static role.
### Sample Request
```console
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/database/static-creds/my-static-role
......@@ -644,7 +665,7 @@ change the stored password and reset the TTL of the Static Role's password.
### Sample Request
```console
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
......
website/content/api-docs/secret/databases/mssql.mdx
+ 5
- 1
View file @ 0d54c1ff
......@@ -48,8 +48,12 @@ has a number of parameters to further configure a connection.
dynamic usernames are generated.
- `contained_db` `(bool: false)` - If set, specifies that the connection being configured is to a
[Contained Database](https://docs.microsoft.com/en-us/sql/relational-databases/databases/contained-databases?view=sql-server-ver15), like AzureSQL.
[Contained Database](https://docs.microsoft.com/en-us/sql/relational-databases/databases/contained-databases?view=sql-server-ver15),
like AzureSQL.
- `disable_escaping` `(boolean: false)` - Turns off the escaping of symbol characters inside of the username
and password fields. See the [databases secrets engine docs](/docs/secrets/databases#disable-character-escaping)
for for information. Defaults to `false`.
<details>
<summary><b>Default Username Template</b></summary>
......
website/content/api-docs/secret/databases/mysql-maria.mdx
+ 4
- 0
View file @ 0d54c1ff
......@@ -53,6 +53,10 @@ has a number of parameters to further configure a connection.
- `username_template` `(string)` - [Template](/docs/concepts/username-templating) describing how
dynamic usernames are generated.
- `disable_escaping` `(boolean: false)` - Turns off the escaping of symbol characters inside of the username
and password fields. See the [databases secrets engine docs](/docs/secrets/databases#disable-character-escaping)
for for information. Defaults to `false`.
**Default Username Templates:**
<details>
......
website/content/api-docs/secret/databases/oracle.mdx
+ 4
- 0
View file @ 0d54c1ff
......@@ -44,6 +44,10 @@ has a number of parameters to further configure a connection.
- `username_template` `(string)` - [Template](/docs/concepts/username-templating) describing how
dynamic usernames are generated.
- `disable_escaping` `(boolean: false)` - Turns off the escaping of symbol characters inside of the username
and password fields. See the [databases secrets engine docs](/docs/secrets/databases#disable-character-escaping)
for for information. Defaults to `false`.
<details>
<summary><b>Default Username Template</b></summary>
......
website/content/api-docs/secret/databases/postgresql.mdx
+ 4
- 0
View file @ 0d54c1ff
......@@ -49,6 +49,10 @@ has a number of parameters to further configure a connection.
- `username_template` `(string)` - [Template](/docs/concepts/username-templating) describing how
dynamic usernames are generated.
- `disable_escaping` `(boolean: false)` - Turns off the escaping of symbol characters inside of the username
and password fields. See the [databases secrets engine docs](/docs/secrets/databases#disable-character-escaping)
for for information. Defaults to `false`.
<details>
<summary><b>Default Username Template</b></summary>
......
website/content/api-docs/secret/databases/redshift.mdx
+ 4
- 0
View file @ 0d54c1ff
......@@ -46,6 +46,10 @@ has a number of parameters to further configure a connection.
- `username_template` `(string)` - [Template](/docs/concepts/username-templating) describing how dynamic usernames are generated.
- `disable_escaping` `(boolean: false)` - Turns off the escaping of symbol characters inside of the username
and password fields. See the [databases secrets engine docs](/docs/secrets/databases#disable-character-escaping)
for for information. Defaults to `false`.
### Sample Payload
```json
......
website/content/api-docs/secret/databases/snowflake.mdx
+ 4
- 0
View file @ 0d54c1ff
......@@ -46,6 +46,10 @@ has a number of parameters to further configure a connection.
- `username_template` `(string)` - [Template](/docs/concepts/username-templating) describing how dynamic usernames are generated.
- `disable_escaping` `(boolean: false)` - Turns off the escaping of symbol characters inside of the username
and password fields. See the [databases secrets engine docs](/docs/secrets/databases#disable-character-escaping)
for for information. Defaults to `false`.
### Sample Payload
```json
......
website/content/docs/secrets/consul.mdx
+ 65
- 45
View file @ 0d54c1ff
......@@ -17,7 +17,7 @@ management tool.
1. Enable the Consul secrets engine:
```text
```shell-session
$ vault secrets enable consul
Success! Enabled the consul secrets engine at: consul/
```
......@@ -25,9 +25,11 @@ management tool.
By default, the secrets engine will mount at the name of the engine. To
enable the secrets engine at a different path, use the `-path` argument.
2. In Consul versions below 1.4, acquire a [management token][consul-mgmt-token] from Consul, using the
`acl_master_token` from your Consul configuration file or another management
token:
1. Bootstrap the Consul ACL system if not already done. To begin configuring the secrets engine, we must give Vault
the necessary credentials to manage Consul.
In Consul versions below 1.4, acquire a [management token][consul-mgmt-token] from Consul using the
`acl_master_token` from your Consul configuration file, or another management token:
```shell-session
$ curl \
......@@ -37,7 +39,7 @@ management tool.
https://consul.rocks/v1/acl/create
```
Vault must have a management type token so that it can create and revoke ACL
Vault must have a "management" type token so that it can create and revoke ACL
tokens. The response will return a new token:
```json
......@@ -48,8 +50,8 @@ management tool.
For Consul 1.4 and above, use the command line to generate a token with the appropriate policy:
```text
$ CONSUL_HTTP_TOKEN=d54fe46a-1f57-a589-3583-6b78e334b03b consul acl token create -policy-name=global-management
```shell-session
$ CONSUL_HTTP_TOKEN="<management-token>" consul acl token create -policy-name="global-management"
AccessorID: 865dc5e9-e585-3180-7b49-4ddc0fc45135
SecretID: ef35f0f1-885b-0cab-573c-7c91b65a7a7e
Description:
......@@ -59,44 +61,68 @@ management tool.
00000000-0000-0000-0000-000000000001 - global-management
```
3. Configure Vault to connect and authenticate to Consul:
1. Configure Vault to connect and authenticate to Consul:
```text
```shell-session
$ vault write consul/config/access \
address=127.0.0.1:8500 \
token=7652ba4c-0f6e-8e75-5724-5e083d72cfe4
address="127.0.0.1:8500" \
token="7652ba4c-0f6e-8e75-5724-5e083d72cfe4"
Success! Data written to: consul/config/access
```
4. Configure a role that maps a name in Vault to a Consul ACL policy. Depending on your Consul version,
1. Configure a role that maps a name in Vault to a Consul ACL policy. Depending on your Consul version,
you will either provide a policy document and a token_type, or a set of policies.
When users generate credentials, they are generated against this role.
For Consul versions below 1.4, the policy must be base64-encoded. The policy language is [documented by Consul](https://www.consul.io/docs/security/acl/acl-legacy).
For Consul versions below 1.4, the policy must be base64-encoded. The policy language is
[documented by Consul](https://www.consul.io/docs/security/acl/acl-legacy).
Write a policy and proceed to link it to the role:
```text
$ vault write consul/roles/my-role policy=$(base64 <<< 'key "" { policy = "read" }')
```shell-session
$ vault write consul/roles/my-role policy="$(base64 <<< 'key "" { policy = "read" }')"
Success! Data written to: consul/roles/my-role
```
For Consul versions 1.4 and above, [generate a policy in Consul](https://www.consul.io/docs/guides/acl.html), and proceed to link it to the role:
For Consul versions 1.4 and above, [generate a policy in Consul](https://www.consul.io/docs/guides/acl.html),
and proceed to link it to the role:
```text
$ vault write consul/roles/my-role policies=readonly
```shell-session
$ vault write consul/roles/my-role policies="readonly"
Success! Data written to: consul/roles/my-role
```
For Consul versions 1.5 and above, [generate a role in Consul](https://www.consul.io/api/acl/roles), and proceed to link it to the role:
For Consul versions 1.5 and above, [generate a role in Consul](https://www.consul.io/api/acl/roles), and
proceed to link it to the role:
```text
$ vault write consul/roles/my-role consul_roles=api-server
```shell-session
$ vault write consul/roles/my-role consul_roles="api-server"
Success! Data written to: consul/roles/my-role
```
-> **Token lease duration:** If you do not specify a value for `ttl` (or `lease` for Consul versions below 1.4) the tokens created using Vault's
Consul secrets engine are created with a Time To Live (TTL) of 30 days. You can change the lease duration by passing `-ttl=<duration>` to the
command above with "duration" being a string with a time suffix like "30s" or "1h".
-> **Token lease duration:** If you do not specify a value for `ttl` (or `lease` for Consul versions below 1.4) the
tokens created using Vault's Consul secrets engine are created with a Time To Live (TTL) of 30 days. You can change
the lease duration by passing `-ttl=<duration>` to the command above with "duration" being a string with a time
suffix like "30s" or "1h".
1. For Enterprise users, you may further limit a role's access by adding the optional parameters `consul_namespace` and/or
`partition`. Please refer to Consul's [namespace documentation](https://www.consul.io/docs/enterprise/namespaces) and
[admin partition documentation](https://www.consul.io/docs/enterprise/admin-partitions) for further information about
these features.
For Consul versions 1.7 and above, link a Consul namespace to the role:
```shell-session
$ vault write consul/roles/my-role consul_roles="namespace-management" consul_namespace="ns1"
Success! Data written to: consul/roles/my-role
```
For Consul version 1.11 and above, link an admin partition to a role:
```shell-session
$ vault write consul/roles/my-role consul_roles="admin-management" partition="admin1"
Success! Data written to: consul/roles/my-role
```
## Usage
......@@ -108,28 +134,22 @@ of the role:
```shell-session
$ vault read consul/creds/my-role
Key Value
--- -----
lease_id consul/creds/my-role/b2469121-f55f-53c5-89af-a3ba52b1d6d8
lease_duration 768h
lease_renewable true
token 642783bf-1540-526f-d4de-fe1ac1aed6f0
```
When using Consul 1.4, the response will include the accessor for the token
```shell-session
$ vault read consul/creds/my-role
Key Value
--- -----
lease_id consul/creds/my-role/7miMPnYaBCaVWDS9clNE0Nv3
lease_duration 768h
lease_renewable true
accessor 6d5a0348-dffe-e87b-4266-2bec03800abb
token bc7a42c0-9c59-23b4-8a09-7173c474dc42
Key Value
--- -----
lease_id consul/creds/my-role/b2469121-f55f-53c5-89af-a3ba52b1d6d8
lease_duration 768h
lease_renewable true
accessor c81b9cf7-2c4f-afc7-1449-4e442b831f65
consul_namespace ns1
local false
partition admin1
token 642783bf-1540-526f-d4de-fe1ac1aed6f0
```
!> **Expired token rotation:** Once a token's TTL expires, then Consul operations will no longer be allowed with it. This requires you to have an external process to rotate tokens. At this time, the recommended approach for operators is to rotate the tokens manually by creating a new token using the `vault read consul/creds/my-role` command. Once the token is synchronized with Consul, apply the token to the agents using the Consul API or CLI.
!> **Expired token rotation:** Once a token's TTL expires, then Consul operations will no longer be allowed with it.
This requires you to have an external process to rotate tokens. At this time, the recommended approach for operators
is to rotate the tokens manually by creating a new token using the `vault read consul/creds/my-role` command. Once
the token is synchronized with Consul, apply the token to the agents using the Consul API or CLI.
## Learn
......
website/content/docs/secrets/databases/index.mdx
+ 26
- 6
View file @ 0d54c1ff
......@@ -49,7 +49,7 @@ management tool.
1. Enable the database secrets engine:
```shell
```shell-session
$ vault secrets enable database
Success! Enabled the database secrets engine at: database/
```
......@@ -59,13 +59,13 @@ management tool.
1. Configure Vault with the proper plugin and connection information:
```shell
```shell-session
$ vault write database/config/my-database \
plugin_name="..." \
connection_url="..." \
allowed_roles="..." \
username="..." \
password="..."
password="..." \
```
~> It is highly recommended a user within the database is created
......@@ -85,7 +85,7 @@ management tool.
password such that the vault user is not accessible by any users other than
Vault itself:
```shell
```shell-session
$ vault write -force database/rotate-root/my-database
```
......@@ -97,7 +97,7 @@ management tool.
1. Configure a role that maps a name in Vault to a set of creation statements to
create the database credential:
```shell
```shell-session
$ vault write database/roles/my-role \
db_name=my-database \
creation_statements="..." \
......@@ -117,7 +117,7 @@ the proper permission, it can generate credentials.
1. Generate a new credential by reading from the `/creds` endpoint with the name
of the role:
```shell
```shell-session
$ vault read database/creds/my-role
Key Value
--- -----
......@@ -192,6 +192,26 @@ rule "charset" {
}
```
## Disable Character Escaping
As of Vault 1.10, you can now specify the option `disable_escaping` with a value of `true ` in
some secrets engines to prevent Vault from escaping special characters in the username and password
fields. This is necessary for some alternate connection string formats, such as ADO with MSSQL or Azure
SQL. See the [databases secrets engine API docs](/api-docs/secret/databases#common-fields) and reference
individual plugin documentation to determine support for this parameter.
For example, when the password contains URL-escaped characters like `%` or `#` they will
remain as so instead of becoming `%23` and `%25` respectively.
```shell-session
$ vault write database/config/my-mssql-database \
plugin_name="mssql-database-plugin" \
connection_url='server=localhost;port=1433;user id={{username}};password={{password}};database=mydb;' \
username="root" \
password='your#Strong(!)Password%' \
disable_escaping="true"
```
## Learn
Refer to the following step-by-step tutorials for more information:
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment

免费DevSecOps平台，让您的项目体验完整的DevSecOps流程，让项目更安全