Documentation

Manage authentication and authorization

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

Authentication

Enable authentication in InfluxDB Enterprise to only allow requests that are sent with valid credentials to execute.

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.

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.

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.

    To create an admin user, run the following command using the 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:

    [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 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 using one of the following options:

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 permissions. To learn about different users types, permissions, and how to manage users, see authorization.

InfluxDB Enterprise redacts passwords in log output when you enable authentication.

Authenticate with basic authentication
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
curl -G "http://localhost:8086/query?u=todd&p=password4todd" \
  --data-urlencode "q=SHOW DATABASES"
Credentials in the request body
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:

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=password4todd
echo $INFLUX_USERNAME $INFLUX_PASSWORD
todd password4todd

influx
Connected to http://localhost:8086 version 1.9.3
InfluxDB shell 1.9.3
Authenticate with CLI flags

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

influx -username todd -password password4todd
Connected to http://localhost:8086 version 1.9.3
InfluxDB shell 1.9.3
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.9.3
InfluxDB shell 1.9.3
> 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 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. 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.

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

  3. Include the token in HTTP requests.

    Include your generated token as part of the Authorization header in HTTP requests:

    Authorization: Bearer <myToken>
    

    Only unexpired tokens will successfully authenticate. Be sure your token has not expired.

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 in InfluxDB Enterprise refers to managing user permissions. To enable authorization, first 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 and/or the Enterprise meta API to manage InfluxDB Enterprise users and roles.

User types and privileges

InfluxDB Enterprise has the following kinds of users:

Admin users

Admin users have the following permissions:

PermissionDescriptionToken
View AdminPermission to view or edit admin screensViewAdmin
View ChronografPermission to use Chronograf toolsViewChronograf
Create DatabasesPermission to create databasesCreateDatabase
Create Users & RolesPermission to create users and rolesCreateUserAndRole
Add/Remove NodesPermission to add/remove nodes from a clusterAddRemoveNode
Drop DatabasesPermission to drop databasesDropDatabase
Drop DataPermission to drop measurements and seriesDropData
ReadPermission to read dataReadData
WritePermission to write dataWriteData
RebalancePermission to rebalance a clusterRebalance
Manage ShardsPermission to copy and delete shardsManageShard
Manage Continuous QueriesPermission to create, show, and drop continuous queriesManageContnuousQuery
Manage QueriesPermission to show and kill queriesManageQuery
Manage SubscriptionsPermission to show, add, and drop subscriptionsManageSubscription
MonitorPermission to show stats and diagnosticsMonitor
Copy ShardPermission to copy shardsCopyShard

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

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 by an admin user.

Non-admin users can SHOW the databases for which they have ReadData or WriteData permissions.

User management commands

User management commands apply to either admin users, non-admin users, or both.

Manage admin users

Create an admin user with:

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

Repeating the exact CREATE USER statement is idempotent. If any values change the database will return a duplicate user error.

> 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

Manage non-admin users

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

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

Manage admin and non-admin users

Reset a user’s password
SET PASSWORD FOR <username> = '<password>'

CLI example:

> SET PASSWORD FOR "todd" = 'password4todd'

The password string 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.

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.


Set your InfluxDB URL

Upgrade to InfluxDB Cloud or InfluxDB 2.0!

InfluxDB Cloud and InfluxDB OSS 2.0 ready for production.