Authentication and Authorization

This document covers setting up and managing authentication and authorization in InfluxDB.

Authentication:	Authorization:
Set up Authentication	User Types and Privileges
Authenticate Requests	User Management Commands
HTTP Errors	HTTP Errors

Note: Authentication and authorization should not be relied upon to prevent access and protect data from malicious actors. If additional security or compliance features are desired, InfluxDB should be run behind a third-party service.

Authentication

InfluxDB’s HTTP API and the command line interface (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.

Set up Authentication

1. Create at least one admin user.

See the authorization section 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 that creates a new 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:

[http]  
  enabled = true  
  bind-address = ":8086"  
  auth-enabled = true # ✨
  log-enabled = true  
  write-tracing = false  
  pprof-enabled = false  
  https-enabled = false  
  https-certificate = "/etc/ssl/influxdb.pem"

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.

Authenticate Requests

Authenticate with the HTTP API

There are two options for authenticating with the HTTP API.

If you authenticate with both Basic Authentication and the URL query parameters, the user credentials specified in the query parameters take precedence. The queries in the following examples assume that the user is an admin user. See the section on authorization for the different user types, their privileges, and more on user management.

Note: InfluxDB redacts passwords when you enable authentication.

Authenticate with Basic Authentication as described in RFC 2617, Section 2

This is the preferred method for providing user credentials.

Example:

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

Set u as the username and p as the password.

Example using query parameters:

curl -G "http://localhost:8086/query?u=todd&p=influxdb4ever" --data-urlencode "q=SHOW DATABASES"

Example using request body:

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.

Authenticate with the `INFLUX_USERNAME` and `INFLUX_PASSWORD` environment variables

Example:

export INFLUX_USERNAME todd
export INFLUX_PASSWORD influxdb4ever
echo $INFLUX_USERNAME $INFLUX_PASSWORD
todd influxdb4ever

influx
Connected to http://localhost:8086 version 1.3.x
InfluxDB shell 1.3.x

Authenticate by setting the `username` and `password` flags when you start the CLI

Example:

influx -username todd -password influxdb4ever
Connected to http://localhost:8086 version 1.3.x
InfluxDB shell 1.3.x

Authenticate with `auth <username> <password>` after starting the CLI

Example:

influx
Connected to http://localhost:8086 version 1.3.x
InfluxDB shell 1.3.x
> auth
username: todd
password:
>

Authenticate Telegraf requests to InfluxDB

Authenticating Telegraf requests to an InfluxDB instance with authentication enabled requires some additional steps. In Telegraf’s configuration file (/etc/telegraf/telegraf.conf), uncomment and edit the username and password settings:
###############################################################################
#                            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" #????

[...]
Next, restart Telegraf and you’re all set!

Authorization

Authorization is only enforced once you’ve enabled authentication. By default, authentication is disabled, all credentials are silently ignored, and all users have all privileges.

User Types and Privileges

Admin users

Admin users have READ and WRITE access to all databases and full access to the following administrative queries:

Database management: ◦ CREATE DATABASE, and DROP DATABASE ◦ DROP SERIES and DROP MEASUREMENT ◦ CREATE RETENTION POLICY, ALTER RETENTION POLICY, and DROP RETENTION POLICY ◦ CREATE CONTINUOUS QUERY and DROP CONTINUOUS QUERY

See the database management and continuous queries pages for a complete discussion of the commands listed above.

User management: ◦ Admin user management: CREATE USER, GRANT ALL PRIVILEGES, REVOKE ALL PRIVILEGES, and SHOW USERS ◦ Non-admin user management: CREATE USER, GRANT [READ,WRITE,ALL], REVOKE [READ,WRITE,ALL], and SHOW GRANTS ◦ General user management: SET PASSWORD and DROP USER

See below for a complete discussion of the user management commands.

Non-admin users

Non-admin users can have one of the following three privileges per database: ◦ READ ◦ WRITE ◦ ALL (both READ and WRITE access)

READ, WRITE, and ALL privileges are controlled per user per database. A new non-admin user has no access to any database until they are specifically granted privileges to a database by an admin user. Non-admin users can SHOW the databases on which they have READ and/or WRITE permissions.

User Management Commands

Admin user management

When you enable HTTP authentication, InfluxDB requires you to create at least one admin user before you can interact with the system.

CREATE USER admin WITH PASSWORD '<password>' WITH ALL PRIVILEGES

`CREATE` another admin user:

CREATE USER <username> WITH PASSWORD '<password>' WITH ALL PRIVILEGES

CLI example:

> CREATE USER paul WITH PASSWORD 'timeseries4days' 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 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
>

`GRANT` administrative privileges to an existing user:

GRANT ALL PRIVILEGES TO <username>

CLI example:

> GRANT ALL PRIVILEGES TO "todd"
>

`REVOKE` administrative privileges from an admin user:

REVOKE ALL PRIVILEGES FROM <username>

CLI example:

> REVOKE ALL PRIVILEGES FROM "todd"
>

`SHOW` all existing users and their admin status:

SHOW USERS

CLI example:

> SHOW USERS
user 	 admin
todd     false
paul     true
hermione false
dobby    false

Non-admin user management

`CREATE` a new non-admin user:

CREATE USER <username> WITH PASSWORD '<password>'

CLI example:

> 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'
>

Notes:

The user value must be wrapped in double quotes if starts with a digit, is an InfluxQL keyword, contains a hyphen and or includes any special characters, for example: !@#$%^&*()-

The password string must be wrapped in single quotes.

Do not include the single quotes when authenticating requests.

For passwords that include a single quote or a newline character, escape the single quote or newline character with a backslash both 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 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'
>

`GRANT` `READ`, `WRITE` or `ALL` database privileges to an existing user:

GRANT [READ,WRITE,ALL] ON <database_name> TO <username>

CLI examples:

GRANT READ access to todd on the NOAA_water_database database:

> GRANT READ ON "NOAA_water_database" TO "todd"
>

GRANT ALL access to todd on the NOAA_water_database database:

> GRANT ALL ON "NOAA_water_database" TO "todd"
>

`REVOKE` `READ`, `WRITE`, or `ALL` database privileges from an existing user:

REVOKE [READ,WRITE,ALL] ON <database_name> FROM <username>

CLI examples:

REVOKE ALL privileges from todd on the NOAA_water_database database:

> REVOKE ALL ON "NOAA_water_database" FROM "todd"
>

REVOKE WRITE privileges from todd on the NOAA_water_database database:

> REVOKE WRITE ON "NOAA_water_database" FROM "todd"
>

Note: If a user with ALL privileges has WRITE privileges revoked, they are left with READ privileges, and vice versa.

`SHOW` a user’s database privileges:

SHOW GRANTS FOR <user_name>

CLI example:

> SHOW GRANTS FOR "todd"
database		            privilege
NOAA_water_database	        WRITE
another_database_name	    READ
yet_another_database_name   ALL PRIVILEGES

General admin and non-admin user management

Re`SET` a user’s password:

SET PASSWORD FOR <username> = '<password>'

CLI example:

> SET PASSWORD FOR "todd" = 'influxdb4ever'
>

> **Note:** The password [string](/influxdb/v1.3/query_language/spec/#strings) must be wrapped in single quotes.

Do not include the single quotes when authenticating requests. > For passwords that include a single quote or a newline character, escape the single quote or newline character with a backslash both when creating the password and when submitting authentication requests.

`DROP` a user:

DROP USER <username>

CLI example:

> DROP USER "todd"
>