Manage fine-grained authorization

Important
Authentication must be enabled before authorization can be managed. If authentication is not enabled, permissions will not be enforced. See “Enable authentication”.

Use fine-grained authorization (FGA) to control user access at the database, measurement, and series levels.

You must have admin permissions to set up FGA.

FGA does not apply to Flux

FGA does not restrict actions performed by Flux queries (both read and write). If using FGA, we recommend [disabling Flux](/enterprise_influxdb/1.11/flux/installation/).

FGA is only available in InfluxDB Enterprise. InfluxDB OSS 1.x controls access at the database level only.

Set up fine-grained authorization

Enable authentication in your InfluxDB configuration file.
Create users through the InfluxDB query API.
```
CREATE USER username WITH PASSWORD 'password'
```
For more information, see User management commands.
Ensure that you can access the meta node API (port 8091 by default).
In a typical cluster configuration, the HTTP ports for data nodes (8086 by default) are exposed to clients but the meta node HTTP ports are not. You may need to work with your network administrator to gain access to the meta node HTTP ports.
Create users. Do the following:
1. As Administrator, create users and grant users all permissions. The example below grants users east and west all permissions on the datacenters database.
```
CREATE DATABASE datacenters

CREATE USER east WITH PASSWORD 'east'
GRANT ALL ON datacenters TO east

CREATE USER west WITH PASSWORD 'west'
GRANT ALL ON datacenters TO west
```
2. Add fine-grained permissions to users as needed.
Create roles to grant permissions to users assigned to a role.
For an overview of how users and roles work in InfluxDB Enterprise, see InfluxDB Enterprise users.
Set up restrictions. Restrictions apply to all non-admin users.
Permissions (currently “read” and “write”) may be restricted independently depending on the scenario.
Set up grants to remove restrictions for specified users and roles.

Notes about examples

The examples below use curl, a command line tool for transferring data, to send HTTP requests to the Meta API, and jq, a command line JSON processor, to make the JSON output easier to read. Alternatives for each are available, but are not covered in this documentation.

All examples assume authentication is enabled in InfluxDB. Admin credentials must be sent with each request. Use the curl -u flag to pass authentication credentials:

curl -u `username:password` #...

Matching methods

The following matching methods are available when managing restrictions and grants to databases, measurements, or series:

exact (matches only exact string matches)
prefix (matches strings the begin with a specified prefix)

# Match a database name exactly
"database": {"match": "exact", "value": "my_database"}

# Match any databases that begin with "my_"
"database": {"match": "prefix", "value": "my_"}

Wildcard matching

Neither exact nor prefix matching methods allow for wildcard matching.

Manage roles

Roles allow you to assign permissions to groups of users. The following examples assume the user1, user2 and ops users already exist in InfluxDB.

Create a role

To create a new role, use the InfluxDB Meta API /role endpoint with the action field set to create in the request body.

The following examples create two new roles:

east
west

# Create east role
curl -s --location-trusted -XPOST "https://127.0.0.1:8091/role" \
  -u "admin-username:admin-password" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "action": "create",
    "role": {
      "name": "east"
    }
  }'

# Create west role
curl -s --location-trusted -XPOST "https://127.0.0.1:8091/role" \
  -u "admin-username:admin-password" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "action": "create",
    "role": {
      "name": "west"
    }
  }'

Specify role permissions

To specify permissions for a role, use the InfluxDB Meta API /role endpoint with the action field set to add-permissions. Specify the permissions to add for each database.

The following example sets read and write permissions on db1 for both east and west roles.

curl -s --location-trusted -XPOST "https://127.0.0.1:8091/role" \
  -u "admin-username:admin-password" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "action": "add-permissions",
    "role": {
      "name": "east",
      "permissions": {
        "db1": ["ReadData", "WriteData"]
      }
    }
  }'

curl -s --location-trusted -XPOST "https://127.0.0.1:8091/role" \
  -u "admin-username:admin-password" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "action": "add-permissions",
    "role": {
      "name": "west",
      "permissions": {
        "db1": ["ReadData", "WriteData"]
      }
    }
  }'

Remove role permissions

To remove permissions from a role, use the InfluxDB Meta API /role endpoint with the action field set to remove-permissions. Specify the permissions to remove from each database.

The following example removes read and write permissions from db1 for the east role.

curl -s --location-trusted -XPOST "https://127.0.0.1:8091/role" \
  -u "admin-username:admin-password" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "action": "remove-permissions",
    "role": {
      "name": "east",
      "permissions": {
        "db1": ["ReadData", "WriteData"]
      }
    }
  }'

Assign users to a role

