From 2ea8be056754c2b0a71f89334fb7a954bcac8a3a Mon Sep 17 00:00:00 2001 From: Robert <17119716+robmonte@users.noreply.github.com> Date: Fri, 25 Feb 2022 17:43:18 -0600 Subject: [PATCH] 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 --- website/content/api-docs/secret/consul.mdx | 32 ++++- .../api-docs/secret/databases/hanadb.mdx | 4 + .../api-docs/secret/databases/index.mdx | 71 +++++++---- .../api-docs/secret/databases/mssql.mdx | 6 +- .../api-docs/secret/databases/mysql-maria.mdx | 4 + .../api-docs/secret/databases/oracle.mdx | 4 + .../api-docs/secret/databases/postgresql.mdx | 4 + .../api-docs/secret/databases/redshift.mdx | 4 + .../api-docs/secret/databases/snowflake.mdx | 4 + website/content/docs/secrets/consul.mdx | 110 +++++++++++------- .../content/docs/secrets/databases/index.mdx | 32 ++++- 11 files changed, 197 insertions(+), 78 deletions(-) diff --git a/website/content/api-docs/secret/consul.mdx b/website/content/api-docs/secret/consul.mdx index bf33cb0ed..c65509d5e 100644 --- a/website/content/api-docs/secret/consul.mdx +++ b/website/content/api-docs/secret/consul.mdx @@ -73,6 +73,36 @@ updated attributes. | :----- | :-------------------- | | `POST` | `/consul/roles/:name` | +### Parameters for Consul versions 1.7 and above + +- `consul_namespace` `(string: "")` - 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: "")` - 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: )` – Specifies the name of an existing role against @@ -84,7 +114,7 @@ updated attributes. Defaults to `"client`". - `policy` `(string: )` – 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: )` – The list of policies to assign to the diff --git a/website/content/api-docs/secret/databases/hanadb.mdx b/website/content/api-docs/secret/databases/hanadb.mdx index a6fbf5d23..e7a7fce34 100644 --- a/website/content/api-docs/secret/databases/hanadb.mdx +++ b/website/content/api-docs/secret/databases/hanadb.mdx @@ -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 diff --git a/website/content/api-docs/secret/databases/index.mdx b/website/content/api-docs/secret/databases/index.mdx index abcfb1599..bbdf1de87 100644 --- a/website/content/api-docs/secret/databases/index.mdx +++ b/website/content/api-docs/secret/databases/index.mdx @@ -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 \ diff --git a/website/content/api-docs/secret/databases/mssql.mdx b/website/content/api-docs/secret/databases/mssql.mdx index a1182cb2e..b3c3ad983 100644 --- a/website/content/api-docs/secret/databases/mssql.mdx +++ b/website/content/api-docs/secret/databases/mssql.mdx @@ -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`.
Default Username Template diff --git a/website/content/api-docs/secret/databases/mysql-maria.mdx b/website/content/api-docs/secret/databases/mysql-maria.mdx index 92df8f508..02a5ee1ce 100644 --- a/website/content/api-docs/secret/databases/mysql-maria.mdx +++ b/website/content/api-docs/secret/databases/mysql-maria.mdx @@ -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:**
diff --git a/website/content/api-docs/secret/databases/oracle.mdx b/website/content/api-docs/secret/databases/oracle.mdx index 470a6deff..075231ec4 100644 --- a/website/content/api-docs/secret/databases/oracle.mdx +++ b/website/content/api-docs/secret/databases/oracle.mdx @@ -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`. +
Default Username Template diff --git a/website/content/api-docs/secret/databases/postgresql.mdx b/website/content/api-docs/secret/databases/postgresql.mdx index e64e02e79..c6e47fef5 100644 --- a/website/content/api-docs/secret/databases/postgresql.mdx +++ b/website/content/api-docs/secret/databases/postgresql.mdx @@ -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`. +
Default Username Template diff --git a/website/content/api-docs/secret/databases/redshift.mdx b/website/content/api-docs/secret/databases/redshift.mdx index 7fe50e58b..c5591f6fd 100644 --- a/website/content/api-docs/secret/databases/redshift.mdx +++ b/website/content/api-docs/secret/databases/redshift.mdx @@ -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 diff --git a/website/content/api-docs/secret/databases/snowflake.mdx b/website/content/api-docs/secret/databases/snowflake.mdx index 11a2234b7..65d7c1d35 100644 --- a/website/content/api-docs/secret/databases/snowflake.mdx +++ b/website/content/api-docs/secret/databases/snowflake.mdx @@ -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 diff --git a/website/content/docs/secrets/consul.mdx b/website/content/docs/secrets/consul.mdx index 095f59c56..42b406b1e 100644 --- a/website/content/docs/secrets/consul.mdx +++ b/website/content/docs/secrets/consul.mdx @@ -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="" 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=` 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=` 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 +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 ``` -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 -``` - -!> **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 diff --git a/website/content/docs/secrets/databases/index.mdx b/website/content/docs/secrets/databases/index.mdx index 64b23a4d6..eec4c4bee 100644 --- a/website/content/docs/secrets/databases/index.mdx +++ b/website/content/docs/secrets/databases/index.mdx @@ -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: