Authentication and authorization in InfluxDB

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

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

Authentication

The InfluxDB 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.

Set up authentication

1. Create at least one admin user. See the authorization section for how to create an admin user.

   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. Enable authentication in your configuration file by setting the auth-enabled option to true in the [http] section:

   [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"
   

   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.

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

Authenticate with the InfluxDB API

There are two options for authenticating with the InfluxDB 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

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

Authenticate with query parameters in the URL or request body

Set u as the username and p as the password.

Credentials as query parameters

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

Credentials in the 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 environment variables

Use the INFLUX_USERNAME and INFLUX_PASSWORD environment variables to provide authentication credentials to the influx CLI.

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

influx
Connected to http://localhost:8086 version 1.11.8
InfluxDB shell 1.11.8

Authenticate with CLI flags

Use the -username and -password flags to provide authentication credentials to the influx CLI.

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

Authenticate with credentials in the influx shell

Start the influx shell and run the auth command. Enter your username and password when prompted.

> influx
Connected to http://localhost:8086 version 1.11.8
InfluxDB shell 1.11.8
> 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.

1. Add a shared secret in your InfluxDB configuration file
2. Generate your JWT token
3. 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. The longer the secret string, the more secure it is:

[http]
  shared-secret = "my super secret pass phrase"

Alternatively, to avoid keeping your secret phrase as plain text in your InfluxDB configuration file, set the value with the INFLUXDB_HTTP_SHARED_SECRET environment variable.

Generate your JWT token

Use an authentication service to generate a secure token using your InfluxDB username, an expiration time, and your shared secret. There are online tools, such as https://jwt.io/, that will do this for you.

The payload (or claims) of the token must be in the following format:

{
  "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.

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/.

The generated token follows this format: <header>.<payload>.<signature>

Include the token in HTTP requests

Include your generated token as part of the Authorization header in HTTP requests. Use the Bearer authorization scheme:

Authorization: Bearer <myToken>

Example query request with JWT authentication

curl -G "http://localhost:8086/query?db=demodb" \
  --data-urlencode "q=SHOW DATABASES" \
  --header "Authorization: Bearer <header>.<payload>.<signature>"

Authenticate Telegraf requests to InfluxDB

Authenticating 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.

###############################################################################
#                            OUTPUT PLUGINS                                   #
###############################################################################

# ...

[[outputs.influxdb]]
  # ...
  username = "example-username" # Provide your username
  password = "example-password" # Provide your password

# ...

Restart Telegraf and you’re all set!

Authorization

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

User types and privileges

Admin users

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

Database management

• CREATE DATABASE
• DROP DATABASE
• DROP SERIES
• DROP MEASUREMENT
• CREATE RETENTION POLICY
• ALTER RETENTION POLICY
• DROP RETENTION POLICY
• CREATE CONTINUOUS QUERY
• DROP CONTINUOUS QUERY

For more information about these commands, see Database management and Continuous queries.

User management

• Admin user management
  • CREATE USER
  • GRANT ALL PRIVILEGES
  • REVOKE ALL PRIVILEGES
  • SHOW USERS
• Non-admin user management:
  • CREATE USER
  • GRANT [READ,WRITE,ALL]
  • REVOKE [READ,WRITE,ALL]
• General user management:
  • SET PASSWORD
  • 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

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

REVOKE administrative privileges from an admin user

REVOKE ALL PRIVILEGES FROM <username>

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

> 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
one_more_database_name      NO PRIVILEGES

General admin and non-admin user management

Reset a user’s password

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

CLI example:

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

DROP a user

DROP USER <username>

CLI example:

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