To assign users to role, set the action field to add-users and include a list of users in the role field.

The following examples add user1, user2 and the ops user to the east and west roles.

# Add user1 and ops to the east role
curl -s --location-trusted -XPOST "https://127.0.0.1:8091/role" \
  -u "admin-username:admin-password" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "action": "add-users",
    "role": {
      "name": "east",
      "users": ["user1", "ops"]
    }
  }'

# Add user1 and ops to the west role
curl -s --location-trusted -XPOST "https://127.0.0.1:8091/role" \
  -u "admin-username:admin-password" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "action": "add-users",
    "role": {
      "name": "west",
      "users": ["user2", "ops"]
    }
  }'

View existing roles

To view existing roles with their assigned permissions and users, use the GET request method with the InfluxDB Meta API /role endpoint.

curl --location-trusted -XGET https://127.0.0.1:8091/role | jq

Delete a role

To delete a role, the InfluxDB Meta API /role endpoint and set the action field to delete and include the name of the role to delete.

curl -s --location-trusted -XPOST "https://127.0.0.1:8091/role" \
  -u "admin-username:admin-password" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "action": "delete",
    "role": {
      "name": "west"
    }
  }'

Deleting a role does not delete users assigned to the role.

Manage restrictions

Restrictions restrict either or both read and write permissions on InfluxDB assets. Restrictions apply to all non-admin users. Grants override restrictions.

In order to run meta queries (such as SHOW MEASUREMENTS or SHOW TAGS ), users must have read permissions for the database and retention policy they are querying.

Manage restrictions using the InfluxDB Meta API acl/restrictions endpoint.

curl --location-trusted -XGET "https://127.0.0.1:8091/influxdb/v2/acl/restrictions"

Restrict by database
Restrict by measurement in a database
Restrict by series in a database
View existing restrictions
Update a restriction
Remove a restriction

Note: For the best performance, set up minimal restrictions.

Restrict by database

In most cases, restricting the database is the simplest option, and has minimal impact on performance. The following example restricts reads and writes on the my_database database.

curl --location-trusted -XPOST "https://127.0.0.1:8091/influxdb/v2/acl/restrictions" \
  -u "admin-username:admin-password" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "database": {"match": "exact", "value": "my_database"},
    "permissions": ["read", "write"]
  }'

Restrict by measurement in a database

The following example restricts read and write permissions on the network measurement in the my_database database. This restriction does not apply to other measurements in the my_database database.

curl --location-trusted -XPOST "https://127.0.0.1:8091/influxdb/v2/acl/restrictions" \
  -u "admin-username:admin-password" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "database": {"match": "exact", "value": "my_database"},
    "measurement": {"match": "exact", "value": "network"},
    "permissions": ["read", "write"]
  }'

Restrict by series in a database

The most fine-grained restriction option is to restrict specific tags in a measurement and database. The following example restricts read and write permissions on the datacenter=east tag in the network measurement in the my_database database. This restriction does not apply to other tags or tag values in the network measurement.

curl --location-trusted -XPOST "https://127.0.0.1:8091/influxdb/v2/acl/restrictions" \
  -u "admin-username:admin-password" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "database": {"match": "exact", "value": "my_database"},
    "measurement": {"match": "exact", "value": "network"},
    "tags": [{"match": "exact", "key": "datacenter", "value": "east"}],
    "permissions": ["read", "write"]
  }'

Consider this option carefully, as it allows writes to network without tags or writes to network with a tag key of datacenter and a tag value of anything but east.

Apply restrictions to a series defined by multiple tags

curl --location-trusted -XPOST "https://127.0.0.1:8091/influxdb/v2/acl/restrictions" \
  -u "admin-username:admin-password" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "database": {"match": "exact", "value": "my_database"},
    "measurement": {"match": "exact", "value": "network"},
    "tags": [
      {"match": "exact", "key": "tag1", "value": "value1"},
      {"match": "exact", "key": "tag2", "value": "value2"}
    ],
    "permissions": ["read", "write"]
  }'

Create multiple restrictions at a time

There may be times where you need to create restrictions using unique values for each. To create multiple restrictions for a list of values, use a bash for loop:

for value in val1 val2 val3 val4; do
  curl --location-trusted -XPOST "https://127.0.0.1:8091/influxdb/v2/acl/restrictions" \
    -u "admin-username:admin-password" \
    -H "Content-Type: application/json" \
    --data-binary '{
      "database": {"match": "exact", "value": "my_database"},
      "measurement": {"match": "exact", "value": "network"},
      "tags": [{"match": "exact", "key": "datacenter", "value": "'$value'"}],
      "permissions": ["read", "write"]
    }'
