From aa3c2023baf69260214b91e4414998d699593d90 Mon Sep 17 00:00:00 2001 From: pierwill <19642016+pierwill@users.noreply.github.com> Date: Tue, 11 Jan 2022 16:07:59 -0600 Subject: [PATCH] Expand and re-organize InfluxDB Enterprise authn and authz docs (#3330) * Edit InfluxDB Enterprise features page * Add password change API example * Rename Enterprise Users doc to "User management and security" * Create "Configure security" section * Edit FGA introduction * Link manage and configure sections * Add shortcode for authn before authz warning * Edit "Next steps" after installation to include security * Apply suggestions from code review * Add --location-trusted in curl examples Closes #3080 Closes #3454 Closes #3472 Co-authored-by: kelseiv <47797004+kelseiv@users.noreply.github.com> --- .../v1.9/administration/configure/ports.md | 2 +- .../configure/security/_index.md | 16 + .../configure/security/authentication.md | 114 ++++ .../security/configure-password-hashing.md | 5 +- .../configure/security}/enable_tls.md | 10 +- .../{manage => configure}/security/ldap.md | 7 +- .../manage/clusters/rebalance.md | 4 +- .../administration/manage/security/_index.md | 60 -- .../authentication_and_authorization.md | 541 ------------------ .../manage/users-and-permissions/_index.md | 18 + .../authorization-api.md} | 128 ++--- .../authorization-influxql.md | 255 +++++++++ .../fine-grained-authorization.md | 29 +- .../introduction-to-auth.md | 84 +++ .../users-and-permissions/permissions.md} | 77 ++- .../v1.9/administration/monitor/logs.md | 2 +- .../v1.9/features/_index.md | 69 ++- .../v1.9/features/clustering-features.md | 8 + .../v1.9/guides/authenticate.md | 191 +++++++ .../installation/data_node_installation.md | 8 +- .../installation/meta_node_installation.md | 5 +- .../v1.9/query_language/functions.md | 2 +- .../v1.9/tools/api_client_libraries.md | 2 +- .../enterprise-warning-authn-b4-authz.md | 20 + 24 files changed, 908 insertions(+), 749 deletions(-) create mode 100644 content/enterprise_influxdb/v1.9/administration/configure/security/_index.md create mode 100644 content/enterprise_influxdb/v1.9/administration/configure/security/authentication.md rename content/enterprise_influxdb/v1.9/administration/{manage => configure}/security/configure-password-hashing.md (96%) rename content/enterprise_influxdb/v1.9/{guides => administration/configure/security}/enable_tls.md (98%) rename content/enterprise_influxdb/v1.9/administration/{manage => configure}/security/ldap.md (98%) delete mode 100644 content/enterprise_influxdb/v1.9/administration/manage/security/_index.md delete mode 100644 content/enterprise_influxdb/v1.9/administration/manage/security/authentication_and_authorization.md create mode 100644 content/enterprise_influxdb/v1.9/administration/manage/users-and-permissions/_index.md rename content/enterprise_influxdb/v1.9/administration/manage/{security/authentication_and_authorization-api.md => users-and-permissions/authorization-api.md} (79%) create mode 100644 content/enterprise_influxdb/v1.9/administration/manage/users-and-permissions/authorization-influxql.md rename content/enterprise_influxdb/v1.9/{guides => administration/manage/users-and-permissions}/fine-grained-authorization.md (96%) create mode 100644 content/enterprise_influxdb/v1.9/administration/manage/users-and-permissions/introduction-to-auth.md rename content/enterprise_influxdb/v1.9/{features/users.md => administration/manage/users-and-permissions/permissions.md} (86%) create mode 100644 content/enterprise_influxdb/v1.9/guides/authenticate.md create mode 100644 layouts/shortcodes/enterprise-warning-authn-b4-authz.md diff --git a/content/enterprise_influxdb/v1.9/administration/configure/ports.md b/content/enterprise_influxdb/v1.9/administration/configure/ports.md index 225af997a..cb44e2428 100644 --- a/content/enterprise_influxdb/v1.9/administration/configure/ports.md +++ b/content/enterprise_influxdb/v1.9/administration/configure/ports.md @@ -64,7 +64,7 @@ This port should not be exposed outside the cluster. ### 2003 The default port that runs the Graphite service. -[Enable and configure this port](/enterprise_influxdb/v1.9/administration/config#bind-address-2003) +[Enable and configure this port](/enterprise_influxdb/v1.9/administration/config-data-nodes/#bind-address-2003) in the configuration file. **Resources** [Graphite README](https://github.com/influxdata/influxdb/tree/1.8/services/graphite/README.md) diff --git a/content/enterprise_influxdb/v1.9/administration/configure/security/_index.md b/content/enterprise_influxdb/v1.9/administration/configure/security/_index.md new file mode 100644 index 000000000..993d1c88c --- /dev/null +++ b/content/enterprise_influxdb/v1.9/administration/configure/security/_index.md @@ -0,0 +1,16 @@ +--- +title: Configure security +description: Configure security features in InfluxDB Enterprise. +menu: + enterprise_influxdb_1_9: + name: Configure security + weight: 40 + parent: Configure +aliases: + - /enterprise_influxdb/v1.9/administration/security/ +--- + +_For user and permission management (authorization), +see [Manage users and permissions](/enterprise_influxdb/v1.9/administration/manage/users-and-permissions/)._ + +{{< children >}} diff --git a/content/enterprise_influxdb/v1.9/administration/configure/security/authentication.md b/content/enterprise_influxdb/v1.9/administration/configure/security/authentication.md new file mode 100644 index 000000000..7cef96fcd --- /dev/null +++ b/content/enterprise_influxdb/v1.9/administration/configure/security/authentication.md @@ -0,0 +1,114 @@ +--- +title: Configure authentication +description: > + Enable authentication to require credentials for a cluster. +menu: + enterprise_influxdb_1_9: + parent: Configure security + name: Configure authentication +weight: 10 +--- + +To configure authentication, do one of the following: + +- [Enable authentication](#enable-authentication) +- [Configure authentication using JWT tokens](#configure-authentication-using-jwt-tokens) ([InfluxDB HTTP API](/enterprise_influxdb/v1.9/tools/api/) only) + +## Enable authentication + +Authentication is disabled by default in InfluxDB and InfluxDB Enterprise. +After [installing the data nodes](/enterprise_influxdb/v1.9/introduction/install-and-deploy/installation/data_node_installation/), +enable authentication to control access to your cluster. + +To enable authentication in a cluster, do the following: + +1. Set `auth-enabled` to `true` in the `[http]` section of the configuration files + for all meta **and** data nodes: + ```toml + [http] + # ... + auth-enabled = true + ``` +1. Next, create an admin user (if you haven't already). + Using the [`influx` CLI](/enterprise_influxdb/v1.9/tools/influx-cli/), + run the following command: + ``` + CREATE USER admin WITH PASSWORD 'mypassword' WITH ALL PRIVILEGES + ``` +1. Restart InfluxDB Enterprise. + Once restarted, InfluxDB Enterprise checks user credentials on every request + and only processes requests with valid credentials. + +## Configure authentication using JWT tokens + +For a more secure alternative to using passwords, include JWT tokens in requests to the InfluxDB 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 (no JWT authentication). + Add a custom shared secret in your [InfluxDB configuration file](/enterprise_influxdb/v1.9/administration/configure/config-data-nodes/#shared-secret--) + for each meta and data node. + Longer strings are more secure: + + ```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 (for example, in Linux: `export INFLUXDB_HTTP_SHARED_SECRET=MYSUPERSECRETPASSPHRASE`). + +2. **Generate your JWT token**. + + Use an authentication service (such as, [https://jwt.io/](https://jwt.io/)) + to generate a secure token using your InfluxDB username, an expiration time, and your shared secret. + + The payload (or claims) of the token must be in the following format: + + ```json + { + "username": "myUserName", + "exp": 1516239022 + } + ``` + + - **username** - InfluxDB username. + - **exp** - Token expiration in UNIX [epoch time](/enterprise_influxdb/v1.9/query_language/explore-data/#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). + + To encode the payload using your shared secret, use a JWT library in your own authentication server or encode by hand at [https://jwt.io/](https://jwt.io/). + +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. +Verify 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
.." +``` + +## 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. + +## Next steps + +After configuring authentication, +you can [manage users and permissions](/enterprise_influxdb/v1.9/administration/manage/users-and-permissions/) +as necessary. + +{{% enterprise-warning-authn-b4-authz %}} diff --git a/content/enterprise_influxdb/v1.9/administration/manage/security/configure-password-hashing.md b/content/enterprise_influxdb/v1.9/administration/configure/security/configure-password-hashing.md similarity index 96% rename from content/enterprise_influxdb/v1.9/administration/manage/security/configure-password-hashing.md rename to content/enterprise_influxdb/v1.9/administration/configure/security/configure-password-hashing.md index 4e92f9047..2e27a86a1 100644 --- a/content/enterprise_influxdb/v1.9/administration/manage/security/configure-password-hashing.md +++ b/content/enterprise_influxdb/v1.9/administration/configure/security/configure-password-hashing.md @@ -5,12 +5,13 @@ description: > menu: enterprise_influxdb_1_9: name: Configure password hashing - parent: Manage security -weight: 44 + parent: Configure security +weight: 40 related: - /enterprise_influxdb/v1.9/administration/configuration/ aliases: - /enterprise_influxdb/v1.9/administration/configure-password-hashing/ + - /enterprise_influxdb/v1.9/administration/manage/configure-password-hashing/ --- By default, InfluxDB Enterprise uses `bcrypt` for password hashing. diff --git a/content/enterprise_influxdb/v1.9/guides/enable_tls.md b/content/enterprise_influxdb/v1.9/administration/configure/security/enable_tls.md similarity index 98% rename from content/enterprise_influxdb/v1.9/guides/enable_tls.md rename to content/enterprise_influxdb/v1.9/administration/configure/security/enable_tls.md index c1f4c8733..783f36067 100644 --- a/content/enterprise_influxdb/v1.9/guides/enable_tls.md +++ b/content/enterprise_influxdb/v1.9/administration/configure/security/enable_tls.md @@ -1,14 +1,16 @@ --- -title: Enable HTTPS over TLS for InfluxDB Enterprise +title: Configure HTTPS over TLS description: > Enabling HTTPS over TLS encrypts the communication between clients and the InfluxDB Enterprise server, and between nodes in the cluster. menu: enterprise_influxdb_1_9: - name: Enable TLS - weight: 100 - parent: Guides + name: Configure TLS for cluster + parent: Configure security +weight: 20 aliases: - /enterprise_influxdb/v1.9/guides/https_setup/ + - /enterprise_influxdb/v1.9/guides/enable_tls/ + - /enterprise_influxdb/v1.9/guides/enable-tls/ --- Enabling HTTPS over TLS encrypts the communication between clients and the InfluxDB Enterprise server, and between nodes in the cluster. diff --git a/content/enterprise_influxdb/v1.9/administration/manage/security/ldap.md b/content/enterprise_influxdb/v1.9/administration/configure/security/ldap.md similarity index 98% rename from content/enterprise_influxdb/v1.9/administration/manage/security/ldap.md rename to content/enterprise_influxdb/v1.9/administration/configure/security/ldap.md index f8f49dfa2..abab1bab6 100644 --- a/content/enterprise_influxdb/v1.9/administration/manage/security/ldap.md +++ b/content/enterprise_influxdb/v1.9/administration/configure/security/ldap.md @@ -1,14 +1,15 @@ --- -title: Configure LDAP authentication in InfluxDB Enterprise +title: Configure LDAP authentication description: > Configure LDAP authentication in InfluxDB Enterprise and test LDAP connectivity. menu: enterprise_influxdb_1_9: name: Configure LDAP authentication - parent: Manage security -weight: 43 + parent: Configure security +weight: 30 aliases: - /enterprise_influxdb/v1.9/administration/ldap/ + - /enterprise_influxdb/v1.9/administration/manage/security/ldap/ --- Configure InfluxDB Enterprise to use LDAP (Lightweight Directory Access Protocol) to: diff --git a/content/enterprise_influxdb/v1.9/administration/manage/clusters/rebalance.md b/content/enterprise_influxdb/v1.9/administration/manage/clusters/rebalance.md index afa30c5db..addd5b15d 100644 --- a/content/enterprise_influxdb/v1.9/administration/manage/clusters/rebalance.md +++ b/content/enterprise_influxdb/v1.9/administration/manage/clusters/rebalance.md @@ -2,8 +2,8 @@ title: Rebalance InfluxDB Enterprise clusters description: Manually rebalance an InfluxDB Enterprise cluster. aliases: - - /enterprise/v1.8/guides/rebalance/ - - /enterprise/v1.9/guides/rebalance/ + - /enterprise_influxdb/v1.8/guides/rebalance/ + - /enterprise_influxdb/v1.9/guides/rebalance/ menu: enterprise_influxdb_1_9: name: Rebalance clusters diff --git a/content/enterprise_influxdb/v1.9/administration/manage/security/_index.md b/content/enterprise_influxdb/v1.9/administration/manage/security/_index.md deleted file mode 100644 index 7ce34a05b..000000000 --- a/content/enterprise_influxdb/v1.9/administration/manage/security/_index.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Manage security -description: Configuration, security, and logging in InfluxDB enterprise. -menu: - enterprise_influxdb_1_9: - name: Manage security - weight: 40 - parent: Manage -aliases: - - /enterprise_influxdb/v1.9/administration/security/ ---- - - - -{{< children >}} 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 deleted file mode 100644 index cc8fbfeff..000000000 --- a/content/enterprise_influxdb/v1.9/administration/manage/security/authentication_and_authorization.md +++ /dev/null @@ -1,541 +0,0 @@ ---- -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 - parent: Manage security -weight: 41 -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/manage/users-and-permissions/_index.md b/content/enterprise_influxdb/v1.9/administration/manage/users-and-permissions/_index.md new file mode 100644 index 000000000..d92c79172 --- /dev/null +++ b/content/enterprise_influxdb/v1.9/administration/manage/users-and-permissions/_index.md @@ -0,0 +1,18 @@ +--- +title: Manage users and permissions +description: Manage authorization in InfluxDB Enterprise clusters with users, roles, and permissions. +menu: + enterprise_influxdb_1_9: + name: Manage users and permissions + weight: 40 + parent: Manage +aliases: + - /enterprise_influxdb/v1.9/administration/authentication_and_authorization/ +--- + +{{% enterprise-warning-authn-b4-authz %}} + +_For information about how to configure HTTPs over TLS, LDAP authentication, and password hashing, +see [Configure security](/enterprise_influxdb/v1.9/administration/configure/security/)._ + +{{< 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/users-and-permissions/authorization-api.md similarity index 79% rename from content/enterprise_influxdb/v1.9/administration/manage/security/authentication_and_authorization-api.md rename to content/enterprise_influxdb/v1.9/administration/manage/users-and-permissions/authorization-api.md index 412cda691..17fc913d0 100644 --- a/content/enterprise_influxdb/v1.9/administration/manage/security/authentication_and_authorization-api.md +++ b/content/enterprise_influxdb/v1.9/administration/manage/users-and-permissions/authorization-api.md @@ -1,80 +1,34 @@ --- -title: Manage users and privileges with the InfluxDB Enterprise Meta API +title: Manage authorization with the InfluxDB Enterprise Meta API description: > - Set up and manage authentication and authorization in InfluxDB Enterprise. + Manage users and permissions with the InfluxDB Enterprise Meta API. menu: enterprise_influxdb_1_9: - name: Manage security with Meta API - parent: Manage security -weight: 42 + name: Manage authorization with the API + parent: Manage users and permissions +weight: 41 +aliases: + - /enterprise_influxdb/v1.9/administration/manage/security/authentication_and_authorization-api/ + - /enterprise_influxdb/v1.9/administration/security/authentication_and_authorization-api/ --- +{{% enterprise-warning-authn-b4-authz %}} + - [Overview](#overview) - [API examples](#user-and-privilege-management-over-the-influxdb-enterprise-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. - +Use the InfluxDB Enterprise Meta API to manage authorization for a cluster. + -* `ViewAdmin` -* `ViewChronograf` -* `CreateDatabase` -* `CreateUserAndRole` -* `AddRemoveNode` -* `DropDatabase` -* `DropData` -* `ReadData` -* `WriteData` -* `Rebalance` -* `ManageShard` -* `ManageContinuousQuery` -* `ManageQuery` -* `ManageSubscription` -* `Monitor` -* `CopyShard` +For more information, see [Enterprise users and permissions](/enterprise_influxdb/v1.9/administration/manage/users-and-permissions/permissions/). -{{% 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 +### Example API requests **Users**: @@ -87,6 +41,7 @@ In addition, two tokens govern Kapacitor permissions: - [Remove permissions from a user](#remove-permissions-from-a-user) - [Remove a user](#remove-a-user) - [Verify user removal](#verify-user-removal) +- [Change a user's password](#change-a-users-password) **Roles**: @@ -111,7 +66,7 @@ Use the `/user` endpoint of the InfluxDB Enterprise Meta API to manage users. View a list of existing users. ``` -$ curl -u "admin:changeit" -s https://cluster_node_1:8091/user | python -m json.tool +$ curl --location-trusted -u "admin:changeit" -s https://cluster_node_1:8091/user | python -m json.tool { "users": [ { @@ -152,7 +107,7 @@ 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 +$ curl --location-trusted -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 @@ -196,7 +151,7 @@ $ curl -u "admin:changeit" -s -v -d '{"action":"create","user":{"name":"phantom2 ##### 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 +$ curl --location-trusted -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 @@ -238,7 +193,7 @@ $ curl -u "admin:changeit" -s -v -d '{"action":"create","user":{"name":"phantom" ##### Retrieve a user details document ``` -$ curl --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/user?name=phantom | python -m json.tool +$ curl --location-trusted --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/user?name=phantom | python -m json.tool { "users": [ { @@ -252,7 +207,7 @@ $ curl --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/user?name= ##### 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 +$ curl --location-trusted --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 @@ -292,7 +247,7 @@ $ curl --negotiate -u "admin:changeit" -s -v -d '{"action":"add-permissions","us ##### Verify user permissions ``` -$ curl --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/user?name=phantom | python -m json.tool +$ curl --location-trusted --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/user?name=phantom | python -m json.tool { "users": [ { @@ -312,7 +267,7 @@ $ curl --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/user?name= ##### 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 +$ curl --location-trusted --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 @@ -352,7 +307,7 @@ $ curl --negotiate -u "admin:changeit" -s -v -d '{"action":"remove-permissions", ##### Remove a user ``` -$ curl --negotiate -u "admin:changeit" -s -v -d '{"action":"delete","user":{"name":"phantom2"}}' https://cluster_node_1:8091/user +$ curl --location-trusted --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 @@ -392,10 +347,17 @@ $ curl --negotiate -u "admin:changeit" -s -v -d '{"action":"delete","user":{"nam ##### Verify user removal ``` -$ curl --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/user?name=phantom +$ curl --location-trusted --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/user?name=phantom {"error":"user not found"} ``` +##### Change a user's password + +``` +$ curl --location-trustedv -u "admin:changeit" -H "Content-Type: application/json" -d '{"action": "change-password", "user": {"name": "", "password": "newpassword"}}' localhost:8091/user +``` + + #### Roles The Influxd-Meta API provides an endpoint `/role` for managing roles. @@ -403,7 +365,7 @@ 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 +$ curl --location-trusted --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/role | python -m json.tool {} ``` @@ -413,7 +375,7 @@ 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 +$ curl --location-trusted --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 @@ -455,7 +417,7 @@ $ curl --negotiate -u "admin:changeit" -v -d '{"action":"create","role":{"name" Verify the role has been created. ``` -$ curl --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/role | python -m json.tool +$ curl --location-trusted --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/role | python -m json.tool { "roles": [ { @@ -473,7 +435,7 @@ $ curl --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/role | pyt 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 +curl --location-trusted --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/role?name=spectre | python -m json.tool { "roles": [ { @@ -487,7 +449,7 @@ curl --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/role?name=sp 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 +$ curl --location-trusted --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 @@ -529,7 +491,7 @@ $ curl --negotiate -u "admin:changeit" -s -v -d '{"action":"add-permissions","ro Verify permissions have been added. ``` -$ curl --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/role?name=spectre | python -m json.tool +$ curl --location-trusted --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/role?name=spectre | python -m json.tool { "roles": [ { @@ -548,7 +510,7 @@ $ curl --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/role?name= ##### 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 +$ curl --location-trusted --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 @@ -590,7 +552,7 @@ $ curl --negotiate -u "admin:changeit" -s -v -d '{"action":"add-users","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 +$ curl --location-trusted --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/role?name=spectre | python -m json.tool { "roles": [ { @@ -612,7 +574,7 @@ $ curl --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/role?name= ##### 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 +$ curl --location-trusted --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 @@ -653,7 +615,7 @@ $ curl --negotiate -u "admin:changeit" -s -v -d '{"action":"remove-users","role" ##### 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 +$ curl --location-trusted --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 @@ -694,7 +656,7 @@ $ curl --negotiate -u "admin:changeit" -s -v -d '{"action":"remove-permissions", ##### Delete a role ``` -$ curl --negotiate -u "admin:changeit" -s -v -d '{"action":"delete","role":{"name":"spectre"}}' https://cluster_node_1:8091/role +$ curl --location-trusted --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 @@ -735,7 +697,7 @@ $ curl --negotiate -u "admin:changeit" -s -v -d '{"action":"delete","role":{"nam ##### Verify role deletion ``` -$ curl --negotiate -u "admin:changeit" -s https://cluster_node_1:8091/role?name=spectre | python -m json.tool +$ curl --location-trusted --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/users-and-permissions/authorization-influxql.md b/content/enterprise_influxdb/v1.9/administration/manage/users-and-permissions/authorization-influxql.md new file mode 100644 index 000000000..59d697673 --- /dev/null +++ b/content/enterprise_influxdb/v1.9/administration/manage/users-and-permissions/authorization-influxql.md @@ -0,0 +1,255 @@ +--- +title: Manage authorization with InfluxQL +description: > + Manage users and permissions with InfluxQL. +menu: + enterprise_influxdb_1_9: + parent: Manage users and permissions +weight: 40 +related: + - /enterprise_influxdb/v1.9/administration/manage/security/authorization-api.md + - /{{< latest "chronograf" >}}/administration/managing-influxdb-users/ + - /enterprise_influxdb/v1.9/administration/manage/security/fine-grained-authorization/ +aliases: + - /enterprise_influxdb/v1.9/administration/manage/security/authentication_and_authorization-api/ +--- + +{{% enterprise-warning-authn-b4-authz %}} + +{{% note %}} +We recommend using [Chronograf](/{{< latest "chronograf" >}}/administration/managing-influxdb-users/) +and/or the [Enterprise meta API](/enterprise_influxdb/v1.9/administration/manage/users-and-permissions/authorization-api/) +to manage InfluxDB Enterprise users and roles. +{{% /note %}} + +{{% warn %}} +Outside of [creating users](/enterprise_influxdb/v1.9/query_language/spec/#create-user), +we recommend operators *do not* mix and match InfluxQL +with other authorization management methods (Chronograf and the API). +Doing so may lead to inconsistencies in user permissions. +{{% /warn %}} + +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.* +Using InfluxQL, you can perform the following actions: + +- Create new users and assign them either the admin role (or no role). +- grant `READ` and/or `WRITE` permissions to users. (`READ`, `WRITE`, `ALL`) +- `REVOKE` permissions from users. +- `GRANT` or `REVOKE` specific database access to individual users. + +However, InfluxDB Enterprise offers an [*expanded set of permissions*](/enterprise_influxdb/v1.9/administration/manage/users-and-permissions/permissions/#permissions). +You can use the Meta API and Chronograf to access and assign these more granular permissions to individual users. + +The [InfluxDB Enterprise meta API](/enterprise_influxdb/v1.9/administration/manage/users-and-permissions/authorization-api/) +provides the most comprehensive way to manage users, roles, permission +and other [fine grained authorization](/enterprise_influxdb/v1.9/administration/manage/users-and-permissions/fine-grained-authorization/) (FGA) capabilities. + +#### 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). + +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/). + +#### 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" +``` + diff --git a/content/enterprise_influxdb/v1.9/guides/fine-grained-authorization.md b/content/enterprise_influxdb/v1.9/administration/manage/users-and-permissions/fine-grained-authorization.md similarity index 96% rename from content/enterprise_influxdb/v1.9/guides/fine-grained-authorization.md rename to content/enterprise_influxdb/v1.9/administration/manage/users-and-permissions/fine-grained-authorization.md index efdc3eeab..1a5afde08 100644 --- a/content/enterprise_influxdb/v1.9/guides/fine-grained-authorization.md +++ b/content/enterprise_influxdb/v1.9/administration/manage/users-and-permissions/fine-grained-authorization.md @@ -1,26 +1,24 @@ --- -title: Use fine-grained authorization in InfluxDB Enterprise +title: Manage fine-grained authorization description: > Fine-grained authorization (FGA) in InfluxDB Enterprise controls user access at the database, measurement, and series levels. -alias: - -/docs/v1.5/administration/fga menu: enterprise_influxdb_1_9: - name: Use fine-grained authorization - weight: 10 - parent: Guides + parent: Manage users and permissions +weight: 44 +aliases: + - /docs/v1.5/administration/fga + - /enterprise_influxdb/v1.9/guides/fine-grained-authorization/ 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. +{{% enterprise-warning-authn-b4-authz %}} -{{% note %}} -**Note:** InfluxDB OSS controls access at the database level only. -{{% /note %}} +Use fine-grained authorization (FGA) to control user access at the database, measurement, and series levels. -You must have [admin permissions](/enterprise_influxdb/v1.9/administration/authentication_and_authorization/#admin-user-management) to set up FGA. +You must have [admin permissions](/enterprise_influxdb/v1.9/administration/manage/users-and-permissions/permissions/#admin) to set up FGA. {{% warn %}} #### FGA does not apply to Flux @@ -28,9 +26,14 @@ FGA does not restrict actions performed by Flux queries (both read and write). If using FGA, we recommend [disabling Flux](/enterprise_influxdb/v{{< current-version >}}/flux/installation/). {{% /warn %}} +{{% note %}} +FGA is only available in InfluxDB Enterprise. +InfluxDB OSS 1.x controls access at the database level only. +{{% /note %}} + ## Set up fine-grained authorization -1. [Enable authentication](/enterprise_influxdb/v1.9/administration/authentication_and_authorization/#set-up-authentication) in your InfluxDB configuration file. +1. [Enable authentication](/enterprise_influxdb/v1.9/administration/configure/security/authentication/) in your InfluxDB configuration file. 2. Create users through the InfluxDB query API. @@ -38,7 +41,7 @@ If using FGA, we recommend [disabling Flux](/enterprise_influxdb/v{{< current-ve CREATE USER username WITH PASSWORD 'password' ``` - For more information, see [User management commands](/enterprise_influxdb/v1.9/administration/authentication_and_authorization/#user-management-commands). + For more information, see [User management commands](/enterprise_influxdb/v1.9/administration/manage/users-and-permissions/authorization-influxql/#user-management-commands). 3. Ensure that you can access the **meta node** API (port 8091 by default). diff --git a/content/enterprise_influxdb/v1.9/administration/manage/users-and-permissions/introduction-to-auth.md b/content/enterprise_influxdb/v1.9/administration/manage/users-and-permissions/introduction-to-auth.md new file mode 100644 index 000000000..564d59548 --- /dev/null +++ b/content/enterprise_influxdb/v1.9/administration/manage/users-and-permissions/introduction-to-auth.md @@ -0,0 +1,84 @@ +--- +title: Introduction to authorization in InfluxDB Enterprise +description: > + Learn the basics of managing users and permissions in InfluxDB Enterprise. +menu: + enterprise_influxdb_1_9: + name: Introduction to authorization + parent: Manage users and permissions +weight: 30 +related: + - /enterprise_influxdb/v1.9/guides/fine-grained-authorization/ + - /{{< latest "chronograf" >}}/administration/managing-influxdb-users/ +--- + +Authorization in InfluxDB Enterprise refers to managing user permissions. +To secure and manage access to an InfluxDB Enterprise cluster, +first [configure authentication](/enterprise_influxdb/v1.9/administration/configure/security/authentication/). +You can then manage users and permissions as necessary. + +This page is meant to help new users choose the best method +for managing permissions in InfluxDB Enterprise. + +## Permissions in InfluxDB Enterprise + +InfluxDB Enterprise has an [expanded set of 16 permissions](/enterprise_influxdb/v1.9/administration/manage/users-and-permissions/permissions/#permissions). +These permissions allow for +controlling read and write access to data for all databases and for individual databases, +as well as permitting certain cluster-management actions like creating or deleting resources. + +InfluxDB 1.x OSS only supports database-level privileges: `READ` and `WRITE`. +A third permission, `ALL`, grants admin privileges. +These three permissions exist in InfluxDB Enterprise as well. +They can _only be granted by using InfluxQL_. + +## Manage user authorization + +Choose one of the following methods manage authorizations in InfluxDB Enterprise: + +- using [InfluxQL](#manage-read-and-write-privileges-with-influxql) + {{% note %}} +InfluxQL can can only grant `READ`, `WRITE`, and `ALL PRIVILEGES` privileges. +To use the full set of InfluxDB Enterprise [permissions](/enterprise_influxdb/v1.9/administration/manage/users-and-permissions/permissions/), +use [Chronograf](#manage-specific-privileges-with-chronograf) +or the [Meta API (recommended)](#influxdb-enterprise-meta-api). + {{% /note %}} +- using [Chronograf](#manage-enterprise-permissions-with-chronograf) +- using the [InfluxDB Enterprise meta API](#manage-enterprise-permissions-with-the-meta-api) (**Recommended**) + +### Manage read and write privileges with InfluxQL + +If you only need to manage basic `READ`, `WRITE`, and `ALL` privileges, +use InfluxQL to manage authorizations. +(For instance, if you upgraded from InfluxDB OSS 1.x +and do not need the more detailed authorization in InfluxDB Enterprise, continue to use InfluxQL.) + +{{% warn %}} +We recommend operators *do not* mix and match InfluxQL +with other authorization management methods (Chronograf and the API). +Doing so may lead to inconsistencies in user permissions. +{{% /warn %}} + +### Manage Enterprise permissions with Chronograf + +The Chronograf user interface can manage the +[full set of InfluxDB Enterprise permissions](/enterprise_influxdb/v1.9/administration/manage/users-and-permissions/permissions/#permissions). + +The permissions listed in Chronograf are global for the cluster, and available through the API. +Outside of [FGA](/enterprise_influxdb/v1.9/administration/manage/users-and-permissions/fine-grained-authorization), +the only database-level permissions available are the basic `READ` and `WRITE`. +These can only be managed using [InfluxQL](#manage-read-and-write-privileges-with-influxql). + +Chronograf can only set permissions globally, for all databases, within a cluster. +If you need to set permissions at the database level, use the [Meta API](#influxdb-enterprise-meta-api). + +See ["Manage InfluxDB users in Chronograf"](/chronograf/v1.9/administration/managing-influxdb-users/) +for instructions. + +### Manage Enterprise permissions with the Meta API + +The InfluxDB Enterprise API is the +recommended method for managing permissions. + +For more information on using the meta API, +see [here](/enterprise_influxdb/v1.9/administration/manage/users-and-permissions/authorization-api). diff --git a/content/enterprise_influxdb/v1.9/features/users.md b/content/enterprise_influxdb/v1.9/administration/manage/users-and-permissions/permissions.md similarity index 86% rename from content/enterprise_influxdb/v1.9/features/users.md rename to content/enterprise_influxdb/v1.9/administration/manage/users-and-permissions/permissions.md index 4d59f5758..3651e4b8f 100644 --- a/content/enterprise_influxdb/v1.9/features/users.md +++ b/content/enterprise_influxdb/v1.9/administration/manage/users-and-permissions/permissions.md @@ -1,19 +1,19 @@ --- -title: InfluxDB Enterprise users -description: Overview of users in InfluxDB Enterprise. -aliases: - - /enterprise/v1.8/features/users/ +title: Enterprise users and permissions reference +description: > + Detailed reference for users, roles, permissions, and permission-to-statement mappings. menu: enterprise_influxdb_1_9: - weight: 0 - parent: Enterprise features + parent: Manage users and permissions +weight: 100 +aliases: + - /enterprise_influxdb/v1.9/features/users/ --- - +{{% enterprise-warning-authn-b4-authz %}} + +- [Users](#users) +- [Permissions](#permissions) ## Users @@ -40,28 +40,45 @@ permissions to: * Manage Shards * Rebalance -### Permissions +## Permissions + +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 InfluxDB Enterprise clusters have 16 permissions: -| 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 | 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` | + +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. + ### Permission to Statement diff --git a/content/enterprise_influxdb/v1.9/administration/monitor/logs.md b/content/enterprise_influxdb/v1.9/administration/monitor/logs.md index a6bfa05f2..4c927b9e7 100644 --- a/content/enterprise_influxdb/v1.9/administration/monitor/logs.md +++ b/content/enterprise_influxdb/v1.9/administration/monitor/logs.md @@ -111,7 +111,7 @@ The service configuration file is `/etc/default/influx-enterprise`. ### Use logrotate -You can use [logrotate](http://manpages.ubuntu.com/manpages/cosmic/en/man8/logrotate.8.html) +You can use [logrotate](https://manpages.ubuntu.com/manpages/jammy/en/man8/logrotate.8.html) to rotate the log files generated by InfluxDB on systems where logs are written to flat files. If using the package install on a sysvinit system, the config file for logrotate is installed in `/etc/logrotate.d`. You can view the file [here](https://github.com/influxdb/influxdb/blob/master/scripts/logrotate). diff --git a/content/enterprise_influxdb/v1.9/features/_index.md b/content/enterprise_influxdb/v1.9/features/_index.md index 14c68de17..cd7d8abee 100644 --- a/content/enterprise_influxdb/v1.9/features/_index.md +++ b/content/enterprise_influxdb/v1.9/features/_index.md @@ -9,4 +9,71 @@ menu: weight: 60 --- -{{< children hlevel="h2" >}} +InfluxDB Enterprise has additional capabilities that enhance +[availability](#clustering), +[scalability](#clustering), and +[security](#security), +and provide [eventual consistency](#eventual-consistency). + +## Clustering + +InfluxDB Enterprise runs on a network of independent servers, a *cluster*, +to provide fault tolerance, availability, and horizontal scalability of the database. + +While many InfluxDB Enterprise features are available +when run with a single meta node and a single data node, this configuration does not take advantage of the clustering capablity +or ensure high availablity. + +Nodes can be added to an existing cluster to improve database performance for querying and writing data. +Certain configurations (e.g., 3 meta and 2 data node) provide high-availability assurances +while making certain tradeoffs in query peformance when compared to a single node. + +Further increasing the number of nodes can improve performance in both respects. +For example, a cluster with 4 data nodes and a [replication factor](https://docs.influxdata.com/enterprise_influxdb/v1.9/concepts/glossary/#replication-factor) +of 2 can support a higher volume of write traffic than a single node could. +It can also support a higher *query* workload, as the data is replicated +in two locations. Performance of the queries may be on par with a single +node in cases where the query can be answered directly by the node which +receives the query. + +For more information on clustering, see [Clustering in InfluxDB Enterprise](/enterprise_influxdb/v1.9/concepts/clustering/). + +## Security + +Enterprise authorization uses an expanded set of [*16 user permissions and roles*](/enterprise_influxdb/v1.9/features/users/). +(InfluxDB OSS only has `READ` and `WRITE` permissions.) +Administrators can give users permission to read and write to databases, +create and remove databases, rebalance a cluster, and manage particular resources. + +Organizations can automate managing permissions with the [InfluxDB Enterprise Meta API](/enterprise_influxdb/v1.9/administration/manage/security/authentication_and_authorization-api/). + +[Fine-grained authorization](/enterprise_influxdb/v1.9/guides/fine-grained-authorization/) +for particular data is also available. + +InfluxDB Enterprise can also use [LDAP for managing authentication](/enterprise_influxdb/v1.9/administration/manage/security/ldap/). + +For FIPS compliance, InfluxDB Enterprise password hashing alogrithms are configurable. + +{{% note %}} +Kapacitor OSS can also delegate its LDAP and security setup to InfluxDB Enterprise. +For details, see ["Set up InfluxDB Enterprise authorizations"](/{{< latest "kapacitor" >}}/administration/auth/influxdb-enterprise-auth/). +{{% /note %}} + +## Eventual consistency + +### Hinted handoff + +Hinted handoff (HH) is how InfluxDB Enterprise deals with data node outages while writes are happening. +HH is essentially a durable disk based queue. + +For more information, see ["Hinted handoff"](/enterprise_influxdb/v1.9/concepts/clustering/#hinted-handoff). + +### Anti-entropy + +Anti-entropy is an optional service to eliminate edge cases related to cluster consistency. + +For more information, see ["Use Anti-Entropy service in InfluxDB Enterprise"](/enterprise_influxdb/v1.9/administration/anti-entropy/). + +--- + +{{< children hlevel="h3" >}} diff --git a/content/enterprise_influxdb/v1.9/features/clustering-features.md b/content/enterprise_influxdb/v1.9/features/clustering-features.md index c24d45b17..714b41277 100644 --- a/content/enterprise_influxdb/v1.9/features/clustering-features.md +++ b/content/enterprise_influxdb/v1.9/features/clustering-features.md @@ -10,6 +10,14 @@ menu: parent: Enterprise features --- +{{% note %}} +_For an overview of InfluxDB Enterprise security features, +see ["InfluxDB Enterprise features - Security"](/enterprise_influxdb/v1.9/features/#security). +To secure your InfluxDB Enterprise cluster, see +["Configure security"](/enterprise_influxdb/v1.9/administration/configure/security/) +and ["Manage security"](/enterprise_influxdb/v1.9/administration/manage/security/)_. +{{% /note %}} + ## Entitlements A valid license key is required in order to start `influxd-meta` or `influxd`. diff --git a/content/enterprise_influxdb/v1.9/guides/authenticate.md b/content/enterprise_influxdb/v1.9/guides/authenticate.md new file mode 100644 index 000000000..49fad2a00 --- /dev/null +++ b/content/enterprise_influxdb/v1.9/guides/authenticate.md @@ -0,0 +1,191 @@ +--- +title: Authenticate requests to InfluxDB Enterprise +description: > + Calculate percentages using basic math operators available in InfluxQL or Flux. + This guide walks through use cases and examples of calculating percentages from two values in a single query. +menu: + enterprise_influxdb_1_9: + weight: 25 + parent: Guides + name: Authenticate requests +--- + +_To require valid credentials for cluster access, see ["Enable authentication"](/enterprise_influxdb/v1.9/administration/configure/security/authentication/)._ + +## 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! + diff --git a/content/enterprise_influxdb/v1.9/introduction/install-and-deploy/installation/data_node_installation.md b/content/enterprise_influxdb/v1.9/introduction/install-and-deploy/installation/data_node_installation.md index 76cddd2f0..98495bab0 100644 --- a/content/enterprise_influxdb/v1.9/introduction/install-and-deploy/installation/data_node_installation.md +++ b/content/enterprise_influxdb/v1.9/introduction/install-and-deploy/installation/data_node_installation.md @@ -311,8 +311,12 @@ CREATE USER admin WITH PASSWORD '' WITH ALL PRIVILEGES ## Next steps -Once your data nodes are part of your cluster: +Once your data nodes are part of your cluster, do the following: +- Set up [authentication](/enterprise_influxdb/v1.9/administration/configure/security/authentication/). + Once you cluster is configured for authentication, + if you want to add more users in addition to admin user, + see [Manage users and permissions](/enterprise_influxdb/v1.9/administration/manage/security/). +- [Enable TLS](/enterprise_influxdb/v1.9/guides/enable-tls/). - [Set up Chronograf](/enterprise_influxdb/v1.9/install-and-deploy/installation/chrono_install) for UI visualization, dashboards, and management. -- [Enable TLS](/enterprise_influxdb/v1.9/guides/enable-tls/) for increased security (recommended). diff --git a/content/enterprise_influxdb/v1.9/introduction/install-and-deploy/installation/meta_node_installation.md b/content/enterprise_influxdb/v1.9/introduction/install-and-deploy/installation/meta_node_installation.md index 299ac860b..2affd5c2c 100644 --- a/content/enterprise_influxdb/v1.9/introduction/install-and-deploy/installation/meta_node_installation.md +++ b/content/enterprise_influxdb/v1.9/introduction/install-and-deploy/installation/meta_node_installation.md @@ -257,7 +257,4 @@ Note that your cluster must have at least three meta nodes. If you do not see your meta nodes in the output, retry adding them to the cluster. -Once your meta nodes are part of your cluster move on to [the next steps to -set up your data nodes](/enterprise_influxdb/v1.9/install-and-deploy/installation/data_node_installation/). -Please do not continue to the next steps if your meta nodes are not part of the -cluster. +After your meta nodes are part of your cluster, [install data nodes](/enterprise_influxdb/v1.9/install-and-deploy/installation/data_node_installation/). diff --git a/content/enterprise_influxdb/v1.9/query_language/functions.md b/content/enterprise_influxdb/v1.9/query_language/functions.md index 3821590de..422bb77ff 100644 --- a/content/enterprise_influxdb/v1.9/query_language/functions.md +++ b/content/enterprise_influxdb/v1.9/query_language/functions.md @@ -6617,7 +6617,7 @@ KAMA will adjust when the data swings widen and follow data from a greater dista This trend-following indicator can be used to identify the overall trend, time turning points and filter data movements. -Source +Source #### Basic syntax diff --git a/content/enterprise_influxdb/v1.9/tools/api_client_libraries.md b/content/enterprise_influxdb/v1.9/tools/api_client_libraries.md index 04f516f05..8e16b2ec3 100644 --- a/content/enterprise_influxdb/v1.9/tools/api_client_libraries.md +++ b/content/enterprise_influxdb/v1.9/tools/api_client_libraries.md @@ -96,7 +96,7 @@ To install and use the Python client library, follow the [instructions below](#i token=token, ``` - > **Note:** The database (and retention policy, if applicable) are converted to a [bucket](https://v2. docs.influxdata.com/v2.0/reference/glossary/#bucket) data store compatible with InfluxDB 2.0. + > **Note:** The database (and retention policy, if applicable) are converted to a [bucket](/v2.0/reference/glossary/#bucket) data store compatible with InfluxDB 2.0. 5. Instantiate a writer object using the client object and the write_api method. Use the `write_api` method to configure the writer object. diff --git a/layouts/shortcodes/enterprise-warning-authn-b4-authz.md b/layouts/shortcodes/enterprise-warning-authn-b4-authz.md new file mode 100644 index 000000000..c5c01ae40 --- /dev/null +++ b/layouts/shortcodes/enterprise-warning-authn-b4-authz.md @@ -0,0 +1,20 @@ + +{{ if eq .Page.Title "Configure authentication" }} +
+ +**Important** +Authentication _must be enabled **before**_ authorization can be managed. +If authentication is not enabled, *permissions will not be enforced*. + +
+{{ else }} +
+ +**Important** +Authentication _must be enabled **before**_ authorization can be managed. +If authentication is not enabled, *permissions will not be enforced*. +See ["Enable authentication"](/enterprise_influxdb/v1.9/administration/configure/security/authentication/). + +
+{{ end }}