fixed formatting in 1.8 auth setup doc (#2347)

pull/2349/head
Scott Anderson 2021-03-24 15:34:09 -06:00 committed by GitHub
parent d5d0035447
commit 94ddeb0de3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 155 additions and 158 deletions

View File

@ -21,54 +21,62 @@ This document covers setting up and managing authentication and authorization in
- [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.
{{% 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 should be run behind a third-party service. If InfluxDB 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 [command line interface](/influxdb/v1.8/tools/shell/) (CLI), which connects to the database using the API, include simple, built-in authentication based on user credentials.
When you enable authentication, InfluxDB 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 %}}
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.
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 will **not** enforce authentication and will only accept the [query](#user-management-commands) that creates a new admin user.
{{% note %}}
If you enable authentication and have no users, InfluxDB will **not** enforce authentication
and will only accept the [query](#user-management-commands) that creates a new admin user.
{{% /note %}}
InfluxDB will enforce authentication once there is an admin user.
InfluxDB will enforce authentication once there is an admin user.
#### 2. By default, authentication is disabled in the configuration file.
Enable authentication by setting the `auth-enabled` option to `true` in the `[http]` section of the configuration file:
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 # ✨
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"
```
```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 %}}
{{% 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 %}}
{{% /note %}}
#### 3. Restart the process
Now InfluxDB will check user credentials on every request and will only process requests that have valid credentials for an existing user.
3. **Restart InfluxDB**.
Once restarted, InfluxDB checks user credentials on every request and only
processes requests that have valid credentials for an existing user.
### Authenticate requests
@ -82,39 +90,37 @@ See the section on [authorization](#authorization) for the different user types,
> **Note:** InfluxDB redacts passwords when you enable authentication.
##### Authenticate with Basic Authentication as described in [RFC 2617, Section 2](http://tools.ietf.org/html/rfc2617)
This is the preferred method for providing user credentials.
Example:
##### Authenticate with Basic Authentication
```bash
curl -G http://localhost:8086/query -u todd:influxdb4ever --data-urlencode "q=SHOW DATABASES"
curl -G http://localhost:8086/query \
-u todd:influxdb4ever \
--data-urlencode "q=SHOW DATABASES"
```
##### Authenticate by providing query parameters in the URL or request body
##### Authenticate with query parameters in the URL or request body
Set `u` as the username and `p` as the password.
###### Example using query parameters
###### Credentials as query parameters
```bash
curl -G "http://localhost:8086/query?u=todd&p=influxdb4ever" --data-urlencode "q=SHOW DATABASES"
curl -G "http://localhost:8086/query?u=todd&p=influxdb4ever" \
--data-urlencode "q=SHOW DATABASES"
```
###### Example using request body
###### 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"
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 the `INFLUX_USERNAME` and `INFLUX_PASSWORD` environment variables
Example:
##### 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
@ -127,9 +133,9 @@ Connected to http://localhost:8086 version 1.4.x
InfluxDB shell 1.4.x
```
##### Authenticate by setting the `username` and `password` flags when you start the CLI
Example:
##### Authenticate with CLI flags
Use the `-username` and `-password` flags to provide authentication credentials
to the `influx` CLI.
```bash
influx -username todd -password influxdb4ever
@ -137,14 +143,14 @@ Connected to http://localhost:8086 version 1.4.x
InfluxDB shell 1.4.x
```
##### Authenticate with `auth <username> <password>` after starting the CLI
Example:
##### Authenticate with credentials in the influx sheel
Start the `influx` shell and run the `auth` command.
Enter your username and password when prompted.
```bash
influx
> influx
Connected to http://localhost:8086 version 1.4.x
InfluxDB shell 1.4.x
InfluxDB shell 1.8.x
> auth
username: todd
password:
@ -152,16 +158,20 @@ password:
```
#### Authenticate using JWT tokens
Passing JWT tokens in each request is a more secure alternative to using passwords.
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
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 configuration file
InfluxDB 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"
```
@ -169,29 +179,30 @@ The longer the secret string, the more secure it is:
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 token
##### 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).
- **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: `<header>.<payload>.<signature>`
##### 3. Include the token in HTTP requests
##### Include the token in HTTP requests
Include your generated token as part of the ``Authorization`` header in HTTP requests.
Use the ``Bearer`` authorization scheme:
@ -204,11 +215,10 @@ 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 <header>.<payload>.<signature>"
--header "Authorization: Bearer <header>.<payload>.<signature>"
```
## Authenticate Telegraf requests to InfluxDB
@ -219,24 +229,21 @@ In the Telegraf configuration file (`/etc/telegraf/telegraf.conf`), uncomment
and edit the `username` and `password` settings.
```toml
>
###############################################################################
# OUTPUT PLUGINS #
###############################################################################
>
[...]
>
## Write timeout (for the InfluxDB client), formatted as a string.
## If not provided, will default to 5s. 0s means no timeout (not recommended).
timeout = "5s"
username = "telegraf" #💥
password = "metricsmetricsmetricsmetrics" #💥
>
[...]
###############################################################################
# OUTPUT PLUGINS #
###############################################################################
# ...
[[outputs.influxdb]]
# ...
username = "example-username" # Provide your username
password = "example-password" # Provide your password
# ...
```
Next, restart Telegraf and you're all set!
Restart Telegraf and you're all set!
## Authorization
@ -246,33 +253,44 @@ By default, authentication is disabled, all credentials are silently ignored, an
### 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:
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`CREATE DATABASE`, and `DROP DATABASE`
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`DROP SERIES` and `DROP MEASUREMENT`
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`CREATE RETENTION POLICY`, `ALTER RETENTION POLICY`, and `DROP RETENTION POLICY`
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`CREATE CONTINUOUS QUERY` and `DROP CONTINUOUS QUERY`
##### 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`
See the [database management](/influxdb/v1.8/query_language/manage-database/) and [continuous queries](/influxdb/v1.8/query_language/continuous_queries/) pages for a complete discussion of the commands listed above.
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:
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Admin user management:
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[`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), and [`SHOW USERS`](#show-all-existing-users-and-their-admin-status)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Non-admin user management:
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[`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), and [`SHOW GRANTS`](#show-a-user-s-database-privileges)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;General user management:
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[`SET PASSWORD`](#re-set-a-user-s-password) and [`DROP USER`](#drop-a-user)
##### 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:
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`READ`
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`WRITE`
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`ALL` (both `READ` and `WRITE` access)
- `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.
@ -283,71 +301,51 @@ Non-admin users can [`SHOW`](/influxdb/v1.8/query_language/explore-schema/#show-
When you enable HTTP authentication, InfluxDB requires you to create at least one admin user before you can interact with the system.
`CREATE USER admin WITH PASSWORD '<password>' WITH ALL PRIVILEGES`
```sql
CREATE USER admin WITH PASSWORD '<password>' WITH ALL PRIVILEGES
```
##### `CREATE` another admin user
##### Create another admin user
```sql
CREATE USER <username> WITH PASSWORD '<password>' WITH ALL PRIVILEGES
```
CLI example:
{{% note %}}
Repeating the exact `CREATE USER` statement is idempotent.
If any values change the database will return a duplicate user error.
```sql
> CREATE USER paul WITH PASSWORD 'timeseries4days' WITH ALL PRIVILEGES
> 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:** 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:
>
> 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 <username>
```
CLI example:
```sql
> GRANT ALL PRIVILEGES TO "todd"
>
```
##### `REVOKE` administrative privileges from an admin user
```sql
REVOKE ALL PRIVILEGES FROM <username>
```
CLI example:
```sql
> REVOKE ALL PRIVILEGES FROM "todd"
>
```
##### `SHOW` all existing users and their admin status
```sql
SHOW USERS
```
CLI example:
###### CLI Example
```sql
> SHOW USERS
user admin
user admin
todd false
paul true
hermione false
@ -357,14 +355,12 @@ dobby false
#### Non-admin user management
##### `CREATE` a new non-admin user
```sql
CREATE USER <username> WITH PASSWORD '<password>'
```
CLI example:
```sql
###### CLI example
```js
> CREATE USER todd WITH PASSWORD 'influxdb41yf3'
> CREATE USER alice WITH PASSWORD 'wonder\'land'
> CREATE USER "rachel_smith" WITH PASSWORD 'asdf1234!'
@ -373,27 +369,28 @@ CLI example:
>
```
> **Notes:**
>
* 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.
{{% 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'
>
* 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:
>
> 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
@ -461,7 +458,7 @@ one_more_database_name NO PRIVILEGES
#### General admin and non-admin user management
##### Re`SET` a user's password
##### Reset a user's password
```sql
SET PASSWORD FOR <username> = '<password>'