From d2b57ecf522a9043e197bc3e80c4b0f1e2313842 Mon Sep 17 00:00:00 2001 From: pierwill <19642016+pierwill@users.noreply.github.com> Date: Fri, 3 Sep 2021 10:49:47 -0500 Subject: [PATCH] Enterprise authentication/authorization improvements (#2972) Edit InfluxDB Enterprise authentication and authorization docs. Re-organize management docs. Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> --- .../v1.8/administration/ldap.md | 4 +- .../authentication_and_authorization.md | 500 ------------ .../v1.9/administration/backup-and-restore.md | 6 +- .../v1.9/administration/configure/_index.md | 11 + .../{ => configure}/anti-entropy/_index.md | 3 +- .../anti-entropy/anti-entropy-api.md | 0 .../{ => configure}/config-data-nodes.md | 4 +- .../{ => configure}/config-meta-nodes.md | 4 +- .../{ => configure}/configuration.md | 3 +- .../administration/{ => configure}/ports.md | 4 +- .../v1.9/administration/manage/_index.md | 11 + .../{ => manage}/cluster-commands.md | 5 +- .../administration/{ => manage}/renaming.md | 5 +- .../security/_index.md} | 19 +- .../authentication_and_authorization-api.md | 742 ++++++++++++++++++ .../authentication_and_authorization.md | 541 +++++++++++++ .../security}/configure-password-hashing.md | 4 +- .../{ => manage/security}/ldap.md | 9 +- .../{ => manage}/subscription-management.md | 4 +- .../v1.9/administration/monitor/_index.md | 11 + .../v1.9/administration/{ => monitor}/logs.md | 4 +- .../{ => monitor}/server_monitoring.md | 3 +- .../v1.9/concepts/glossary.md | 12 +- .../v1.9/features/users.md | 234 ++---- .../v1.9/guides/fine-grained-authorization.md | 3 + 25 files changed, 1470 insertions(+), 676 deletions(-) delete mode 100644 content/enterprise_influxdb/v1.9/administration/authentication_and_authorization.md create mode 100644 content/enterprise_influxdb/v1.9/administration/configure/_index.md rename content/enterprise_influxdb/v1.9/administration/{ => configure}/anti-entropy/_index.md (99%) rename content/enterprise_influxdb/v1.9/administration/{ => configure}/anti-entropy/anti-entropy-api.md (100%) rename content/enterprise_influxdb/v1.9/administration/{ => configure}/config-data-nodes.md (99%) rename content/enterprise_influxdb/v1.9/administration/{ => configure}/config-meta-nodes.md (99%) rename content/enterprise_influxdb/v1.9/administration/{ => configure}/configuration.md (98%) rename content/enterprise_influxdb/v1.9/administration/{ => configure}/ports.md (97%) create mode 100644 content/enterprise_influxdb/v1.9/administration/manage/_index.md rename content/enterprise_influxdb/v1.9/administration/{ => manage}/cluster-commands.md (94%) rename content/enterprise_influxdb/v1.9/administration/{ => manage}/renaming.md (96%) rename content/enterprise_influxdb/v1.9/administration/{security.md => manage/security/_index.md} (84%) create mode 100644 content/enterprise_influxdb/v1.9/administration/manage/security/authentication_and_authorization-api.md create mode 100644 content/enterprise_influxdb/v1.9/administration/manage/security/authentication_and_authorization.md rename content/enterprise_influxdb/v1.9/administration/{ => manage/security}/configure-password-hashing.md (96%) rename content/enterprise_influxdb/v1.9/administration/{ => manage/security}/ldap.md (96%) rename content/enterprise_influxdb/v1.9/administration/{ => manage}/subscription-management.md (98%) create mode 100644 content/enterprise_influxdb/v1.9/administration/monitor/_index.md rename content/enterprise_influxdb/v1.9/administration/{ => monitor}/logs.md (98%) rename content/enterprise_influxdb/v1.9/administration/{ => monitor}/server_monitoring.md (98%) diff --git a/content/enterprise_influxdb/v1.8/administration/ldap.md b/content/enterprise_influxdb/v1.8/administration/ldap.md index 10481e9f0..42c5bbae4 100644 --- a/content/enterprise_influxdb/v1.8/administration/ldap.md +++ b/content/enterprise_influxdb/v1.8/administration/ldap.md @@ -39,7 +39,9 @@ Update the following settings in each data node configuration file (`/etc/influx 3. If you're enabling authentication on meta nodes, you must also include the following configurations: - `INFLUXDB_META_META_AUTH_ENABLED` environment variable, or `[http]` configuration setting `meta-auth-enabled`, is set to `true`. This value must be the same value as the meta node's `meta.auth-enabled` configuration. - - `INFLUXDB_META_META_INTERNAL_SHARED_SECRET`, or the corresponding `[meta]` configuration setting `meta-internal-shared-secret`, is set to `true`. + - `INFLUXDB_META_META_INTERNAL_SHARED_SECRET`, + or the corresponding `[meta]` configuration setting `meta-internal-shared-secret`, + is set to a secret value. This value must be the same value as the meta node's `meta.internal-shared-secret`. ### Configure meta nodes diff --git a/content/enterprise_influxdb/v1.9/administration/authentication_and_authorization.md b/content/enterprise_influxdb/v1.9/administration/authentication_and_authorization.md deleted file mode 100644 index 9d558521c..000000000 --- a/content/enterprise_influxdb/v1.9/administration/authentication_and_authorization.md +++ /dev/null @@ -1,500 +0,0 @@ ---- -title: Authentication and authorization in InfluxDB Enterprise -description: > - Set up and manage authentication and authorization in InfluxDB Enterprise. -menu: - enterprise_influxdb_1_9: - name: Manage authentication and authorization - weight: 30 - parent: Administration ---- - -This document covers setting up and managing authentication and authorization in InfluxDB Enterprise. - -- [Authentication](#authentication) - - [Set up Authentication](#set-up-authentication) - - [Authenticate Requests](#authenticate-requests) -- [Authorization](#authorization) - - [User Types and Privileges](#user-types-and-privileges) - - [User Management Commands](#user-management-commands) -- [HTTP Errors](#authentication-and-authorization-http-errors) - -{{% note %}} -Authentication and authorization should not be relied upon to prevent access and protect data from malicious actors. -If additional security or compliance features are desired, InfluxDB Enterprise should be run behind a third-party service. -If InfluxDB Enterprise is being deployed on a publicly accessible endpoint, we strongly recommend authentication be enabled. Otherwise the data will be -publicly available to any unauthenticated user. -{{% /note %}} - -## Authentication - -The InfluxDB API and the [`influx` CLI](/enterprise_influxdb/v1.9/tools/influx-cli/), -which connects to the database using the API, -include built-in authentication based on user credentials. -When you enable authentication, InfluxDB Enterprise only executes HTTP requests that are sent with valid credentials. - -{{% note %}} -Authentication only occurs at the HTTP request scope. -Plugins do not currently have the ability to authenticate requests and service -endpoints (for example, Graphite, collectd, etc.) are not authenticated. -{{% /note %}} - -### Set up authentication - -1. **Create at least one [admin user](#admin-users)**. - See the [authorization section](#authorization) for how to create an admin user. - - {{% note %}} -If you enable authentication and have no users, InfluxDB Enterprise will **not** enforce authentication -and will only accept the [query](#user-management-commands) that creates a new admin user. - {{% /note %}} - - InfluxDB Enterprise will enforce authentication once there is an admin user. - -2. **Enable authentication in your configuration file** - by setting the `auth-enabled` option to `true` in the `[http]` section: - - ```toml - [http] - enabled = true - bind-address = ":8086" - auth-enabled = true # Set to true - log-enabled = true - write-tracing = false - pprof-enabled = true - pprof-auth-enabled = true - debug-pprof-enabled = false - ping-auth-enabled = true - https-enabled = true - https-certificate = "/etc/ssl/influxdb.pem" - ``` - - {{% note %}} -If `pprof-enabled` is set to `true`, set `pprof-auth-enabled` and `ping-auth-enabled` -to `true` to require authentication on profiling and ping endpoints. - {{% /note %}} - -3. **Restart InfluxDB Enterprise**. - Once restarted, InfluxDB Enterprise checks user credentials on every request and only - processes requests that have valid credentials for an existing user. - -### Authenticate requests - -#### Authenticate with the InfluxDB API - -There are two options for authenticating with the [InfluxDB API](/enterprise_influxdb/v1.9/tools/api/). - -If you authenticate with both Basic Authentication **and** the URL query parameters, -the user credentials specified in the query parameters take precedence. -The queries in the following examples assume that the user is an [admin user](#admin-users). -See the section on [authorization](#authorization) for the different user types, their privileges, and more on user management. - -> **Note:** InfluxDB Enterprise redacts passwords when you enable authentication. - -##### Authenticate with Basic Authentication -```bash -curl -G http://localhost:8086/query \ - -u todd:influxdb4ever \ - --data-urlencode "q=SHOW DATABASES" -``` - -##### Authenticate with query parameters in the URL or request body -Set `u` as the username and `p` as the password. - -###### Credentials as query parameters -```bash -curl -G "http://localhost:8086/query?u=todd&p=influxdb4ever" \ - --data-urlencode "q=SHOW DATABASES" -``` - -###### Credentials in the request body -```bash -curl -G http://localhost:8086/query \ - --data-urlencode "u=todd" \ - --data-urlencode "p=influxdb4ever" \ - --data-urlencode "q=SHOW DATABASES" -``` - -#### Authenticate with the CLI - -There are three options for authenticating with the [CLI](/influxdb/v1.8/tools/shell/). - -##### Authenticate with environment variables -Use the `INFLUX_USERNAME` and `INFLUX_PASSWORD` environment variables to provide -authentication credentials to the `influx` CLI. - -```bash -export INFLUX_USERNAME=todd -export INFLUX_PASSWORD=influxdb4ever -echo $INFLUX_USERNAME $INFLUX_PASSWORD -todd influxdb4ever - -influx -Connected to http://localhost:8086 version {{< latest-patch >}} -InfluxDB shell {{< latest-patch >}} -``` - -##### Authenticate with CLI flags -Use the `-username` and `-password` flags to provide authentication credentials -to the `influx` CLI. - -```bash -influx -username todd -password influxdb4ever -Connected to http://localhost:8086 version {{< latest-patch >}} -InfluxDB shell {{< latest-patch >}} -``` - -##### Authenticate with credentials in the influx shell -Start the `influx` shell and run the `auth` command. -Enter your username and password when prompted. - -```bash -> influx -Connected to http://localhost:8086 version {{< latest-patch >}} -InfluxDB shell {{< latest-patch >}} -> auth -username: todd -password: -> -``` - -#### Authenticate using JWT tokens -For a more secure alternative to using passwords, include JWT tokens with requests to the InfluxDB API. -This is currently only possible through the [InfluxDB HTTP API](/influxdb/v1.8/tools/api/). - -1. [Add a shared secret in your InfluxDB configuration file](#add-a-shared-secret-in-your-influxdb-configuration-file) -2. [Generate your JWT token](#generate-your-jwt-token) -3. [Include the token in HTTP requests](#include-the-token-in-http-requests) - -##### Add a shared secret in your InfluxDB Enterprise configuration file -InfluxDB Enterprise uses the shared secret to encode the JWT signature. -By default, `shared-secret` is set to an empty string, in which case no JWT authentication takes place. -Add a custom shared secret in your [InfluxDB configuration file](/influxdb/v1.8/administration/config/#shared-secret). -The longer the secret string, the more secure it is: - -```toml -[http] - shared-secret = "my super secret pass phrase" -``` - -Alternatively, to avoid keeping your secret phrase as plain text in your InfluxDB configuration file, set the value with the `INFLUXDB_HTTP_SHARED_SECRET` environment variable. - - -##### Generate your JWT token -Use an authentication service to generate a secure token using your InfluxDB username, an expiration time, and your shared secret. -There are online tools, such as [https://jwt.io/](https://jwt.io/), that will do this for you. - -The payload (or claims) of the token must be in the following format: - -```json -{ - "username": "myUserName", - "exp": 1516239022 -} -``` - -- **username** - The name of your InfluxDB user. -- **exp** - The expiration time of the token in UNIX epoch time. - For increased security, keep token expiration periods short. - For testing, you can manually generate UNIX timestamps using [https://www.unixtimestamp.com/index.php](https://www.unixtimestamp.com/index.php). - -Encode the payload using your shared secret. -You can do this with either a JWT library in your own authentication server or by hand at [https://jwt.io/](https://jwt.io/). - -The generated token follows this format: `
..` - -##### Include the token in HTTP requests -Include your generated token as part of the ``Authorization`` header in HTTP requests. -Use the ``Bearer`` authorization scheme: - -``` -Authorization: Bearer -``` -{{% note %}} -Only unexpired tokens will successfully authenticate. -Be sure your token has not expired. -{{% /note %}} - -###### Example query request with JWT authentication -```bash -curl -G "http://localhost:8086/query?db=demodb" \ - --data-urlencode "q=SHOW DATABASES" \ - --header "Authorization: Bearer
.." -``` - -## Authenticate Telegraf requests to InfluxDB - -Authenticating [Telegraf](/{{< latest "telegraf" >}}/) requests to an InfluxDB instance with -authentication enabled requires some additional steps. -In the Telegraf configuration file (`/etc/telegraf/telegraf.conf`), uncomment -and edit the `username` and `password` settings. - -```toml -############################################################################### -# OUTPUT PLUGINS # -############################################################################### - -# ... - -[[outputs.influxdb]] - # ... - username = "example-username" # Provide your username - password = "example-password" # Provide your password - -# ... -``` - -Restart Telegraf and you're all set! - -## Authorization - -Authorization is only enforced once you've [enabled authentication](#set-up-authentication). -By default, authentication is disabled, all credentials are silently ignored, and all users have all privileges. - -### User types and privileges - -#### Admin users -Admin users have `READ` and `WRITE` access to all databases and full access to the following administrative queries: - -##### Database management -- `CREATE DATABASE` -- `DROP DATABASE` -- `DROP SERIES` -- `DROP MEASUREMENT` -- `CREATE RETENTION POLICY` -- `ALTER RETENTION POLICY` -- `DROP RETENTION POLICY` -- `CREATE CONTINUOUS QUERY` -- `DROP CONTINUOUS QUERY` - -For more information about these commands, see [Database management](/influxdb/v1.8/query_language/manage-database/) and -[Continuous queries](/influxdb/v1.8/query_language/continuous_queries/). - -##### User management -- Admin user management - - [`CREATE USER`](#user-management-commands) - - [`GRANT ALL PRIVILEGES`](#grant-administrative-privileges-to-an-existing-user) - - [`REVOKE ALL PRIVILEGES`](#revoke-administrative-privileges-from-an-admin-user) - - [`SHOW USERS`](#show-all-existing-users-and-their-admin-status) -- Non-admin user management: - - [`CREATE USER`](#user-management-commands) - - [`GRANT [READ,WRITE,ALL]`](#grant-read-write-or-all-database-privileges-to-an-existing-user) - - [`REVOKE [READ,WRITE,ALL]`](#revoke-read-write-or-all-database-privileges-from-an-existing-user) -- General user management: - - [`SET PASSWORD`](#reset-a-users-password) - - [`DROP USER`](#drop-a-user) - -See [below](#user-management-commands) for a complete discussion of the user management commands. - -#### Non-admin users -Non-admin users can have one of the following three privileges per database: - -- `READ` -- `WRITE` -- `ALL` (both `READ` and `WRITE` access) - -`READ`, `WRITE`, and `ALL` privileges are controlled per user per database. A new non-admin user has no access to any database until they are specifically [granted privileges to a database](#grant-read-write-or-all-database-privileges-to-an-existing-user) by an admin user. -Non-admin users can [`SHOW`](/influxdb/v1.8/query_language/explore-schema/#show-databases) the databases on which they have `READ` and/or `WRITE` permissions. - -### User management commands - -#### Admin user management - -When you enable HTTP authentication, InfluxDB requires you to create at least one admin user before you can interact with the system. - -```sql -CREATE USER admin WITH PASSWORD '' WITH ALL PRIVILEGES -``` - -##### Create another admin user - -```sql -CREATE USER WITH PASSWORD '' WITH ALL PRIVILEGES -``` - -{{% note %}} -Repeating the exact `CREATE USER` statement is idempotent. -If any values change the database will return a duplicate user error. - -```sql -> CREATE USER todd WITH PASSWORD '123456' WITH ALL PRIVILEGES -> CREATE USER todd WITH PASSWORD '123456' WITH ALL PRIVILEGES -> CREATE USER todd WITH PASSWORD '123' WITH ALL PRIVILEGES -ERR: user already exists -> CREATE USER todd WITH PASSWORD '123456' -ERR: user already exists -> CREATE USER todd WITH PASSWORD '123456' WITH ALL PRIVILEGES -> -``` -{{% /note %}} - -##### `GRANT` administrative privileges to an existing user -```sql -GRANT ALL PRIVILEGES TO -``` - -##### `REVOKE` administrative privileges from an admin user -```sql -REVOKE ALL PRIVILEGES FROM -``` - -##### `SHOW` all existing users and their admin status -```sql -SHOW USERS -``` - -###### CLI Example -```sql -> SHOW USERS -user admin -todd false -paul true -hermione false -dobby false -``` - -#### Non-admin user management - -##### `CREATE` a new non-admin user -```sql -CREATE USER WITH PASSWORD '' -``` - -###### CLI example -```js -> CREATE USER todd WITH PASSWORD 'influxdb41yf3' -> CREATE USER alice WITH PASSWORD 'wonder\'land' -> CREATE USER "rachel_smith" WITH PASSWORD 'asdf1234!' -> CREATE USER "monitoring-robot" WITH PASSWORD 'XXXXX' -> CREATE USER "$savyadmin" WITH PASSWORD 'm3tr1cL0v3r' -> -``` - -{{% note %}} -##### Important notes about providing user credentials -- The user value must be wrapped in double quotes if it starts with a digit, is an InfluxQL keyword, contains a hyphen and or includes any special characters, for example: `!@#$%^&*()-` -- The password [string](/influxdb/v1.8/query_language/spec/#strings) must be wrapped in single quotes. - Do not include the single quotes when authenticating requests. - We recommend avoiding the single quote (`'`) and backslash (`\`) characters in passwords. - For passwords that include these characters, escape the special character with a backslash (e.g. (`\'`) when creating the password and when submitting authentication requests. -- Repeating the exact `CREATE USER` statement is idempotent. If any values change the database will return a duplicate user error. See GitHub Issue [#6890](https://github.com/influxdata/influxdb/pull/6890) for details. - -###### CLI example -```sql -> CREATE USER "todd" WITH PASSWORD '123456' -> CREATE USER "todd" WITH PASSWORD '123456' -> CREATE USER "todd" WITH PASSWORD '123' -ERR: user already exists -> CREATE USER "todd" WITH PASSWORD '123456' -> CREATE USER "todd" WITH PASSWORD '123456' WITH ALL PRIVILEGES -ERR: user already exists -> CREATE USER "todd" WITH PASSWORD '123456' -> -``` -{{% /note %}} - - -##### `GRANT` `READ`, `WRITE` or `ALL` database privileges to an existing user - -```sql -GRANT [READ,WRITE,ALL] ON TO -``` - -CLI examples: - -`GRANT` `READ` access to `todd` on the `NOAA_water_database` database: - -```sql -> GRANT READ ON "NOAA_water_database" TO "todd" -> -``` - -`GRANT` `ALL` access to `todd` on the `NOAA_water_database` database: - -```sql -> GRANT ALL ON "NOAA_water_database" TO "todd" -> -``` - -##### `REVOKE` `READ`, `WRITE`, or `ALL` database privileges from an existing user - -``` -REVOKE [READ,WRITE,ALL] ON FROM -``` - -CLI examples: - -`REVOKE` `ALL` privileges from `todd` on the `NOAA_water_database` database: - -```sql -> REVOKE ALL ON "NOAA_water_database" FROM "todd" -> -``` - -`REVOKE` `WRITE` privileges from `todd` on the `NOAA_water_database` database: - -```sql -> REVOKE WRITE ON "NOAA_water_database" FROM "todd" -> -``` - ->**Note:** If a user with `ALL` privileges has `WRITE` privileges revoked, they are left with `READ` privileges, and vice versa. - -##### `SHOW` a user's database privileges - -```sql -SHOW GRANTS FOR -``` - -CLI example: - -```sql -> SHOW GRANTS FOR "todd" -database privilege -NOAA_water_database WRITE -another_database_name READ -yet_another_database_name ALL PRIVILEGES -one_more_database_name NO PRIVILEGES -``` - -#### General admin and non-admin user management - -##### Reset a user's password - -```sql -SET PASSWORD FOR = '' -``` - -CLI example: - -```sql -> SET PASSWORD FOR "todd" = 'influxdb4ever' -> -``` - -{{% note %}} -**Note:** The password [string](/influxdb/v1.8/query_language/spec/#strings) must be wrapped in single quotes. -Do not include the single quotes when authenticating requests. - -We recommend avoiding the single quote (`'`) and backslash (`\`) characters in passwords -For passwords that include these characters, escape the special character with a backslash (e.g. (`\'`) when creating the password and when submitting authentication requests. -{{% /note %}} - -##### `DROP` a user - -```sql -DROP USER -``` - -CLI example: - -```sql -> DROP USER "todd" -> -``` - -## Authentication and authorization HTTP errors - -Requests with no authentication credentials or incorrect credentials yield the `HTTP 401 Unauthorized` response. - -Requests by unauthorized users yield the `HTTP 403 Forbidden` response. diff --git a/content/enterprise_influxdb/v1.9/administration/backup-and-restore.md b/content/enterprise_influxdb/v1.9/administration/backup-and-restore.md index bce96b6ec..e2ee45610 100644 --- a/content/enterprise_influxdb/v1.9/administration/backup-and-restore.md +++ b/content/enterprise_influxdb/v1.9/administration/backup-and-restore.md @@ -1,13 +1,13 @@ --- -title: Back up and restore InfluxDB Enterprise clusters +title: Back up and restore description: > - Back up and restore InfluxDB enterprise clusters in case of unexpected data loss. + Back up and restore InfluxDB enterprise clusters to prevent data loss. aliases: - /enterprise/v1.8/guides/backup-and-restore/ menu: enterprise_influxdb_1_9: name: Back up and restore - weight: 80 + weight: 10 parent: Administration --- diff --git a/content/enterprise_influxdb/v1.9/administration/configure/_index.md b/content/enterprise_influxdb/v1.9/administration/configure/_index.md new file mode 100644 index 000000000..436442772 --- /dev/null +++ b/content/enterprise_influxdb/v1.9/administration/configure/_index.md @@ -0,0 +1,11 @@ +--- +title: Configure +description: Configure cluster and node settings in InfluxDB Enterprise. +menu: + enterprise_influxdb_1_9: + name: Configure + weight: 11 + parent: Administration +--- + +{{< children >}} diff --git a/content/enterprise_influxdb/v1.9/administration/anti-entropy/_index.md b/content/enterprise_influxdb/v1.9/administration/configure/anti-entropy/_index.md similarity index 99% rename from content/enterprise_influxdb/v1.9/administration/anti-entropy/_index.md rename to content/enterprise_influxdb/v1.9/administration/configure/anti-entropy/_index.md index 4dc0dae35..c832ef984 100644 --- a/content/enterprise_influxdb/v1.9/administration/anti-entropy/_index.md +++ b/content/enterprise_influxdb/v1.9/administration/configure/anti-entropy/_index.md @@ -3,11 +3,12 @@ title: Use Anti-Entropy service in InfluxDB Enterprise description: The Anti-Entropy service monitors and repairs shards in InfluxDB. aliases: - /enterprise_influxdb/v1.9/guides/Anti-Entropy/ + - /enterprise_influxdb/v1.9/administration/anti-entropy/ menu: enterprise_influxdb_1_9: name: Use Anti-entropy service weight: 60 - parent: Administration + parent: Configure --- {{% warn %}} diff --git a/content/enterprise_influxdb/v1.9/administration/anti-entropy/anti-entropy-api.md b/content/enterprise_influxdb/v1.9/administration/configure/anti-entropy/anti-entropy-api.md similarity index 100% rename from content/enterprise_influxdb/v1.9/administration/anti-entropy/anti-entropy-api.md rename to content/enterprise_influxdb/v1.9/administration/configure/anti-entropy/anti-entropy-api.md diff --git a/content/enterprise_influxdb/v1.9/administration/config-data-nodes.md b/content/enterprise_influxdb/v1.9/administration/configure/config-data-nodes.md similarity index 99% rename from content/enterprise_influxdb/v1.9/administration/config-data-nodes.md rename to content/enterprise_influxdb/v1.9/administration/configure/config-data-nodes.md index 3a62ca07b..ad845dd66 100644 --- a/content/enterprise_influxdb/v1.9/administration/config-data-nodes.md +++ b/content/enterprise_influxdb/v1.9/administration/configure/config-data-nodes.md @@ -6,7 +6,9 @@ menu: enterprise_influxdb_1_9: name: Configure data nodes weight: 20 - parent: Administration + parent: Configure +aliases: + - /enterprise_influxdb/v1.9/administration/config-data-nodes/ --- * [Data node configuration settings](#data-node-configuration-settings) diff --git a/content/enterprise_influxdb/v1.9/administration/config-meta-nodes.md b/content/enterprise_influxdb/v1.9/administration/configure/config-meta-nodes.md similarity index 99% rename from content/enterprise_influxdb/v1.9/administration/config-meta-nodes.md rename to content/enterprise_influxdb/v1.9/administration/configure/config-meta-nodes.md index 7eeec949f..eef81b08c 100644 --- a/content/enterprise_influxdb/v1.9/administration/config-meta-nodes.md +++ b/content/enterprise_influxdb/v1.9/administration/configure/config-meta-nodes.md @@ -6,7 +6,9 @@ menu: enterprise_influxdb_1_9: name: Configure meta nodes weight: 21 - parent: Administration + parent: Configure +aliases: + - /enterprise_influxdb/v1.9/administration/config-meta-nodes/ --- * [Meta node configuration settings](#meta-node-configuration-settings) diff --git a/content/enterprise_influxdb/v1.9/administration/configuration.md b/content/enterprise_influxdb/v1.9/administration/configure/configuration.md similarity index 98% rename from content/enterprise_influxdb/v1.9/administration/configuration.md rename to content/enterprise_influxdb/v1.9/administration/configure/configuration.md index 48b6030cc..4dc8be4d5 100644 --- a/content/enterprise_influxdb/v1.9/administration/configuration.md +++ b/content/enterprise_influxdb/v1.9/administration/configure/configuration.md @@ -4,11 +4,12 @@ description: > Learn about global options, meta node options, data node options and other InfluxDB Enterprise configuration settings, including aliases: - /enterprise/v1.8/administration/configuration/ + - /enterprise/v1.9/administration/configuration/ menu: enterprise_influxdb_1_9: name: Configure clusters weight: 10 - parent: Administration + parent: Configure --- This page contains general information about configuring InfluxDB Enterprise clusters. diff --git a/content/enterprise_influxdb/v1.9/administration/ports.md b/content/enterprise_influxdb/v1.9/administration/configure/ports.md similarity index 97% rename from content/enterprise_influxdb/v1.9/administration/ports.md rename to content/enterprise_influxdb/v1.9/administration/configure/ports.md index 628cd54a7..7d93ba3c7 100644 --- a/content/enterprise_influxdb/v1.9/administration/ports.md +++ b/content/enterprise_influxdb/v1.9/administration/configure/ports.md @@ -5,7 +5,9 @@ menu: enterprise_influxdb_1_9: name: Configure TCP and UDP Ports weight: 120 - parent: Administration + parent: Configure +aliases: + - /enterprise/v1.9/administration/ports/ --- ![InfluxDB Enterprise network diagram](/img/enterprise/1-8-network-diagram.png) diff --git a/content/enterprise_influxdb/v1.9/administration/manage/_index.md b/content/enterprise_influxdb/v1.9/administration/manage/_index.md new file mode 100644 index 000000000..0b7d5638c --- /dev/null +++ b/content/enterprise_influxdb/v1.9/administration/manage/_index.md @@ -0,0 +1,11 @@ +--- +title: Manage +description: Manage security, clusters, and subscriptions in InfluxDB enterprise. +menu: + enterprise_influxdb_1_9: + name: Manage + weight: 12 + parent: Administration +--- + +{{< children >}} diff --git a/content/enterprise_influxdb/v1.9/administration/cluster-commands.md b/content/enterprise_influxdb/v1.9/administration/manage/cluster-commands.md similarity index 94% rename from content/enterprise_influxdb/v1.9/administration/cluster-commands.md rename to content/enterprise_influxdb/v1.9/administration/manage/cluster-commands.md index 58afc610b..16b1ea719 100644 --- a/content/enterprise_influxdb/v1.9/administration/cluster-commands.md +++ b/content/enterprise_influxdb/v1.9/administration/manage/cluster-commands.md @@ -5,11 +5,12 @@ description: > aliases: - /enterprise/v1.8/features/cluster-commands/ - /enterprise_influxdb/v1.9/features/cluster-commands/ + - /enterprise_influxdb/v1.9/administration/cluster-commands/ menu: enterprise_influxdb_1_9: name: Manage clusters - weight: 40 - parent: Administration + weight: 30 + parent: Manage --- Use the following tools to manage and interact with your InfluxDB Enterprise clusters: diff --git a/content/enterprise_influxdb/v1.9/administration/renaming.md b/content/enterprise_influxdb/v1.9/administration/manage/renaming.md similarity index 96% rename from content/enterprise_influxdb/v1.9/administration/renaming.md rename to content/enterprise_influxdb/v1.9/administration/manage/renaming.md index b1e48fcd4..243ea372b 100644 --- a/content/enterprise_influxdb/v1.9/administration/renaming.md +++ b/content/enterprise_influxdb/v1.9/administration/manage/renaming.md @@ -2,12 +2,13 @@ title: Rename hosts in InfluxDB Enterprise description: Rename a host within your InfluxDB Enterprise instance. aliases: - - /enterprise/v1.8/administration/renaming/ + - /enterprise_influxdb/v1.8/administration/renaming/ + - /enterprise_influxdb/v1.9/administration/renaming/ menu: enterprise_influxdb_1_9: name: Rename hosts weight: 100 - parent: Administration + parent: Manage --- ## Host renaming diff --git a/content/enterprise_influxdb/v1.9/administration/security.md b/content/enterprise_influxdb/v1.9/administration/manage/security/_index.md similarity index 84% rename from content/enterprise_influxdb/v1.9/administration/security.md rename to content/enterprise_influxdb/v1.9/administration/manage/security/_index.md index 3d648f0bc..7ce34a05b 100644 --- a/content/enterprise_influxdb/v1.9/administration/security.md +++ b/content/enterprise_influxdb/v1.9/administration/manage/security/_index.md @@ -1,14 +1,18 @@ --- -title: Manage security in InfluxDB Enterprise -description: Protect the data in your InfluxDB Enterprise instance. +title: Manage security +description: Configuration, security, and logging in InfluxDB enterprise. menu: enterprise_influxdb_1_9: name: Manage security - weight: 110 - parent: Administration + weight: 40 + parent: Manage +aliases: + - /enterprise_influxdb/v1.9/administration/security/ --- -Some customers may choose to install InfluxDB Enterprise with public internet access, however doing so can inadvertently expose your data and invite unwelcome attacks on your database. + + +{{< children >}} diff --git a/content/enterprise_influxdb/v1.9/administration/manage/security/authentication_and_authorization-api.md b/content/enterprise_influxdb/v1.9/administration/manage/security/authentication_and_authorization-api.md new file mode 100644 index 000000000..db508b824 --- /dev/null +++ b/content/enterprise_influxdb/v1.9/administration/manage/security/authentication_and_authorization-api.md @@ -0,0 +1,742 @@ +--- +title: Manage users and privileges with Meta API +description: > + Set up and manage authentication and authorization in InfluxDB Enterprise. +menu: + enterprise_influxdb_1_9: + name: Manage security with Meta API + weight: 30 + parent: Manage security +--- + +- [Overview](#overview) +- [API examples](#user-and-privilege-management-over-the-influxd-meta-api) + +## Overview + +Authentication and authorization can be managed using the InfluxDB Enterprise Meta API. + +User and privilege management means +managing the contents of a user store and the permissions that users can be granted. +It entails creating and deleting users and roles, granting them privileges, and assigning roles to users. + +Managing users, roles and privileges can be done using the Chronograf InfluxDB Admin console. +However, certain operations are only available through the Enterprise meta API. + + +**Users** are granted a set of privileges. + + +A **role** is a predefined collection of privileges that can be assigned to a user. + +A **permission** (also *privilege*) is the ability to access a resource in some way, including: +- viewing the resource +- copying the resource +- dropping the resource +- writing to the resource +- full management capabilities + +The level of access and the resource are combined in predefined keys. + + +Predefined key tokens take the form of verb-object pairs. +When the token lacks the verb part, full management privileges are implied. +These predefined tokens are: + +* `ViewAdmin` +* `ViewChronograf` +* `CreateDatabase` +* `CreateUserAndRole` +* `AddRemoveNode` +* `DropDatabase` +* `DropData` +* `ReadData` +* `WriteData` +* `Rebalance` +* `ManageShard` +* `ManageContinuousQuery` +* `ManageQuery` +* `ManageSubscription` +* `Monitor` +* `CopyShard` + +{{% note %}} +These privileges are system privileges and are separate from the database-specific privileges +that can be inspected using the `show grants for ""` command when connected to a data node. +{{% /note %}} + +In addition, two tokens govern Kapacitor permissions: + +* `KapacitorAPI`: + Grants the user permission to create, read, update and delete + tasks, topics, handlers and similar Kapacitor artefacts. +* `KapacitorConfigAPI`: + Grants the user permission to override the Kapacitor configuration + dynamically using the configuration endpoint. + +### User and privilege management over the InfluxDB Enterprise meta API + +**Users**: + +- [List users](#list-users) +- [Create a user against a follower node](#create-a-user-against-a-follower-node) +- [Create a user against the lead node](#create-a-user-against-the-lead-node) +- [Retrieve a user details document](#retrieve-a-user-details-document) +- [Grant permissions to a user](#grant-permissions-to-a-user) +- [Verify user permissions](#verify-user-permissions) +- [Remove permissions from a user](#remove-permissions-from-a-user) +- [Remove a user](#remove-a-user) +- [Verify user removal](#verify-user-removal) + +**Roles**: + +- [List roles](#list-roles) +- [Create a role](#create-a-role) +- [Verify roles](#verify-roles) +- [Retrieve a role document](#retrieve-a-role-document) +- [Add permissions to a role](#add-permissions-to-a-role) +- [Verify role permissions](#verify-role-permissions) +- [Add a user to a role](#add-a-user-to-a-role) +- [Verify user in role](#verify-user-in-role) +- [Remove a user from a role](#remove-a-user-from-a-role) +- [Remove a permission from a role](#remove-a-permission-from-a-role) +- [Delete a role](#delete-a-role) +- [Verify role deletion](#verify-role-deletion) + +#### Users + +Use the `/user` endpoint of the InfluxDB Enterprise Meta API to manage users. + +##### List users +View a list of existing users. + +``` +$ curl -u "admin:changeit" -s https://cluster_node_1:8091/user | python -m json.tool +{ + "users": [ + { + "hash": "$2a$10$NelNfrWdxubN0/TnP7DwquKB9/UmJnyZ7gy0i69MPldK73m.2WfCu", + "name": "admin", + "permissions": { + "": [ + "ViewAdmin", + "ViewChronograf", + "CreateDatabase", + "CreateUserAndRole", + "AddRemoveNode", + "DropDatabase", + "DropData", + "ReadData", + "WriteData", + "Rebalance", + "ManageShard", + "ManageContinuousQuery", + "ManageQuery", + "ManageSubscription", + "Monitor", + "CopyShard", + "KapacitorAPI", + "KapacitorConfigAPI" + ] + } + } + ] +} +``` + +##### Create a user against a follower node + +Transactions that modify the user store must be sent to the lead meta node using `POST`. + +If the node returns a 307 redirect message, +try resending the request to the lead node as indicated by the `Location` field in the HTTP response header. + +``` +$ curl -u "admin:changeit" -s -v -d '{"action":"create","user":{"name":"phantom2","password":"changeit"}}' https://cluster_node_2:8091/user +* Trying 172.31.16.140... +* Connected to cluster_node_2 (172.31.16.140) port 8091 (#0) +* found 149 certificates in /etc/ssl/certs/ca-certificates.crt +* found 596 certificates in /etc/ssl/certs +* ALPN, offering http/1.1 +* SSL connection using TLS1.2 / ECDHE_RSA_AES_128_GCM_SHA256 +* server certificate verification OK +* server certificate status verification SKIPPED +* common name: cluster_node_2 (matched) +* server certificate expiration date OK +* server certificate activation date OK +* certificate public key: RSA +* certificate version: #1 +* subject: C=CZ,ST=Praha,L=Hlavni-mesto,O=Bonitoo.io,OU=QA,CN=cluster_node_2 +* start date: Tue, 27 Mar 2018 12:34:09 GMT +* expire date: Thu, 26 Mar 2020 12:34:09 GMT +* issuer: C=CZ,ST=Praha,L=Hlavni-mesto,O=bonitoo.io,OU=QA,CN=bonitoo.io,EMAIL=tester@qa.org +* compression: NULL +* ALPN, server did not agree to a protocol +* Server auth using Basic with user 'admin' +> POST /user HTTP/1.1 +> Host: cluster_node_2:8091 +> Authorization: Basic YWRtaW46Y2hhbmdlaXQ= +> User-Agent: curl/7.47.0 +> Accept: */* +> Content-Length: 68 +> Content-Type: application/x-www-form-urlencoded +> +* upload completely sent off: 68 out of 68 bytes +< HTTP/1.1 307 Temporary Redirect +< Influxdb-Metaindex: 33402 +< Location: https://cluster_node_1:8091/user +< Request-Id: b7489b68-38c4-11e8-9cf7-000000000000 +< X-Influxdb-Version: 1.5.1-c1.5.1 +< Date: Thu, 05 Apr 2018 11:30:17 GMT +< Content-Length: 0 +< Content-Type: text/plain; charset=utf-8 +< +``` + +##### Create a user against the lead node + +``` +$ curl -u "admin:changeit" -s -v -d '{"action":"create","user":{"name":"phantom","password":"changeit"}}' https://cluster_node_1:8091/user +* Trying 172.31.16.108... +* Connected to cluster_node_1 (172.31.16.108) port 8091 (#0) +* found 149 certificates in /etc/ssl/certs/ca-certificates.crt +* found 596 certificates in /etc/ssl/certs +* ALPN, offering http/1.1 +* SSL connection using TLS1.2 / ECDHE_RSA_AES_128_GCM_SHA256 +* server certificate verification OK +* server certificate status verification SKIPPED +* common name: cluster_node_1 (matched) +* server certificate expiration date OK +* server certificate activation date OK +* certificate public key: RSA +* certificate version: #1 +* subject: C=CZ,ST=Praha,L=Hlavni-mesto,O=Bonitoo.io,OU=QA,CN=cluster_node_1 +* start date: Tue, 27 Mar 2018 12:29:36 GMT +* expire date: Thu, 26 Mar 2020 12:29:36 GMT +* issuer: C=CZ,ST=Praha,L=Hlavni-mesto,O=bonitoo.io,OU=QA,CN=bonitoo.io,EMAIL=tester@qa.org +* compression: NULL +* ALPN, server did not agree to a protocol +* Server auth using Basic with user 'admin' +> POST /user HTTP/1.1 +> Host: cluster_node_1:8091 +> Authorization: Basic YWRtaW46Y2hhbmdlaXQ= +> User-Agent: curl/7.47.0 +> Accept: */* +> Content-Length: 68 +> Content-Type: application/x-www-form-urlencoded +> +* upload completely sent off: 68 out of 68 bytes +< HTTP/1.1 200 OK +< Request-Id: 6711760c-38c4-11e8-b7ff-000000000000 +< X-Influxdb-Version: 1.5.1-c1.5.1 +< Date: Thu, 05 Apr 2018 11:28:02 GMT +< Content-Length: 0 +< Content-Type: text/plain; charset=utf-8 +< +``` + +##### Retrieve a user details document + +``` +$ curl --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/user?name=phantom | python -m json.tool +{ + "users": [ + { + "hash": "$2a$10$hR.Ih6DpIHUaynA.uqFhpOiNUgrADlwg3rquueHDuw58AEd7zk5hC", + "name": "phantom" + } + ] +} +``` + +##### Grant permissions to a user + +``` +$ curl --negotiate -u "admin:changeit" -s -v -d '{"action":"add-permissions","user":{"name":"phantom","permissions":{"":["KapacitorAPI","KapacitorConfigAPI"]}}}' https://cluster_node_1:8091/user +* Trying 172.31.16.108... +* Connected to cluster_node_1 (172.31.16.108) port 8091 (#0) +* found 149 certificates in /etc/ssl/certs/ca-certificates.crt +* found 596 certificates in /etc/ssl/certs +* ALPN, offering http/1.1 +* SSL connection using TLS1.2 / ECDHE_RSA_AES_128_GCM_SHA256 +* server certificate verification OK +* server certificate status verification SKIPPED +* common name: cluster_node_1 (matched) +* server certificate expiration date OK +* server certificate activation date OK +* certificate public key: RSA +* certificate version: #1 +* subject: C=CZ,ST=Praha,L=Hlavni-mesto,O=Bonitoo.io,OU=QA,CN=cluster_node_1 +* start date: Tue, 27 Mar 2018 12:29:36 GMT +* expire date: Thu, 26 Mar 2020 12:29:36 GMT +* issuer: C=CZ,ST=Praha,L=Hlavni-mesto,O=bonitoo.io,OU=QA,CN=bonitoo.io,EMAIL=tester@qa.org +* compression: NULL +* ALPN, server did not agree to a protocol +> POST /user HTTP/1.1 +> Host: cluster_node_1:8091 +> User-Agent: curl/7.47.0 +> Accept: */* +> Content-Length: 111 +> Content-Type: application/x-www-form-urlencoded +> +* upload completely sent off: 111 out of 111 bytes +< HTTP/1.1 200 OK +< Request-Id: 604141f2-38c6-11e8-bc15-000000000000 +< X-Influxdb-Version: 1.5.1-c1.5.1 +< Date: Thu, 05 Apr 2018 11:42:10 GMT +< Content-Length: 0 +< Content-Type: text/plain; charset=utf-8 +< +``` + +##### Verify user permissions + +``` +$ curl --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/user?name=phantom | python -m json.tool +{ + "users": [ + { + "hash": "$2a$10$hR.Ih6DpIHUaynA.uqFhpOiNUgrADlwg3rquueHDuw58AEd7zk5hC", + "name": "phantom", + "permissions": { + "": [ + "KapacitorAPI", + "KapacitorConfigAPI" + ] + } + } + ] +} +``` + +##### Remove permissions from a user + +``` +$ curl --negotiate -u "admin:changeit" -s -v -d '{"action":"remove-permissions","user":{"name":"phantom","permissions":{"":["KapacitorConfigAPI"]}}}' https://cluster_node_1:8091/user +* Trying 172.31.16.108... +* Connected to cluster_node_1 (172.31.16.108) port 8091 (#0) +* found 149 certificates in /etc/ssl/certs/ca-certificates.crt +* found 596 certificates in /etc/ssl/certs +* ALPN, offering http/1.1 +* SSL connection using TLS1.2 / ECDHE_RSA_AES_128_GCM_SHA256 +* server certificate verification OK +* server certificate status verification SKIPPED +* common name: cluster_node_1 (matched) +* server certificate expiration date OK +* server certificate activation date OK +* certificate public key: RSA +* certificate version: #1 +* subject: C=CZ,ST=Praha,L=Hlavni-mesto,O=Bonitoo.io,OU=QA,CN=cluster_node_1 +* start date: Tue, 27 Mar 2018 12:29:36 GMT +* expire date: Thu, 26 Mar 2020 12:29:36 GMT +* issuer: C=CZ,ST=Praha,L=Hlavni-mesto,O=bonitoo.io,OU=QA,CN=bonitoo.io,EMAIL=tester@qa.org +* compression: NULL +* ALPN, server did not agree to a protocol +> POST /user HTTP/1.1 +> Host: cluster_node_1:8091 +> User-Agent: curl/7.47.0 +> Accept: */* +> Content-Length: 99 +> Content-Type: application/x-www-form-urlencoded +> +* upload completely sent off: 99 out of 99 bytes +< HTTP/1.1 200 OK +< Request-Id: 1d84744c-38c7-11e8-bd97-000000000000 +< X-Influxdb-Version: 1.5.1-c1.5.1 +< Date: Thu, 05 Apr 2018 11:47:27 GMT +< Content-Length: 0 +< Content-Type: text/plain; charset=utf-8 +< +``` + +##### Remove a user + +``` +$ curl --negotiate -u "admin:changeit" -s -v -d '{"action":"delete","user":{"name":"phantom2"}}' https://cluster_node_1:8091/user +* Trying 172.31.16.108... +* Connected to cluster_node_1 (172.31.16.108) port 8091 (#0) +* found 149 certificates in /etc/ssl/certs/ca-certificates.crt +* found 596 certificates in /etc/ssl/certs +* ALPN, offering http/1.1 +* SSL connection using TLS1.2 / ECDHE_RSA_AES_128_GCM_SHA256 +* server certificate verification OK +* server certificate status verification SKIPPED +* common name: cluster_node_1 (matched) +* server certificate expiration date OK +* server certificate activation date OK +* certificate public key: RSA +* certificate version: #1 +* subject: C=CZ,ST=Praha,L=Hlavni-mesto,O=Bonitoo.io,OU=QA,CN=cluster_node_1 +* start date: Tue, 27 Mar 2018 12:29:36 GMT +* expire date: Thu, 26 Mar 2020 12:29:36 GMT +* issuer: C=CZ,ST=Praha,L=Hlavni-mesto,O=bonitoo.io,OU=QA,CN=bonitoo.io,EMAIL=tester@qa.org +* compression: NULL +* ALPN, server did not agree to a protocol +> POST /user HTTP/1.1 +> Host: cluster_node_1:8091 +> User-Agent: curl/7.47.0 +> Accept: */* +> Content-Length: 46 +> Content-Type: application/x-www-form-urlencoded +> +* upload completely sent off: 46 out of 46 bytes +< HTTP/1.1 200 OK +< Request-Id: 8dda5513-38c7-11e8-be84-000000000000 +< X-Influxdb-Version: 1.5.1-c1.5.1 +< Date: Thu, 05 Apr 2018 11:50:36 GMT +< Content-Length: 0 +< Content-Type: text/plain; charset=utf-8 +< +``` + +##### Verify user removal + +``` +$ curl --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/user?name=phantom +{"error":"user not found"} +``` + +#### Roles + +The Influxd-Meta API provides an endpoint `/role` for managing roles. + +##### List roles + +``` +$ curl --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/role | python -m json.tool +{} +``` + +In a fresh installation no roles will have been created yet. +As when creating a user the lead node must be used. + +##### Create a role + +``` +$ curl --negotiate -u "admin:changeit" -v -d '{"action":"create","role":{"name":"spectre"}}' https://cluster_node_1:8091/role +* Trying 172.31.16.108... +* Connected to cluster_node_1 (172.31.16.108) port 8091 (#0) +* found 149 certificates in /etc/ssl/certs/ca-certificates.crt +* found 596 certificates in /etc/ssl/certs +* ALPN, offering http/1.1 +* SSL connection using TLS1.2 / ECDHE_RSA_AES_128_GCM_SHA256 +* server certificate verification OK +* server certificate status verification SKIPPED +* common name: cluster_node_1 (matched) +* server certificate expiration date OK +* server certificate activation date OK +* certificate public key: RSA +* certificate version: #1 +* subject: C=CZ,ST=Praha,L=Hlavni-mesto,O=Bonitoo.io,OU=QA,CN=cluster_node_1 +* start date: Tue, 27 Mar 2018 12:29:36 GMT +* expire date: Thu, 26 Mar 2020 12:29:36 GMT +* issuer: C=CZ,ST=Praha,L=Hlavni-mesto,O=bonitoo.io,OU=QA,CN=bonitoo.io,EMAIL=tester@qa.org +* compression: NULL +* ALPN, server did not agree to a protocol +> POST /role HTTP/1.1 +> Host: cluster_node_1:8091 +> User-Agent: curl/7.47.0 +> Accept: */* +> Content-Length: 45 +> Content-Type: application/x-www-form-urlencoded +> +* upload completely sent off: 45 out of 45 bytes +< HTTP/1.1 200 OK +< Influxdb-Metaindex: 33408 +< Request-Id: 733b3294-38c8-11e8-805f-000000000000 +< X-Influxdb-Version: 1.5.1-c1.5.1 +< Date: Thu, 05 Apr 2018 11:57:01 GMT +< Content-Length: 0 +< Content-Type: text/plain; charset=utf-8 +< +``` + +##### Verify roles +Verify the role has been created. + +``` +$ curl --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/role | python -m json.tool +{ + "roles": [ + { + "name": "djinn", + }, + { + "name": "spectre" + }, + ] +} + +``` + +##### Retrieve a role document +Retrieve a record for a single node. + +``` +curl --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/role?name=spectre | python -m json.tool +{ + "roles": [ + { + "name": "spectre" + } + ] +} +``` + +##### Add permissions to a role +Add permissions to a role. + +``` +$ curl --negotiate -u "admin:changeit" -s -v -d '{"action":"add-permissions","role":{"name":"spectre","permissions":{"":["KapacitorAPI","KapacitorConfigAPI"]}}}' https://cluster_node_1:8091/role +* Trying 172.31.16.108... +* Connected to cluster_node_1 (172.31.16.108) port 8091 (#0) +* found 149 certificates in /etc/ssl/certs/ca-certificates.crt +* found 596 certificates in /etc/ssl/certs +* ALPN, offering http/1.1 +* SSL connection using TLS1.2 / ECDHE_RSA_AES_128_GCM_SHA256 +* server certificate verification OK +* server certificate status verification SKIPPED +* common name: cluster_node_1 (matched) +* server certificate expiration date OK +* server certificate activation date OK +* certificate public key: RSA +* certificate version: #1 +* subject: C=CZ,ST=Praha,L=Hlavni-mesto,O=Bonitoo.io,OU=QA,CN=cluster_node_1 +* start date: Tue, 27 Mar 2018 12:29:36 GMT +* expire date: Thu, 26 Mar 2020 12:29:36 GMT +* issuer: C=CZ,ST=Praha,L=Hlavni-mesto,O=bonitoo.io,OU=QA,CN=bonitoo.io,EMAIL=tester@qa.org +* compression: NULL +* ALPN, server did not agree to a protocol +> POST /role HTTP/1.1 +> Host: cluster_node_1:8091 +> User-Agent: curl/7.47.0 +> Accept: */* +> Content-Length: 111 +> Content-Type: application/x-www-form-urlencoded +> +* upload completely sent off: 111 out of 111 bytes +< HTTP/1.1 200 OK +< Influxdb-Metaindex: 33412 +< Request-Id: 603934f5-38c9-11e8-8252-000000000000 +< X-Influxdb-Version: 1.5.1-c1.5.1 +< Date: Thu, 05 Apr 2018 12:03:38 GMT +< Content-Length: 0 +< Content-Type: text/plain; charset=utf-8 +< +``` + +##### Verify role permissions +Verify permissions have been added. + +``` +$ curl --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/role?name=spectre | python -m json.tool +{ + "roles": [ + { + "name": "spectre", + "permissions": { + "": [ + "KapacitorAPI", + "KapacitorConfigAPI" + ] + } + } + ] +} +``` + +##### Add a user to a role + +``` +$ curl --negotiate -u "admin:changeit" -s -v -d '{"action":"add-users","role":{"name":"spectre","users":["phantom"]}}' https://cluster_node_1:8091/role +* Trying 172.31.16.108... +* Connected to cluster_node_1 (172.31.16.108) port 8091 (#0) +* found 149 certificates in /etc/ssl/certs/ca-certificates.crt +* found 596 certificates in /etc/ssl/certs +* ALPN, offering http/1.1 +* SSL connection using TLS1.2 / ECDHE_RSA_AES_128_GCM_SHA256 +* server certificate verification OK +* server certificate status verification SKIPPED +* common name: cluster_node_1 (matched) +* server certificate expiration date OK +* server certificate activation date OK +* certificate public key: RSA +* certificate version: #1 +* subject: C=CZ,ST=Praha,L=Hlavni-mesto,O=Bonitoo.io,OU=QA,CN=cluster_node_1 +* start date: Tue, 27 Mar 2018 12:29:36 GMT +* expire date: Thu, 26 Mar 2020 12:29:36 GMT +* issuer: C=CZ,ST=Praha,L=Hlavni-mesto,O=bonitoo.io,OU=QA,CN=bonitoo.io,EMAIL=tester@qa.org +* compression: NULL +* ALPN, server did not agree to a protocol +> POST /role HTTP/1.1 +> Host: cluster_node_1:8091 +> User-Agent: curl/7.47.0 +> Accept: */* +> Content-Length: 68 +> Content-Type: application/x-www-form-urlencoded +> +* upload completely sent off: 68 out of 68 bytes +< HTTP/1.1 200 OK +< Influxdb-Metaindex: 33413 +< Request-Id: 2f3f4310-38ca-11e8-83f4-000000000000 +< X-Influxdb-Version: 1.5.1-c1.5.1 +< Date: Thu, 05 Apr 2018 12:09:26 GMT +< Content-Length: 0 +< Content-Type: text/plain; charset=utf-8 +< +``` + +##### Verify user in role +Verify user has been added to role. + +``` +$ curl --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/role?name=spectre | python -m json.tool +{ + "roles": [ + { + "name": "spectre", + "permissions": { + "": [ + "KapacitorAPI", + "KapacitorConfigAPI" + ] + }, + "users": [ + "phantom" + ] + } + ] +} +``` + +##### Remove a user from a role + +``` +$ curl --negotiate -u "admin:changeit" -s -v -d '{"action":"remove-users","role":{"name":"spectre","users":["phantom"]}}' https://admin:changeit@cluster_node_1:8091/role +* Trying 172.31.16.108... +* Connected to cluster_node_1 (172.31.16.108) port 8091 (#0) +* found 149 certificates in /etc/ssl/certs/ca-certificates.crt +* found 596 certificates in /etc/ssl/certs +* ALPN, offering http/1.1 +* SSL connection using TLS1.2 / ECDHE_RSA_AES_128_GCM_SHA256 +* server certificate verification OK +* server certificate status verification SKIPPED +* common name: cluster_node_1 (matched) +* server certificate expiration date OK +* server certificate activation date OK +* certificate public key: RSA +* certificate version: #1 +* subject: C=CZ,ST=Praha,L=Hlavni-mesto,O=Bonitoo.io,OU=QA,CN=cluster_node_1 +* start date: Tue, 27 Mar 2018 12:29:36 GMT +* expire date: Thu, 26 Mar 2020 12:29:36 GMT +* issuer: C=CZ,ST=Praha,L=Hlavni-mesto,O=bonitoo.io,OU=QA,CN=bonitoo.io,EMAIL=tester@qa.org +* compression: NULL +* ALPN, server did not agree to a protocol +> POST /role HTTP/1.1 +> Host: cluster_node_1:8091 +> User-Agent: curl/7.47.0 +> Accept: */* +> Content-Length: 71 +> Content-Type: application/x-www-form-urlencoded +> +* upload completely sent off: 71 out of 71 bytes +< HTTP/1.1 200 OK +< Influxdb-Metaindex: 33414 +< Request-Id: 840896df-38ca-11e8-84a9-000000000000 +< X-Influxdb-Version: 1.5.1-c1.5.1 +< Date: Thu, 05 Apr 2018 12:11:48 GMT +< Content-Length: 0 +< Content-Type: text/plain; charset=utf-8 +< +``` + +##### Remove a permission from a role + +``` +$ curl --negotiate -u "admin:changeit" -s -v -d '{"action":"remove-permissions","role":{"name":"spectre","permissions":{"":["KapacitorConfigAPI"]}}}' https://cluster_node_1:8091/role +* Trying 172.31.16.108... +* Connected to cluster_node_1 (172.31.16.108) port 8091 (#0) +* found 149 certificates in /etc/ssl/certs/ca-certificates.crt +* found 596 certificates in /etc/ssl/certs +* ALPN, offering http/1.1 +* SSL connection using TLS1.2 / ECDHE_RSA_AES_128_GCM_SHA256 +* server certificate verification OK +* server certificate status verification SKIPPED +* common name: cluster_node_1 (matched) +* server certificate expiration date OK +* server certificate activation date OK +* certificate public key: RSA +* certificate version: #1 +* subject: C=CZ,ST=Praha,L=Hlavni-mesto,O=Bonitoo.io,OU=QA,CN=cluster_node_1 +* start date: Tue, 27 Mar 2018 12:29:36 GMT +* expire date: Thu, 26 Mar 2020 12:29:36 GMT +* issuer: C=CZ,ST=Praha,L=Hlavni-mesto,O=bonitoo.io,OU=QA,CN=bonitoo.io,EMAIL=tester@qa.org +* compression: NULL +* ALPN, server did not agree to a protocol +> POST /role HTTP/1.1 +> Host: cluster_node_1:8091 +> User-Agent: curl/7.47.0 +> Accept: */* +> Content-Length: 99 +> Content-Type: application/x-www-form-urlencoded +> +* upload completely sent off: 99 out of 99 bytes +< HTTP/1.1 200 OK +< Influxdb-Metaindex: 33415 +< Request-Id: a1d9a3e4-38ca-11e8-84f0-000000000000 +< X-Influxdb-Version: 1.5.1-c1.5.1 +< Date: Thu, 05 Apr 2018 12:12:38 GMT +< Content-Length: 0 +< Content-Type: text/plain; charset=utf-8 +< +``` + +##### Delete a role + +``` +$ curl --negotiate -u "admin:changeit" -s -v -d '{"action":"delete","role":{"name":"spectre"}}' https://cluster_node_1:8091/role +* Trying 172.31.16.108... +* Connected to cluster_node_1 (172.31.16.108) port 8091 (#0) +* found 149 certificates in /etc/ssl/certs/ca-certificates.crt +* found 596 certificates in /etc/ssl/certs +* ALPN, offering http/1.1 +* SSL connection using TLS1.2 / ECDHE_RSA_AES_128_GCM_SHA256 +* server certificate verification OK +* server certificate status verification SKIPPED +* common name: cluster_node_1 (matched) +* server certificate expiration date OK +* server certificate activation date OK +* certificate public key: RSA +* certificate version: #1 +* subject: C=CZ,ST=Praha,L=Hlavni-mesto,O=Bonitoo.io,OU=QA,CN=cluster_node_1 +* start date: Tue, 27 Mar 2018 12:29:36 GMT +* expire date: Thu, 26 Mar 2020 12:29:36 GMT +* issuer: C=CZ,ST=Praha,L=Hlavni-mesto,O=bonitoo.io,OU=QA,CN=bonitoo.io,EMAIL=tester@qa.org +* compression: NULL +* ALPN, server did not agree to a protocol +> POST /role HTTP/1.1 +> Host: cluster_node_1:8091 +> User-Agent: curl/7.47.0 +> Accept: */* +> Content-Length: 45 +> Content-Type: application/x-www-form-urlencoded +> +* upload completely sent off: 45 out of 45 bytes +< HTTP/1.1 200 OK +< Influxdb-Metaindex: 33416 +< Request-Id: c9ae3c8b-38ca-11e8-8546-000000000000 +< X-Influxdb-Version: 1.5.1-c1.5.1 +< Date: Thu, 05 Apr 2018 12:13:45 GMT +< Content-Length: 0 +< Content-Type: text/plain; charset=utf-8 +< +``` + +##### Verify role deletion + +``` +$ curl --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/role?name=spectre | python -m json.tool +{ + "error": "role not found" +} +``` diff --git a/content/enterprise_influxdb/v1.9/administration/manage/security/authentication_and_authorization.md b/content/enterprise_influxdb/v1.9/administration/manage/security/authentication_and_authorization.md new file mode 100644 index 000000000..82829ac60 --- /dev/null +++ b/content/enterprise_influxdb/v1.9/administration/manage/security/authentication_and_authorization.md @@ -0,0 +1,541 @@ +--- +title: Manage authentication and authorization +description: > + Set up and manage authentication and authorization in InfluxDB Enterprise. +menu: + enterprise_influxdb_1_9: + name: Manage authentication and authorization + weight: 30 + parent: Manage security +related: + - /enterprise_influxdb/v1.9/guides/fine-grained-authorization/ + - /{{< latest "chronograf" >}}/administration/managing-influxdb-users/ +aliases: + - enterprise_influxdb/v1.9/administration/authentication_and_authorization/ +--- + +This document covers setting up and managing authentication and authorization in InfluxDB Enterprise. + +- [Authentication](#authentication) + - [Enable Authentication](#enable-authentication) + - [Authenticate Requests](#authenticate-requests) +- [Authorization](#authorization) + - [User Types and Privileges](#user-types-and-privileges) + - [User Management Commands](#user-management-commands) +- [HTTP Errors](#authentication-and-authorization-http-errors) + +## Authentication + +Enable authentication in InfluxDB Enterprise +to only allow requests that are sent with valid credentials to execute. + +{{% note %}} +#### Plugins not authenticated +Authentication only occurs at the HTTP request scope. +Plugins do not currently have the ability to authenticate requests and service +endpoints (for example, Graphite, collectd, etc.) are not authenticated. +{{% /note %}} + +{{% note %}} +#### Authentication recommended on public endpoints +If InfluxDB Enterprise is being deployed on a publicly accessible endpoint, +we **strongly recommend** enabling authentication. +Otherwise, data and potentially destructive commands will be publicly available to any unauthenticated user. +For additional security, +InfluxDB Enterprise should be run behind a third-party service. +Authentication and authorization should not be soley relied upon +to prevent access and protect data from malicious actors. +{{% /note %}} + +### Enable authentication + +Authentication is disabled by default in InfluxDB and InfluxDB Enterprise. +All credentials are silently ignored, and all users have all privileges. + +To enable authentication in a cluster, do the following: + +1. **Create at least one [admin user](#admin-users)**. + + To create an admin user, + run the following command using the [`influx` CLI](/enterprise_influxdb/v1.9/tools/influx-cli/): + ``` + CREATE USER admin WITH PASSWORD 'mypassword' WITH ALL PRIVILEGES + ``` + +2. **Enable authentication in your meta and data configuration files**. + + Set the `auth-enabled` options to `true` in the `[http]` section: + + ```toml + [http] + enabled = true + bind-address = ":8086" + auth-enabled = true # Set to true + log-enabled = true + write-tracing = false + pprof-enabled = true + pprof-auth-enabled = true + debug-pprof-enabled = false + ping-auth-enabled = true + https-enabled = true + https-certificate = "/etc/ssl/influxdb.pem" + ``` + + {{% note %}} +If `pprof-enabled` is set to `true`, set `pprof-auth-enabled` and `ping-auth-enabled` +to `true` to require authentication on profiling and ping endpoints. + {{% /note %}} + +3. **Restart InfluxDB Enterprise**. + Once restarted, InfluxDB Enterprise checks user credentials on every request and only + processes requests that have valid credentials for an existing user. + +### Authenticate requests + +#### Authenticate with the InfluxDB API + +Authenticate with the [InfluxDB API](/enterprise_influxdb/v1.9/tools/api/) using one of the following options: + +- [Authenticate with basic authentication](#authenticate-with-basic-authentication) +- [Authenticate with query parameters in the URL or request body](#authenticate-with-query-parameters-in-the-url-or-request-body) + +If you authenticate with both basic authentication **and** the URL query parameters, +the user credentials specified in the query parameters take precedence. +The following examples demonstrate queries with [admin user](#admin-users) permissions. +To learn about different users types, permissions, and how to manage users, see [authorization](#authorization). + +{{% note %}} +InfluxDB Enterprise redacts passwords in log output when you enable authentication. +{{% /note %}} + +##### Authenticate with basic authentication +```bash +curl -G http://localhost:8086/query \ + -u todd:password4todd \ + --data-urlencode "q=SHOW DATABASES" +``` + +##### Authenticate with query parameters in the URL or request body +Set `u` as the username and `p` as the password. + +###### Credentials as query parameters +```bash +curl -G "http://localhost:8086/query?u=todd&p=password4todd" \ + --data-urlencode "q=SHOW DATABASES" +``` + +###### Credentials in the request body +```bash +curl -G http://localhost:8086/query \ + --data-urlencode "u=todd" \ + --data-urlencode "p=password4todd" \ + --data-urlencode "q=SHOW DATABASES" +``` + +#### Authenticate with the CLI + +There are three options for authenticating with the [CLI](/enterprise_influxdb/v1.9/tools/influx-cli/): + +- [Authenticate with environment variables](#authenticate-with-environment-variables) +- [Authenticate with CLI flags](#authenticate-with-cli-flags) +- [Authenticate with credentials in the influx shell](#authenticate-with-credentials-in-the-influx-shell) + +##### Authenticate with environment variables +Use the `INFLUX_USERNAME` and `INFLUX_PASSWORD` environment variables to provide +authentication credentials to the `influx` CLI. + +```bash +export INFLUX_USERNAME=todd +export INFLUX_PASSWORD=password4todd +echo $INFLUX_USERNAME $INFLUX_PASSWORD +todd password4todd + +influx +Connected to http://localhost:8086 version {{< latest-patch >}} +InfluxDB shell {{< latest-patch >}} +``` + +##### Authenticate with CLI flags +Use the `-username` and `-password` flags to provide authentication credentials +to the `influx` CLI. + +```bash +influx -username todd -password password4todd +Connected to http://localhost:8086 version {{< latest-patch >}} +InfluxDB shell {{< latest-patch >}} +``` + +##### Authenticate with credentials in the influx shell +Start the `influx` shell and run the `auth` command. +Enter your username and password when prompted. + +```bash +$ influx +Connected to http://localhost:8086 version {{< latest-patch >}} +InfluxDB shell {{< latest-patch >}} +> auth +username: todd +password: +> +``` + +#### Authenticate using JWT tokens +For a more secure alternative to using passwords, include JWT tokens with requests to the InfluxDB API. +This is currently only possible through the [InfluxDB HTTP API](/enterprise_influxdb/v1.9/tools/api/). + +1. **Add a shared secret in your InfluxDB Enterprise configuration file**. + + InfluxDB Enterprise uses the shared secret to encode the JWT signature. + By default, `shared-secret` is set to an empty string, in which case no JWT authentication takes place. + + Add a custom shared secret in your [InfluxDB configuration file](/enterprise_influxdb/v1.9/administration/configure/config-data-nodes/#shared-secret--). + The longer the secret string, the more secure it is: + + ```toml + [http] + shared-secret = "my super secret pass phrase" + ``` + + Alternatively, to avoid keeping your secret phrase as plain text in your InfluxDB configuration file, + set the value with the `INFLUXDB_HTTP_SHARED_SECRET` environment variable. + +2. **Generate your JWT token**. + + Use an authentication service to generate a secure token + using your InfluxDB username, an expiration time, and your shared secret. + There are online tools, such as [https://jwt.io/](https://jwt.io/), that will do this for you. + + The payload (or claims) of the token must be in the following format: + + ```json + { + "username": "myUserName", + "exp": 1516239022 + } + ``` + + - **username** - The name of your InfluxDB user. + - **exp** - The expiration time of the token in UNIX epoch time. + For increased security, keep token expiration periods short. + For testing, you can manually generate UNIX timestamps using [https://www.unixtimestamp.com/index.php](https://www.unixtimestamp.com/index.php). + + Encode the payload using your shared secret. + You can do this with either a JWT library in your own authentication server or by hand at [https://jwt.io/](https://jwt.io/). + + The generated token follows this format: `
..` + +3. **Include the token in HTTP requests**. + + Include your generated token as part of the `Authorization` header in HTTP requests: + + ``` + Authorization: Bearer + ``` + {{% note %}} +Only unexpired tokens will successfully authenticate. +Be sure your token has not expired. + {{% /note %}} + +##### Example query request with JWT authentication +```bash +curl -G "http://localhost:8086/query?db=demodb" \ + --data-urlencode "q=SHOW DATABASES" \ + --header "Authorization: Bearer
.." +``` + +## Authenticate Telegraf requests to InfluxDB + +Authenticating [Telegraf](/{{< latest "telegraf" >}}/) requests to an InfluxDB instance with +authentication enabled requires some additional steps. +In the Telegraf configuration file (`/etc/telegraf/telegraf.conf`), uncomment +and edit the `username` and `password` settings. + +```toml +############################################################################### +# OUTPUT PLUGINS # +############################################################################### + +# ... + +[[outputs.influxdb]] + # ... + username = "example-username" # Provide your username + password = "example-password" # Provide your password + +# ... +``` + +Restart Telegraf and you're all set! + +## Authorization + +Authorization in InfluxDB Enterprise refers to managing user permissions. +To enable authorization, first [enable authentication](#enable-authentication). + +This page shows examples of basic user and permission management using InfluxQL statements. +However, *only a subset of Enterprise permissions can be managed with InfluxQL.* +Consider using [Chronograf](/{{< latest "chronograf" >}}/administration/managing-influxdb-users/) +and/or the [Enterprise meta API](/enterprise_influxdb/v1.9/administration/manage/security/authentication_and_authorization-api/) +to manage InfluxDB Enterprise users and roles. + + +### User types and privileges + +InfluxDB Enterprise has the following kinds of users: + +- [Admin users](#admin-users) +- [Non-admin users](#non-admin-users) + +#### Admin users + +Admin users have the following permissions: + +| Permission | Description | Token | +|:--------------------------|---------------------------------------------------------|------------------------| +| View Admin | Permission to view or edit admin screens | `ViewAdmin` | +| View Chronograf | Permission to use Chronograf tools | `ViewChronograf` | +| Create Databases | Permission to create databases | `CreateDatabase` | +| Create Users & Roles | Permission to create users and roles | `CreateUserAndRole` | +| Add/Remove Nodes | Permission to add/remove nodes from a cluster | `AddRemoveNode` | +| Drop Databases | Permission to drop databases | `DropDatabase` | +| Drop Data | Permission to drop measurements and series | `DropData` | +| Read | Permission to read data | `ReadData` | +| Write | Permission to write data | `WriteData` | +| Rebalance | Permission to rebalance a cluster | `Rebalance` | +| Manage Shards | Permission to copy and delete shards | `ManageShard` | +| Manage Continuous Queries | Permission to create, show, and drop continuous queries | `ManageContnuousQuery` | +| Manage Queries | Permission to show and kill queries | `ManageQuery` | +| Manage Subscriptions | Permission to show, add, and drop subscriptions | `ManageSubscription` | +| Monitor | Permission to show stats and diagnostics | `Monitor` | +| Copy Shard | Permission to copy shards | `CopyShard` | + +{{% caption %}} +For more information about these commands, +see [Database management](/enterprise_influxdb/v1.9/query_language/manage-database/) and +[Continuous queries](/enterprise_influxdb/v1.9/query_language/continuous_queries/). +{{% /caption %}} + + + +#### Non-admin users + +When authentication is enabled +a new non-admin user has no access to any database +until they are specifically [granted privileges to a database](#grant-read-write-or-all-database-privileges-to-an-existing-user) +by an admin user. + +Non-admin users can [`SHOW`](/enterprise_influxdb/v1.9/query_language/explore-schema/#show-databases) +the databases for which they have `ReadData` or `WriteData` permissions. + +### User management commands + +User management commands apply to either +[admin users](#manage-admin-users), +[non-admin users](#manage-non-admin-users), +or [both](#manage-admin-and-non-admin-users). + +#### Manage admin users + +Create an admin user with: + +```sql +CREATE USER admin WITH PASSWORD '' WITH ALL PRIVILEGES +``` + +{{% note %}} +Repeating the exact `CREATE USER` statement is idempotent. +If any values change the database will return a duplicate user error. + +```sql +> CREATE USER todd WITH PASSWORD '123456' WITH ALL PRIVILEGES +> CREATE USER todd WITH PASSWORD '123456' WITH ALL PRIVILEGES +> CREATE USER todd WITH PASSWORD '123' WITH ALL PRIVILEGES +ERR: user already exists +> CREATE USER todd WITH PASSWORD '123456' +ERR: user already exists +> CREATE USER todd WITH PASSWORD '123456' WITH ALL PRIVILEGES +> +``` +{{% /note %}} + +##### `GRANT` administrative privileges to an existing user +```sql +GRANT ALL PRIVILEGES TO +``` + +##### `REVOKE` administrative privileges from an admin user +```sql +REVOKE ALL PRIVILEGES FROM +``` + +##### `SHOW` all existing users and their admin status +```sql +SHOW USERS +``` + +###### CLI Example +```sql +> SHOW USERS +user admin +todd false +paul true +hermione false +dobby false +``` + +#### Manage non-admin users + +##### `CREATE` a new non-admin user +```sql +CREATE USER WITH PASSWORD '' +``` + +###### CLI example +```js +> CREATE USER todd WITH PASSWORD 'influxdb41yf3' +> CREATE USER alice WITH PASSWORD 'wonder\'land' +> CREATE USER "rachel_smith" WITH PASSWORD 'asdf1234!' +> CREATE USER "monitoring-robot" WITH PASSWORD 'XXXXX' +> CREATE USER "$savyadmin" WITH PASSWORD 'm3tr1cL0v3r' +``` + +{{% note %}} +##### Important notes about providing user credentials +- The user value must be wrapped in double quotes if + it starts with a digit, is an InfluxQL keyword, contains a hyphen, + or includes any special characters (for example: `!@#$%^&*()-`). +- The password [string](/influxdb/v1.8/query_language/spec/#strings) must be wrapped in single quotes. + Do not include the single quotes when authenticating requests. + We recommend avoiding the single quote (`'`) and backslash (`\`) characters in passwords. + For passwords that include these characters, escape the special character with a backslash + (e.g. (`\'`) when creating the password and when submitting authentication requests. +- Repeating the exact `CREATE USER` statement is idempotent. + If any values change the database will return a duplicate user error. + +###### CLI example +```sql +> CREATE USER "todd" WITH PASSWORD '123456' +> CREATE USER "todd" WITH PASSWORD '123456' +> CREATE USER "todd" WITH PASSWORD '123' +ERR: user already exists +> CREATE USER "todd" WITH PASSWORD '123456' +> CREATE USER "todd" WITH PASSWORD '123456' WITH ALL PRIVILEGES +ERR: user already exists +> CREATE USER "todd" WITH PASSWORD '123456' +> +``` +{{% /note %}} + +##### `GRANT` `READ`, `WRITE` or `ALL` database privileges to an existing user + +```sql +GRANT [READ,WRITE,ALL] ON TO +``` + +CLI examples: + +`GRANT` `READ` access to `todd` on the `NOAA_water_database` database: + +```sql +> GRANT READ ON "NOAA_water_database" TO "todd" +``` + +`GRANT` `ALL` access to `todd` on the `NOAA_water_database` database: + +```sql +> GRANT ALL ON "NOAA_water_database" TO "todd" +``` + +##### `REVOKE` `READ`, `WRITE`, or `ALL` database privileges from an existing user + +``` +REVOKE [READ,WRITE,ALL] ON FROM +``` + +CLI examples: + +`REVOKE` `ALL` privileges from `todd` on the `NOAA_water_database` database: + +```sql +> REVOKE ALL ON "NOAA_water_database" FROM "todd" +``` + +`REVOKE` `WRITE` privileges from `todd` on the `NOAA_water_database` database: + +```sql +> REVOKE WRITE ON "NOAA_water_database" FROM "todd" +``` + +{{% note %}} +If a user with `ALL` privileges has `WRITE` privileges revoked, they are left with `READ` privileges, and vice versa. +{{% /note %}} + +##### `SHOW` a user's database privileges + +```sql +SHOW GRANTS FOR +``` + +CLI example: + +```sql +> SHOW GRANTS FOR "todd" +database privilege +NOAA_water_database WRITE +another_database_name READ +yet_another_database_name ALL PRIVILEGES +one_more_database_name NO PRIVILEGES +``` + +#### Manage admin and non-admin users + +##### Reset a user's password + +```sql +SET PASSWORD FOR = '' +``` + +CLI example: + +```sql +> SET PASSWORD FOR "todd" = 'password4todd' +``` + +{{% note %}} +The password [string](/influxdb/v1.8/query_language/spec/#strings) must be wrapped in single quotes. +Do not include the single quotes when authenticating requests. + +We recommend avoiding the single quote (`'`) and backslash (`\`) characters in passwords +For passwords that include these characters, escape the special character with a backslash (e.g. (`\'`) when creating the password and when submitting authentication requests. +{{% /note %}} + +##### `DROP` a user + +```sql +DROP USER +``` + +CLI example: + +```sql +> DROP USER "todd" +``` + +## Authentication and authorization HTTP errors + +Requests with no authentication credentials or incorrect credentials yield the `HTTP 401 Unauthorized` response. + +Requests by unauthorized users yield the `HTTP 403 Forbidden` response. diff --git a/content/enterprise_influxdb/v1.9/administration/configure-password-hashing.md b/content/enterprise_influxdb/v1.9/administration/manage/security/configure-password-hashing.md similarity index 96% rename from content/enterprise_influxdb/v1.9/administration/configure-password-hashing.md rename to content/enterprise_influxdb/v1.9/administration/manage/security/configure-password-hashing.md index 0c080d4df..5ea912534 100644 --- a/content/enterprise_influxdb/v1.9/administration/configure-password-hashing.md +++ b/content/enterprise_influxdb/v1.9/administration/manage/security/configure-password-hashing.md @@ -6,9 +6,11 @@ menu: enterprise_influxdb_1_9: name: Configure password hashing weight: 80 - parent: Administration + parent: Manage security related: - /enterprise_influxdb/v1.9/administration/configuration/ +aliases: + - /enterprise_influxdb/v1.9/administration/configure-password-hashing/ --- By default, InfluxDB Enterprise uses `bcrypt` for password hashing. diff --git a/content/enterprise_influxdb/v1.9/administration/ldap.md b/content/enterprise_influxdb/v1.9/administration/manage/security/ldap.md similarity index 96% rename from content/enterprise_influxdb/v1.9/administration/ldap.md rename to content/enterprise_influxdb/v1.9/administration/manage/security/ldap.md index 9ae9fb21b..29e976590 100644 --- a/content/enterprise_influxdb/v1.9/administration/ldap.md +++ b/content/enterprise_influxdb/v1.9/administration/manage/security/ldap.md @@ -6,7 +6,10 @@ menu: enterprise_influxdb_1_9: name: Configure LDAP authentication weight: 40 - parent: Administration + parent: Manage security +aliases: + - /enterprise_influxdb/v1.9/administration/ldap/ + --- Configure InfluxDB Enterprise to use LDAP (Lightweight Directory Access Protocol) to: @@ -39,7 +42,9 @@ Update the following settings in each data node configuration file (`/etc/influx 3. If you're enabling authentication on meta nodes, you must also include the following configurations: - `INFLUXDB_META_META_AUTH_ENABLED` environment variable, or `[http]` configuration setting `meta-auth-enabled`, is set to `true`. This value must be the same value as the meta node's `meta.auth-enabled` configuration. - - `INFLUXDB_META_META_INTERNAL_SHARED_SECRET`, or the corresponding `[meta]` configuration setting `meta-internal-shared-secret`, is set to `true`. + - `INFLUXDB_META_META_INTERNAL_SHARED_SECRET`, + or the corresponding `[meta]` configuration setting `meta-internal-shared-secret`, + is set a secret value. This value must be the same value as the meta node's `meta.internal-shared-secret`. ### Configure meta nodes diff --git a/content/enterprise_influxdb/v1.9/administration/subscription-management.md b/content/enterprise_influxdb/v1.9/administration/manage/subscription-management.md similarity index 98% rename from content/enterprise_influxdb/v1.9/administration/subscription-management.md rename to content/enterprise_influxdb/v1.9/administration/manage/subscription-management.md index 8f20e2df4..488cae1e4 100644 --- a/content/enterprise_influxdb/v1.9/administration/subscription-management.md +++ b/content/enterprise_influxdb/v1.9/administration/manage/subscription-management.md @@ -4,9 +4,11 @@ description: > Manage subscriptions, which copy all written data to a local or remote endpoint, in InfluxDB OSS. menu: enterprise_influxdb_1_9: - parent: Administration name: Manage subscriptions weight: 100 + parent: Manage +aliases: + - /enterprise_influxdb/v1.9/administration/subscription-management/ --- InfluxDB subscriptions are local or remote endpoints to which all data written to InfluxDB is copied. diff --git a/content/enterprise_influxdb/v1.9/administration/monitor/_index.md b/content/enterprise_influxdb/v1.9/administration/monitor/_index.md new file mode 100644 index 000000000..2c7635a7f --- /dev/null +++ b/content/enterprise_influxdb/v1.9/administration/monitor/_index.md @@ -0,0 +1,11 @@ +--- +title: Monitor +description: +menu: + enterprise_influxdb_1_9: + name: Monitor + weight: 12 + parent: Administration +--- + +{{< children >}} diff --git a/content/enterprise_influxdb/v1.9/administration/logs.md b/content/enterprise_influxdb/v1.9/administration/monitor/logs.md similarity index 98% rename from content/enterprise_influxdb/v1.9/administration/logs.md rename to content/enterprise_influxdb/v1.9/administration/monitor/logs.md index 1611e3353..05e6f25a4 100644 --- a/content/enterprise_influxdb/v1.9/administration/logs.md +++ b/content/enterprise_influxdb/v1.9/administration/monitor/logs.md @@ -6,7 +6,9 @@ menu: enterprise_influxdb_1_9: name: Log and trace weight: 90 - parent: Administration + parent: Monitor +aliases: + - /enterprise_influxdb/v1.9/administration/logs/ --- diff --git a/content/enterprise_influxdb/v1.9/administration/server_monitoring.md b/content/enterprise_influxdb/v1.9/administration/monitor/server_monitoring.md similarity index 98% rename from content/enterprise_influxdb/v1.9/administration/server_monitoring.md rename to content/enterprise_influxdb/v1.9/administration/monitor/server_monitoring.md index 14bcec62d..6e01618b5 100644 --- a/content/enterprise_influxdb/v1.9/administration/server_monitoring.md +++ b/content/enterprise_influxdb/v1.9/administration/monitor/server_monitoring.md @@ -4,11 +4,12 @@ description: Troubleshoot and monitor InfluxDB OSS. aliases: - /enterprise_influxdb/v1.9/administration/statistics/ - /enterprise_influxdb/v1.9/troubleshooting/statistics/ + - /enterprise_influxdb/v1.9/administration/server-monitoring/ menu: enterprise_influxdb_1_9: name: Monitor InfluxDB weight: 80 - parent: Administration + parent: Monitor --- **On this page** diff --git a/content/enterprise_influxdb/v1.9/concepts/glossary.md b/content/enterprise_influxdb/v1.9/concepts/glossary.md index 48ee1de0a..f9a7d40c5 100644 --- a/content/enterprise_influxdb/v1.9/concepts/glossary.md +++ b/content/enterprise_influxdb/v1.9/concepts/glossary.md @@ -162,6 +162,9 @@ See [InfluxQL Functions](/enterprise_influxdb/v1.9/query_language/functions/) fo Related entries: [aggregation](#aggregation), [selector](#selector), [transformation](#transformation) + ## identifier Tokens that refer to continuous query names, database names, field keys, @@ -195,6 +198,9 @@ The metastore contains the user information, databases, retention policies, shar Related entries: [database](#database), [retention policy](#retention-policy-rp), [user](#user) + ## node An independent `influxd` process. @@ -251,6 +257,9 @@ For more information, see [Retention policy management](/enterprise_influxdb/v1. Related entries: [duration](#duration), [measurement](#measurement), [replication factor](#replication-factor), [series](#series), [shard duration](#shard-duration), [tag set](#tag-set) + ## schema How the data are organized in InfluxDB. @@ -423,8 +432,9 @@ The purpose-built data storage format for InfluxDB. TSM allows for greater compa ## user -There are two kinds of users in InfluxDB: +There are three kinds of users in InfluxDB Enterprise: +* *Global admin users* have all permissions. * *Admin users* have `READ` and `WRITE` access to all databases and full access to administrative queries and user management commands. * *Non-admin users* have `READ`, `WRITE`, or `ALL` (both `READ` and `WRITE`) access per database. diff --git a/content/enterprise_influxdb/v1.9/features/users.md b/content/enterprise_influxdb/v1.9/features/users.md index 587f4470b..38dae27d6 100644 --- a/content/enterprise_influxdb/v1.9/features/users.md +++ b/content/enterprise_influxdb/v1.9/features/users.md @@ -9,38 +9,15 @@ menu: parent: Enterprise features --- -InfluxDB Enterprise users have functions that are either specific to the web -console or specific to the cluster: + -``` -Users Cluster Permissions +## Users -Penelope - O - \|/ - | ----------------------> Dev Account --------> Manage Queries - / \ --------> Monitor - --------> Add/Remove Nodes -Jim - O - \|/ - | ----------------------> Marketing Account ---> View Admin - / \ ---> Graph Role ---> Read - ---> View Chronograf -``` - -## Cluster user information - -In the cluster, individual users are assigned to an account. -Cluster accounts have permissions and roles. - -In the diagram above, Penelope is assigned to the Dev Account and -Jim is assigned to the Marketing Account. -The Dev Account includes the permissions to manage queries, monitor the -cluster, and add/remove nodes from the cluster. -The Marketing Account includes the permission to view and edit the admin screens -as well as the Graph Role which contains the permissions to read data and -view Chronograf. +Users have permissions and roles. ### Roles @@ -67,131 +44,88 @@ permissions to: InfluxDB Enterprise clusters have 16 permissions: -#### View Admin - -Permission to view or edit admin screens. - -#### View Chronograf - -Permission to use Chronograf tools. - -#### Create Databases - -Permission to create databases. - -#### Create Users & Roles - -Permission to create users and roles. - -#### Add/Remove nodes - -Permission to add/remove nodes from a cluster. - -#### Drop Databases - -Permission to drop databases. - -#### Drop Data - -Permission to drop measurements and series. - -#### Read - -Permission to read data. - -#### Write - -Permission to write data. - -#### Rebalance - -Permission to rebalance a cluster. - -#### Manage Shards - -Permission to copy and delete shards. - -#### Manage continuous queries - -Permission to create, show, and drop continuous queries. - -#### Manage Queries - -Permission to show and kill queries. - -#### Manage Subscriptions - -Permission to show, add, and drop subscriptions. - -#### Monitor - -Permission to show stats and diagnostics. - -#### Copy Shard - -Permission to copy shards. +| Permission | Description | +|:--------------------------|---------------------------------------------------------| +| View Admin | Permission to view or edit admin screens | +| View Chronograf | Permission to use Chronograf tools | +| Create Databases | Permission to create databases | +| Create Users & Roles | Permission to create users and roles | +| Add/Remove Nodes | Permission to add/remove nodes from a cluster | +| Drop Databases | Permission to drop databases | +| Drop Data | Permission to drop measurements and series | +| Read | Permission to read data | +| Write | Permission to write data | +| Rebalance | Permission to rebalance a cluster | +| Manage Shards | Permission to copy and delete shards | +| Manage Continuous Queries | Permission to create, show, and drop continuous queries | +| Manage Queries | Permission to show and kill queries | +| Manage Subscriptions | Permission to show, add, and drop subscriptions | +| Monitor | Permission to show stats and diagnostics | +| Copy Shard | Permission to copy shards | ### Permission to Statement -The following table describes permissions required to execute the associated database statement. It also describes whether these permissions apply just to InfluxDB (Database) or InfluxDB Enterprise (Cluster). +The following table describes permissions required to execute the associated database statement. + -|Permission|Statement| -|---|---| -|CreateDatabasePermission|AlterRetentionPolicyStatement, CreateDatabaseStatement, CreateRetentionPolicyStatement, ShowRetentionPoliciesStatement| -|ManageContinuousQueryPermission|CreateContinuousQueryStatement, DropContinuousQueryStatement, ShowContinuousQueriesStatement| -|ManageSubscriptionPermission|CreateSubscriptionStatement, DropSubscriptionStatement, ShowSubscriptionsStatement| -|CreateUserAndRolePermission|CreateUserStatement, DropUserStatement, GrantAdminStatement, GrantStatement, RevokeAdminStatement, RevokeStatement, SetPasswordUserStatement, ShowGrantsForUserStatement, ShowUsersStatement| -|DropDataPermission|DeleteSeriesStatement, DeleteStatement, DropMeasurementStatement, DropSeriesStatement| -|DropDatabasePermission|DropDatabaseStatement, DropRetentionPolicyStatement| -|ManageShardPermission|DropShardStatement,ShowShardGroupsStatement, ShowShardsStatement| -|ManageQueryPermission|KillQueryStatement, ShowQueriesStatement| -|MonitorPermission|ShowDiagnosticsStatement, ShowStatsStatement| -|ReadDataPermission|ShowFieldKeysStatement, ShowMeasurementsStatement, ShowSeriesStatement, ShowTagKeysStatement, ShowTagValuesStatement, ShowRetentionPoliciesStatement| -|NoPermissions|ShowDatabasesStatement| -|Determined by type of select statement|SelectStatement| +| Permission | Statement | +|----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| CreateDatabasePermission | AlterRetentionPolicyStatement, CreateDatabaseStatement, CreateRetentionPolicyStatement, ShowRetentionPoliciesStatement | +| ManageContinuousQueryPermission | CreateContinuousQueryStatement, DropContinuousQueryStatement, ShowContinuousQueriesStatement | +| ManageSubscriptionPermission | CreateSubscriptionStatement, DropSubscriptionStatement, ShowSubscriptionsStatement | +| CreateUserAndRolePermission | CreateUserStatement, DropUserStatement, GrantAdminStatement, GrantStatement, RevokeAdminStatement, RevokeStatement, SetPasswordUserStatement, ShowGrantsForUserStatement, ShowUsersStatement | +| DropDataPermission | DeleteSeriesStatement, DeleteStatement, DropMeasurementStatement, DropSeriesStatement | +| DropDatabasePermission | DropDatabaseStatement, DropRetentionPolicyStatement | +| ManageShardPermission | DropShardStatement,ShowShardGroupsStatement, ShowShardsStatement | +| ManageQueryPermission | KillQueryStatement, ShowQueriesStatement | +| MonitorPermission | ShowDiagnosticsStatement, ShowStatsStatement | +| ReadDataPermission | ShowFieldKeysStatement, ShowMeasurementsStatement, ShowSeriesStatement, ShowTagKeysStatement, ShowTagValuesStatement, ShowRetentionPoliciesStatement | +| NoPermissions | ShowDatabasesStatement | +| Determined by type of select statement | SelectStatement | ### Statement to Permission -The following table describes database statements and the permissions required to execute them. It also describes whether these permissions apply just to InfluxDB (Database) or InfluxDB Enterprise (Cluster). +The following table describes database statements and the permissions required to execute them. +It also describes whether these permissions apply the the database or cluster level. -|Statment|Permissions|Scope| -|---|---|---| -|AlterRetentionPolicyStatement|CreateDatabasePermission|Database| -|CreateContinuousQueryStatement|ManageContinuousQueryPermission|Database| -|CreateDatabaseStatement|CreateDatabasePermission|Cluster| -|CreateRetentionPolicyStatement|CreateDatabasePermission|Database| -|CreateSubscriptionStatement|ManageSubscriptionPermission|Database| -|CreateUserStatement|CreateUserAndRolePermission|Database| -|DeleteSeriesStatement|DropDataPermission|Database| -|DeleteStatement|DropDataPermission|Database| -|DropContinuousQueryStatement|ManageContinuousQueryPermission|Database| -|DropDatabaseStatement|DropDatabasePermission|Cluster| -|DropMeasurementStatement|DropDataPermission|Database| -|DropRetentionPolicyStatement|DropDatabasePermission|Database| -|DropSeriesStatement|DropDataPermission|Database| -|DropShardStatement|ManageShardPermission|Cluster| -|DropSubscriptionStatement|ManageSubscriptionPermission|Database| -|DropUserStatement|CreateUserAndRolePermission|Database| -|GrantAdminStatement|CreateUserAndRolePermission|Database| -|GrantStatement|CreateUserAndRolePermission|Database| -|KillQueryStatement|ManageQueryPermission|Database| -|RevokeAdminStatement|CreateUserAndRolePermission|Database| -|RevokeStatement|CreateUserAndRolePermission|Database| -|SelectStatement|Determined by type of select statement|n/a| -|SetPasswordUserStatement|CreateUserAndRolePermission|Database| -|ShowContinuousQueriesStatement|ManageContinuousQueryPermission|Database| -|ShowDatabasesStatement|NoPermissions|Cluster|The user's grants determine which databases are returned in the results.| -|ShowDiagnosticsStatement|MonitorPermission|Database| -|ShowFieldKeysStatement|ReadDataPermission|Database| -|ShowGrantsForUserStatement|CreateUserAndRolePermission|Database| -|ShowMeasurementsStatement|ReadDataPermission|Database| -|ShowQueriesStatement|ManageQueryPermission|Database| -|ShowRetentionPoliciesStatement|CreateDatabasePermission|Database| -|ShowSeriesStatement|ReadDataPermission|Database| -|ShowShardGroupsStatement|ManageShardPermission|Cluster| -|ShowShardsStatement|ManageShardPermission|Cluster| -|ShowStatsStatement|MonitorPermission|Database| -|ShowSubscriptionsStatement|ManageSubscriptionPermission|Database| -|ShowTagKeysStatement|ReadDataPermission|Database| -|ShowTagValuesStatement|ReadDataPermission|Database| -|ShowUsersStatement|CreateUserAndRolePermission|Database| +| Statement | Permissions | Scope | | +|--------------------------------|----------------------------------------|----------|--------------------------------------------------------------------------| +| AlterRetentionPolicyStatement | CreateDatabasePermission | Database | | +| CreateContinuousQueryStatement | ManageContinuousQueryPermission | Database | | +| CreateDatabaseStatement | CreateDatabasePermission | Cluster | | +| CreateRetentionPolicyStatement | CreateDatabasePermission | Database | | +| CreateSubscriptionStatement | ManageSubscriptionPermission | Database | | +| CreateUserStatement | CreateUserAndRolePermission | Database | | +| DeleteSeriesStatement | DropDataPermission | Database | | +| DeleteStatement | DropDataPermission | Database | | +| DropContinuousQueryStatement | ManageContinuousQueryPermission | Database | | +| DropDatabaseStatement | DropDatabasePermission | Cluster | | +| DropMeasurementStatement | DropDataPermission | Database | | +| DropRetentionPolicyStatement | DropDatabasePermission | Database | | +| DropSeriesStatement | DropDataPermission | Database | | +| DropShardStatement | ManageShardPermission | Cluster | | +| DropSubscriptionStatement | ManageSubscriptionPermission | Database | | +| DropUserStatement | CreateUserAndRolePermission | Database | | +| GrantAdminStatement | CreateUserAndRolePermission | Database | | +| GrantStatement | CreateUserAndRolePermission | Database | | +| KillQueryStatement | ManageQueryPermission | Database | | +| RevokeAdminStatement | CreateUserAndRolePermission | Database | | +| RevokeStatement | CreateUserAndRolePermission | Database | | +| SelectStatement | Determined by type of select statement | n/a | | +| SetPasswordUserStatement | CreateUserAndRolePermission | Database | | +| ShowContinuousQueriesStatement | ManageContinuousQueryPermission | Database | | +| ShowDatabasesStatement | NoPermissions | Cluster | The user's grants determine which databases are returned in the results. | +| ShowDiagnosticsStatement | MonitorPermission | Database | | +| ShowFieldKeysStatement | ReadDataPermission | Database | | +| ShowGrantsForUserStatement | CreateUserAndRolePermission | Database | | +| ShowMeasurementsStatement | ReadDataPermission | Database | | +| ShowQueriesStatement | ManageQueryPermission | Database | | +| ShowRetentionPoliciesStatement | CreateDatabasePermission | Database | | +| ShowSeriesStatement | ReadDataPermission | Database | | +| ShowShardGroupsStatement | ManageShardPermission | Cluster | | +| ShowShardsStatement | ManageShardPermission | Cluster | | +| ShowStatsStatement | MonitorPermission | Database | | +| ShowSubscriptionsStatement | ManageSubscriptionPermission | Database | | +| ShowTagKeysStatement | ReadDataPermission | Database | | +| ShowTagValuesStatement | ReadDataPermission | Database | | +| ShowUsersStatement | CreateUserAndRolePermission | Database | | diff --git a/content/enterprise_influxdb/v1.9/guides/fine-grained-authorization.md b/content/enterprise_influxdb/v1.9/guides/fine-grained-authorization.md index 35c4032e3..4f08ed03b 100644 --- a/content/enterprise_influxdb/v1.9/guides/fine-grained-authorization.md +++ b/content/enterprise_influxdb/v1.9/guides/fine-grained-authorization.md @@ -9,6 +9,9 @@ menu: name: Use fine-grained authorization weight: 10 parent: Guides +related: + - /enterprise_influxdb/v1.9/administration/authentication_and_authorization/ + - /{{< latest "chronograf" >}}/administration/managing-influxdb-users/ --- Use fine-grained authorization (FGA) in InfluxDB Enterprise to control user access at the database, measurement, and series levels.