done

View existing restrictions

To view existing restrictions, use the GET request method with the acl/restrictions endpoint.

curl --location-trusted -u "admin-username:admin-password" -XGET "https://127.0.0.1:8091/influxdb/v2/acl/restrictions" | jq

Update a restriction

You can not directly modify a restriction. Delete the existing restriction and create a new one with updated parameters.

Remove a restriction

To remove a restriction, obtain the restriction ID using the GET request method with the acl/restrictions endpoint. Use the DELETE request method to delete a restriction by ID.

# Obtain the restriction ID from the list of restrictions
curl --location-trusted -u "admin-username:admin-password" \
  -XGET "https://127.0.0.1:8091/influxdb/v2/acl/restrictions" | jq

# Delete the restriction using the restriction ID
curl --location-trusted -u "admin-username:admin-password" \
  -XDELETE "https://127.0.0.1:8091/influxdb/v2/acl/restrictions/<restriction_id>"

Manage grants

Grants remove restrictions and grant users or roles either or both read and write permissions on InfluxDB assets.

Manage grants using the InfluxDB Meta API acl/grants endpoint.

curl --location-trusted -u "admin-username:admin-password" \
  -XGET "https://127.0.0.1:8091/influxdb/v2/acl/grants"

Grant permissions by database
Grant permissions by measurement in a database
Grant permissions by series in a database
View existing grants
Update a grant
Remove a grant

Grant permissions by database

The following examples grant read and write permissions on the my_database database.

Note: This offers no guarantee that the users will write to the correct measurement or use the correct tags.

Grant database-level permissions to users

curl -s --location-trusted -XPOST "https://127.0.0.1:8091/influxdb/v2/acl/grants" \
  -u "admin-username:admin-password" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "database": {"match": "exact", "value": "my_database"},
    "permissions": ["read", "write"],
    "users": [
      {"name": "user1"},
      {"name": "user2"}
    ]
  }'

Grant database-level permissions to roles

curl -s --location-trusted -XPOST "https://127.0.0.1:8091/influxdb/v2/acl/grants" \
  -u "admin-username:admin-password" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "database": {"match": "exact", "value": "my_database"},
    "permissions": ["read", "write"],
    "roles": [
      {"name": "role1"},
      {"name": "role2"}
    ]
  }'

Grant permissions by measurement in a database

The following examples grant permissions to the network measurement in the my_database database. These grants do not apply to other measurements in the my_database database nor guarantee that users will use the correct tags.

Grant measurement-level permissions to users

curl -s --location-trusted -XPOST "https://127.0.0.1:8091/influxdb/v2/acl/grants" \
  -u "admin-username:admin-password" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "database": {"match": "exact", "value": "my_database"},
    "measurement": {"match": "exact", "value": "network"},
    "permissions": ["read", "write"],
    "users": [
      {"name": "user1"},
      {"name": "user2"}
    ]
  }'

To grant access for roles, run:

curl -s --location-trusted -XPOST "https://127.0.0.1:8091/influxdb/v2/acl/grants" \
  -u "admin-username:admin-password" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "database": {"match": "exact", "value": "my_database"},
    "measurement": {"match": "exact", "value": "network"},
    "permissions": ["read", "write"],
    "roles": [
      {"name": "role1"},
      {"name": "role2"}
    ]
  }'

Grant permissions by series in a database

The following examples grant access only to data with the corresponding datacenter tag. Neither guarantees the users will use the network measurement.

Grant series-level permissions to users

# Grant user1 read/write permissions on data with the 'datacenter=east' tag set.
curl -s --location-trusted -XPOST "https://127.0.0.1:8091/influxdb/v2/acl/grants" \
  -u "admin-username:admin-password" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "database": {"match": "exact", "value": "my_database"},
    "tags": [{"match": "exact", "key": "datacenter", "value": "east"}],
    "permissions": ["read", "write"],
    "users": [{"name": "user1"}]
  }'

# Grant user2 read/write permissions on data with the 'datacenter=west' tag set.
curl -s --location-trusted -XPOST "https://127.0.0.1:8091/influxdb/v2/acl/grants" \
  -u "admin-username:admin-password" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "database": {"match": "exact", "value": "my_database"},
    "tags": [{"match": "exact", "key": "datacenter", "value": "west"}],
    "permissions": ["read", "write"],
    "users": [{"name": "user2"}]
  }'

Grant series-level permissions to roles

# Grant role1 read/write permissions on data with the 'datacenter=east' tag set.
curl -s --location-trusted -XPOST "https://127.0.0.1:8091/influxdb/v2/acl/grants" \
  -u "admin-username:admin-password" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "database": {"match": "exact", "value": "my_database"},
    "tags": [{"match": "exact", "key": "datacenter", "value": "east"}],
    "permissions": ["read", "write"],
    "roles": [{"name": "role1"}]
  }'

