Merge pull request #176 from influxdata/security-auth

Security and authorization section

content/v2.0/collect-data/use-telegraf/auto-config/_index.md

@@ -59,7 +59,7 @@ Requests to the InfluxDB v2.0 API must include an authentication token.
 A token identifies specific permissions to the InfluxDB instance.
 
 Define the `INFLUX_TOKEN` environment variable using your token.
-_For information about viewing tokens, see [View tokens](/v2.0/users/tokens/view-tokens/)._
+_For information about viewing tokens, see [View tokens](/v2.0/security/tokens/view-tokens/)._
 
 ```sh
 export INFLUX_TOKEN=YourAuthenticationToken

content/v2.0/collect-data/use-telegraf/manual-config.md

@@ -38,7 +38,7 @@ _By default, InfluxDB runs on port `9999`._
 
 ##### token
 Your InfluxDB v2.0 authorization token.
-For information about viewing tokens, see [View tokens](/v2.0/users/tokens/view-tokens/).
+For information about viewing tokens, see [View tokens](/v2.0/security/tokens/view-tokens/).
 
 {{% note %}}
 #### Avoid storing tokens in plain text

content/v2.0/get-started.md

@@ -213,7 +213,7 @@ use one of the following methods to provide your [authentication token](/v2.0/us
 3. Store your token in `~/.influxdbv2/credentials`.
    _The content of the `credentials` file should be only your token._
 
-_See [View tokens](/v2.0/users/tokens/view-tokens/) for information about
+_See [View tokens](/v2.0/security/tokens/view-tokens/) for information about
 retrieving authentication tokens._
 {{% /note %}}
 

content/v2.0/organizations/view-orgs.md

@@ -33,3 +33,25 @@ influx org find
 Filtering options such as filtering by name or ID are available.
 See the [`influx org find` documentation](/v2.0/reference/cli/influx/org/find)
 for information about other available flags.
+
+## View your organization ID
+Use the InfluxDB UI or `influx` CLI to view your organization ID.
+
+### Organization ID in the UI
+After logging in to the InfluxDB UI, your organization ID appears in the URL.
+
+<pre class="highlight">
+http://localhost:9999/orgs/<span class="bp" style="font-weight:bold;margin:0 .15rem">03a2bbf46249a000</span>/...
+</pre>
+
+
+### Organization ID in the CLI
+Use [`influx org find`](#view-organizations-using-the-influx-cli) to view your organization ID.
+
+```sh
+> influx org find
+
+ID                  Name
+03a2bbf46249a000    org-1
+03ace3a859669000    org-2
+```

content/v2.0/reference/cli/influx/_index.md

@@ -38,7 +38,7 @@ with each `influx` command, use one of the following methods to store your token
     _**Note:** If you [set up InfluxDB using the CLI](/v2.0/reference/cli/influx/setup),
     InfluxDB stores your token in the credentials files automatically._
 
-_See [View tokens](/v2.0/users/tokens/view-tokens/) for information about
+_See [View tokens](/v2.0/security/tokens/view-tokens/) for information about
 retrieving authentication tokens._
 {{% /note %}}
 

content/v2.0/security/_index.md

@@ -0,0 +1,18 @@
+---
+title: Manage security and authorization
+description: >
+  Security, access control, and sensitive secret handling are incredibly important
+  when handling any sort of sensitive data.
+  This section provides information about managing the security of your InfluxDB instance.
+weight: 12
+menu:
+  v2_0:
+    name: Security & authorization
+v2.0/tags: [security, authentication]
+---
+
+Security, access control, and sensitive secret handling are incredibly important
+when handling any sort of sensitive data.
+This section provides information about managing the security of your InfluxDB instance.
+
+{{< children >}}

content/v2.0/security/tokens/_index.md

@@ -1,17 +1,19 @@
 ---
-title: Manage tokens
-seotitle: Manage tokens in InfluxDB
+title: Manage authentication tokens
+seotitle: Manage authentication tokens in InfluxDB
 description: Manage authentication tokens in InfluxDB using the InfluxDB UI or the influx CLI.
-v2.0/tags: [tokens, authentication]
+aliases:
+  - /v2.0/users/tokens
+v2.0/tags: [tokens, authentication, security]
 menu:
   v2_0:
     name: Manage tokens
-    parent: Manage users
-weight: 105
+    parent: Security & authorization
+weight: 101
 ---
 
 InfluxDB ensures secure interaction between users and data through the use of **authentication tokens**.
-A token identifies InfluxDB permissions.
+A token belongs to an organization and identifies InfluxDB permissions within the organization.
 
 The following articles provide information about managing authentication tokens.
 

content/v2.0/security/tokens/create-token.md

@@ -2,6 +2,8 @@
 title: Create a token
 seotitle: Create an authentication token in InfluxDB
 description: Create an authentication token in InfluxDB using the InfluxDB UI or the `influx` CLI.
+aliases:
+  - /v2.0/users/tokens/create-token/
 menu:
   v2_0:
     name: Create a token

content/v2.0/security/tokens/delete-token.md

@@ -2,6 +2,8 @@
 title: Delete a token
 seotitle: Delete an authentication token from InfluxDB
 description: Delete an authentication token from InfluxDB using the InfluxDB UI or the `influx` CLI.
+aliases:
+  - /v2.0/users/tokens/delete-token
 menu:
   v2_0:
     name: Delete a token

content/v2.0/security/tokens/update-tokens.md

@@ -1,7 +1,9 @@
 ---
 title: Update a token
 seotitle: Update authentication tokens in InfluxDB
-description: Update authentication tokens' descriptions in InfluxDB using the InfluxDB UI.
+description: Update authentication tokens' descriptions in InfluxDB using the InfluxDB UI
+aliases:
+  - /v2.0/users/tokens/update-tokens
 menu:
   v2_0:
     name: Update a token

content/v2.0/security/tokens/view-tokens.md

@@ -2,6 +2,8 @@
 title: View tokens
 seotitle: View authentication tokens in InfluxDB
 description: View authentication tokens in InfluxDB using the InfluxDB UI or the `influx` CLI.
+aliases:
+  - /v2.0/users/tokens/view-tokens
 menu:
   v2_0:
     name: View tokens

content/v2.0/security/use-vault.md

@@ -0,0 +1,129 @@
+---
+title: Store secrets in Vault
+description: Manage authentication tokens in InfluxDB using the InfluxDB UI or the influx CLI.
+v2.0/tags: [tokens, security]
+menu:
+  v2_0:
+    parent: Security & authorization
+weight: 102
+---
+
+[Vault](https://www.vaultproject.io/) secures, stores, and tightly controls access
+to tokens, passwords, certificates, and other sensitive secrets.
+Store sensitive secrets in Vault using the InfluxDB built-in Vault integration.
+
+{{% note %}}
+When not using Vault, secrets are Base64-encoded and stored in the InfluxDB embedded key value store,
+[BoltDB](https://github.com/boltdb/bolt).
+{{% /note %}}
+
+## Start a Vault server
+Start a Vault server and ensure InfluxDB has network access to the server.
+The following links provide information about running Vault in both development and production:
+
+- [Install Vault](https://learn.hashicorp.com/vault/getting-started/install)
+- [Start a Vault dev server](https://learn.hashicorp.com/vault/getting-started/dev-server)
+- [Deploy Vault](https://learn.hashicorp.com/vault/getting-started/deploy)
+
+For this example, install Vault on your local machine and start a Vault dev server.
+
+```sh
+vault server -dev
+```
+
+## Define Vault environment variables
+Use [Vault environment variables](https://www.vaultproject.io/docs/commands/index.html#environment-variables)
+to provide connection credentials and other important Vault-related information to InfluxDB.
+
+#### Required environment variables
+- `VAULT_ADDR`: The API address of your Vault server _(provided in the Vault server output)_.
+- `VAULT_TOKEN`: The [Vault token](https://learn.hashicorp.com/vault/getting-started/authentication)
+  required to access your Vault server.
+
+_Your Vault server configuration may require other environment variables._
+
+```sh
+export VAULT_ADDR='http://127.0.0.1:8200' VAULT_TOKEN='s.0X0XxXXx0xXxXXxxxXxXxX0x'
+```
+
+## Start InfluxDB
+Start the [`influxd` service](/v2.0/reference/cli/influxd/) with the `--secret-store`
+option set to `vault`.
+
+```bash
+influxd --secret-store vault
+```
+
+## Test Vault storage
+With Vault and InfluxDB servers running, use the InfluxDB API to test Vault:
+
+{{% note %}}
+Replace `<org-id>` with your [organization ID](/v2.0/organizations/view-orgs/#view-your-organization-id)
+and `YOURAUTHTOKEN` with your [InfluxDB authentication token](/v2.0/security/tokens/).
+{{% /note %}}
+
+##### Retrieve an organization's secrets
+```sh
+curl --request GET \
+  --url http://localhost:9999/api/v2/orgs/<org-id>/secrets \
+  --header 'authorization: Token YOURAUTHTOKEN'
+
+# should return
+#  {
+#    "links": {
+#      "org": "/api/v2/orgs/031c8cbefe101000",
+#      "secrets": "/api/v2/orgs/031c8cbefe101000/secrets"
+#    },
+#    "secrets": []
+#  }
+```
+
+##### Add secrets to an organization
+```sh
+curl --request PATCH \
+  --url http://localhost:9999/api/v2/orgs/<org-id>/secrets \
+  --header 'authorization: Token YOURAUTHTOKEN' \
+  --header 'content-type: application/json' \
+  --data '{
+	"foo": "bar",
+	"hello": "world"
+}'
+
+# should return 204 no content
+```
+
+##### Retrieve the added secrets
+```bash
+curl --request GET \
+  --url http://localhost:9999/api/v2/orgs/<org-id>/secrets \
+  --header 'authorization: Token YOURAUTHTOKEN'
+
+# should return
+#  {
+#    "links": {
+#      "org": "/api/v2/orgs/031c8cbefe101000",
+#      "secrets": "/api/v2/orgs/031c8cbefe101000/secrets"
+#    },
+#    "secrets": [
+#      "foo",
+#      "hello"
+#    ]
+#  }
+```
+
+## Vault secrets storage
+For each organization, InfluxDB creates a [secrets engine](https://learn.hashicorp.com/vault/getting-started/secrets-engines)
+using the following pattern:
+
+```
+/secret/data/<org-id>
+```
+
+Secrets are stored in Vault as key value pairs in their respective secrets engines.
+
+```
+/secret/data/031c8cbefe101000 ->
+  this_key: foo
+  that_key: bar
+  a_secret: key
+```

content/v2.0/users/_index.md

@@ -6,12 +6,12 @@ v2.0/tags: [users, authentication]
 menu:
   v2_0:
     name: Manage users
-weight: 12
+weight: 11
 ---
 
 Users are those with access to InfluxDB.
-In order to access any data, a user must be added as a member of an organization.
-All users have unique authentication tokens with specific permissions used to grant them access to data within InfluxDB.
+To grant a user permission to access data, add them as a [member of an organization](/v2.0/organizations/members/)
+and provide them with an [authentication token](/v2.0/security/tokens/).
 
 The following articles walk through managing users.