# Grant role2 read/write permissions on data with the 'datacenter=west' tag set.
curl -s --location-trusted -XPOST "https://127.0.0.1:8091/influxdb/v2/acl/grants" \
  -u "admin-username:admin-password" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "database": {"match": "exact", "value": "my_database"},
    "tags": [{"match": "exact", "key": "datacenter", "value": "west"}],
    "permissions": ["read", "write"],
    "roles": [{"name": "role2"}]
  }'

Grant access to specific series in a measurement

The following examples grant read and write permissions to corresponding datacenter tags in the network measurement. They each specify the measurement in the request body.

Grant series-level permissions in a measurement to users

# Grant user1 read/write permissions on data with the 'datacenter=west' tag set
# inside the 'network' measurement.
curl -s --location-trusted -XPOST "https://127.0.0.1:8091/influxdb/v2/acl/grants" \
  -u "admin-username:admin-password" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "database": {"match": "exact", "value": "my_database"},
    "measurement": {"match": "exact", "value": "network"},
    "tags": [{"match": "exact", "key": "datacenter", "value": "east"}],
    "permissions": ["read", "write"],
    "users": [{"name": "user1"}]
  }'

# Grant user2 read/write permissions on data with the 'datacenter=west' tag set
# inside the 'network' measurement.
curl -s --location-trusted -XPOST "https://127.0.0.1:8091/influxdb/v2/acl/grants" \
  -u "admin-username:admin-password" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "database": {"match": "exact", "value": "my_database"},
    "measurement": {"match": "exact", "value": "network"},
    "tags": [{"match": "exact", "key": "datacenter", "value": "west"}],
    "permissions": ["read", "write"],
    "users": [{"name": "user2"}]
  }'

Grant series-level permissions in a measurement to roles

# Grant role1 read/write permissions on data with the 'datacenter=west' tag set
# inside the 'network' measurement.
curl -s --location-trusted -XPOST "https://127.0.0.1:8091/influxdb/v2/acl/grants" \
  -u "admin-username:admin-password" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "database": {"match": "exact", "value": "my_database"},
    "measurement": {"match": "exact", "value": "network"},
    "tags": [{"match": "exact", "key": "datacenter", "value": "east"}],
    "permissions": ["read", "write"],
    "roles": [{"name": "role1"}]
  }'

# Grant role2 read/write permissions on data with the 'datacenter=west' tag set
# inside the 'network' measurement.
curl -s --location-trusted -XPOST "https://127.0.0.1:8091/influxdb/v2/acl/grants" \
  -u "admin-username:admin-password" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "database": {"match": "exact", "value": "my_database"},
    "measurement": {"match": "exact", "value": "network"},
    "tags": [{"match": "exact", "key": "datacenter", "value": "west"}],
    "permissions": ["read", "write"],
    "roles": [{"name": "role2"}]
  }'

Grants for specific series also apply to meta queries. Results from meta queries are restricted based on series-level permissions. For example, SHOW TAG VALUES only returns tag values that the user is authorized to see.

With these grants in place, a user or role can only read or write data from or to the network measurement if the data includes the appropriate datacenter tag set.

Note that this is only the requirement of the presence of that tag; datacenter=east,foo=bar will also be accepted.

View existing grants

To view existing grants, use the GET request method with the acl/grants endpoint.

curl --location-trusted -u "admin-username:admin-password" \
  -XGET "https://127.0.0.1:8091/influxdb/v2/acl/grants" | jq

Update a grant

You can not directly modify a grant. Delete the existing grant and create a new one with updated parameters.

Remove a grant

To delete a grant, obtain the grant ID using the GET request method with the acl/grants endpoint. Use the DELETE request method to delete a grant by ID.

# Obtain the grant ID from the list of grants
curl --location-trusted -u "admin-username:admin-password" \
  -XGET "https://127.0.0.1:8091/influxdb/v2/acl/grants" | jq

# Delete the grant using the grant ID
curl --location-trusted -u "admin-username:admin-password" \
  -XDELETE "https://127.0.0.1:8091/influxdb/v2/acl/grants/<grant_id>"

Was this page helpful?

Thank you for your feedback!

Support and feedback

Thank you for being part of our community! We welcome and encourage your feedback and bug reports for InfluxDB and this documentation. To find support, use the following resources:

Customers with an annual or support contract can contact InfluxData Support.

Edit this page Submit docs issue Submit InfluxDB issue