Skip to content

fine-grained-authorization.md

Latest commit

 

History

History
393 lines (313 loc) · 15.3 KB

fine-grained-authorization.md

File metadata and controls

393 lines (313 loc) · 15.3 KB
title Fine Grained Authorization
alias -/docs/v1.3/administration/fga
menu
enterprise_influxdb_1_3
weight parent
10
Guides

Controlling access to data with Enterprise's Fine-Grained Authorization

In open source InfluxDB, access control operates only at a database level. In Enterprise, fine-grained authorization can be used to control access at a measurement or series level.

Concepts

To use fine-grained authorization (hereafter "FGA"), you must first enable authentication in your configuration file. Then the admin user needs to create users through the query API and grant those users explicit read and/or write privileges per database. So far, this is the same as how you would configure authorization on an open source InfluxDB instance.

To continue setting up fine-grained authorization, the admin user must first set restrictions which define a combination of database, measurement, and series which cannot be accessed without an explicit grant. A grant enables access to entities that were previously restricted.

Restrictions specify permissions defining whether reads and/or writes are being restricted, and they specify selectors defining the combination of database, measurement, and tags. Grants also specify permissions and selectors, but unlike restrictions, grants are able to specify users and roles. Users are the same as the users created in InfluxQL, and roles, an Enterprise feature, are created separately through the Meta HTTP API. (Roles are not covered in this guide.)

Modifying grants and restrictions

To configure FGA, you will need access to the meta nodes' HTTP ports (which run on port 8089 by default). Note that in a typical cluster configuration, the data nodes' HTTP ports (8086 by default) are exposed to clients but the meta nodes' HTTP ports are not. You may need to work with your network administrator to gain access to the meta nodes' HTTP ports.

Scenario: partitioning access within a single measurement via users

We'll assume a schema of a database named datacenters, one measurement named network with a tag of dc=east or dc=west, and two fields, bytes_in and bytes_out. Suppose you want to make sure that the client in the east datacenter can't read or write the west datacenter's metrics, and vice versa.

First, as an administrator, you would create the database and users and standard grants with InfluxQL queries:

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

At this point, the east and west users have unrestricted write access to the datacenters database and the ops user has unrestricted read access. We'll need to use curl to set up the restrictions first, and we'll need to decide how to apply the restrictions.

Restrictions

Restriction option 1: the entire database

Restricting the entire database is a simple option, and in most cases it is the simplest option to reason about. Moreover, because this is a very general restriction, it will have minimal impact on performance.

Assuming the meta node is running its HTTP service on localhost on the default port, you can run

curl -L -XPOST "http://localhost:8091/influxdb/v2/acl/restrictions" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "database": {"match": "exact", "value": "datacenters"},
    "permissions": ["read", "write"]
  }'

After applying this restriction and before applying any grants, the east and west users will not be authorized to write to the database.

Restriction option 2: one measurement within the database

Restricting a single measurement will disallow writes within that measurement, but access to other measurements within the database will be decided by standard permissions.

curl -L -XPOST "http://localhost:8091/influxdb/v2/acl/restrictions" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "database": {"match": "exact", "value": "datacenters"},
    "measurement": {"match": "exact", "value": "network"},
    "permissions": ["read", "write"]
  }'

Compared to the previous approach of restricting the entire database, this only restricts access to the measurement network. In this state, the east and west users are free to read from and write to any measurement in the database datacenters besides network.

Restriction option 3: specific series in a database

The most fine-grained restriction option is to restrict specific tags in a measurement and database.

for region in east west; do
  curl -L -XPOST "http://localhost:8091/influxdb/v2/acl/restrictions" \
    -H "Content-Type: application/json" \
    --data-binary '{
      "database": {"match": "exact", "value": "datacenters"},
      "measurement": {"match": "exact", "value": "network"},
      "tags": [{"match": "exact", "key": "dc", "value": "'$region'"}],
      "permissions": ["read", "write"]
    }'
done

This configuration would allow reads and writes from any measurement in datacenters; and when the measurement is network, it would only restrict when there is a tag dc=east or dc=west. This is probably not what you want, as it would allow writes to network without tags or writes to network with a tag key of dc and a tag value of anything but east or west.

Restriction summary

These options were simple matchers on exact patterns. Remember that you will achieve the best performance by having few, coarse-grained restrictions as opposed to many fine-grained restrictions.

We only used the matcher exact above, but you can also match with prefix if you want to restrict based on a common prefix on your database, measurements, or tags. The other matcher option is regex to use a regular expression.

Grants

Now that you've applied your restrictions that apply to all users, you must apply grants to allow selected users to bypass the restrictions. The structure of a POST body for a grant is identical to the POST body for a restriction, but with the addition of a users array.

Grant option 1: the entire database

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

curl -s -L -XPOST "http://localhost:8091/influxdb/v2/acl/grants" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "database": {"match": "exact", "value": "datacenters"},
    "permissions": ["read", "write"],
    "users": [{"name": "east"}, {"name": "west"}]
  }'
Grant option 2: one measurement within the database

This guarantees that the users will only have access to the network measurement but it still does not guarantee that they will use the correct tags.

curl -s -L -XPOST "http://localhost:8091/influxdb/v2/acl/grants" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "database": {"match": "exact", "value": "datacenters"},
    "measurement": {"match": "exact", "value": "network"},
    "permissions": ["read", "write"],
    "users": [{"name": "east"}, {"name": "west"}]
  }'
Grant option 3: specific tags on a database

This guarantees that the users will only have access to data with the corresponding dc tag but it does not guarantee that they will use the network measurement.

curl -s -L -XPOST "http://localhost:8091/influxdb/v2/acl/grants" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "database": {"match": "exact", "value": "datacenters"},
    "tags": [{"match": "exact", "key": "dc", "value": "east"}],
    "permissions": ["read", "write"],
    "users": [{"name": "east"}]
  }'
curl -s -L -XPOST "http://localhost:8091/influxdb/v2/acl/grants" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "database": {"match": "exact", "value": "datacenters"},
    "tags": [{"match": "exact", "key": "dc", "value": "west"}],
    "permissions": ["read", "write"],
    "users": [{"name": "west"}]
  }'
Grant option 4: specific series within the database

To guarantee that both users only have access to the network measurement and that the east user uses the tag dc=east and the west user uses the tag dc=west, we need to make two separate grant calls:

curl -s -L -XPOST "http://localhost:8091/influxdb/v2/acl/grants" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "database": {"match": "exact", "value": "datacenters"},
    "measurement": {"match": "exact", "value": "network"},
    "tags": [{"match": "exact", "key": "dc", "value": "east"}],
    "permissions": ["read", "write"],
    "users": [{"name": "east"}]
  }'
curl -s -L -XPOST "http://localhost:8091/influxdb/v2/acl/grants" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "database": {"match": "exact", "value": "datacenters"},
    "measurement": {"match": "exact", "value": "network"},
    "tags": [{"match": "exact", "key": "dc", "value": "west"}],
    "permissions": ["read", "write"],
    "users": [{"name": "west"}]
  }'

Now, when the east user writes to the network measurement, it must include the tag dc=east, and when the west user writes to network, it must include the tag dc=west. Note that this is only the requirement of the presence of that tag; dc=east,foo=bar will also be accepted.

Scenario: partitioning access via roles

Suppose that we have many individuals who need to write to our datacenters database in the previous example. We wouldn't want them to all share one set of login credentials. We can instead use roles, which are associate a set of users with a set of permissions.

We'll assume that we now have many users on the east and west teams, and we'll have an ops user who needs full access to data from both the east and west datacenters. We will only create one user each for east and west, but the process would be the same for any number of users.

First we will set up the users.

CREATE DATABASE datacenters

CREATE USER e001 WITH PASSWORD 'e001'
CREATE USER w001 WITH PASSWORD 'w001'
CREATE USER ops WITH PASSWORD 'ops'

Creating the roles

We want one role for full access to any point in datacenters with the tag dc=east and another role for the tag dc=west.

First, we initialize the roles.

curl -s -L -XPOST "http://localhost:8091/role" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "action": "create",
    "role": {
      "name": "east"
    }
  }'
curl -s -L -XPOST "http://localhost:8091/role" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "action": "create",
    "role": {
      "name": "west"
    }
  }'

Next, let's specify that anyone belonging to those roles has general read and write access to the datacenters database.

curl -s -L -XPOST "http://localhost:8091/role" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "action": "add-permissions",
    "role": {
      "name": "east",
      "permissions": {
        "datacenters": ["ReadData", "WriteData"]
      }
    }
  }'

curl -s -L -XPOST "http://localhost:8091/role" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "action": "add-permissions",
    "role": {
      "name": "west",
      "permissions": {
        "datacenters": ["ReadData", "WriteData"]
      }
    }
  }'

Next, we need to associate users to the roles. The east role gets the user from the east team, the west role gets the user from the west team, and both roles get the ops user.

curl -s -L -XPOST "http://localhost:8091/role" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "action": "add-users",
    "role": {
      "name": "east",
      "users": ["e001", "ops"]
    }
  }'
curl -s -L -XPOST "http://localhost:8091/role" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "action": "add-users",
    "role": {
      "name": "west",
      "users": ["w001", "ops"]
    }
  }'

Restrictions

Please refer to the previous scenario for directions on how to set up restrictions.

Grants and roles

Grants for a role function the same as grants for a user. Instead of using the key users to refer to users, use the key roles to refer to roles.

Grant option 1: the entire database

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

curl -s -L -XPOST "http://localhost:8091/influxdb/v2/acl/grants" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "database": {"match": "exact", "value": "datacenters"},
    "permissions": ["read", "write"],
    "roles": [{"name": "east"}, {"name": "west"}]
  }'
Grant option 2: one measurement within the database

This guarantees that the users in the roles will only have access to the network measurement but it still does not guarantee that they will use the correct tags.

curl -s -L -XPOST "http://localhost:8091/influxdb/v2/acl/grants" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "database": {"match": "exact", "value": "datacenters"},
    "measurement": {"match": "exact", "value": "network"},
    "permissions": ["read", "write"],
    "roles": [{"name": "east"}, {"name": "west"}]
  }'
Grant option 3: specific tags on a database

This guarantees that the users in the roles will only have access to data with the corresponding dc tag. They will have access to any measurement in the datacenters database.

curl -s -L -XPOST "http://localhost:8091/influxdb/v2/acl/grants" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "database": {"match": "exact", "value": "datacenters"},
    "tags": [{"match": "exact", "key": "dc", "value": "east"}],
    "permissions": ["read", "write"],
    "roles": [{"name": "east"}]
  }'
curl -s -L -XPOST "http://localhost:8091/influxdb/v2/acl/grants" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "database": {"match": "exact", "value": "datacenters"},
    "tags": [{"match": "exact", "key": "dc", "value": "west"}],
    "permissions": ["read", "write"],
    "roles": [{"name": "west"}]
  }'
Grant option 4: specific series within the database

To guarantee that both roles only have access to the network measurement and that the east user uses the tag dc=east and the west user uses the tag dc=west, we need to make two separate grant calls:

curl -s -L -XPOST "http://localhost:8091/influxdb/v2/acl/grants" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "database": {"match": "exact", "value": "datacenters"},
    "measurement": {"match": "exact", "value": "network"},
    "tags": [{"match": "exact", "key": "dc", "value": "east"}],
    "permissions": ["read", "write"],
    "roles": [{"name": "east"}]
  }'
curl -s -L -XPOST "http://localhost:8091/influxdb/v2/acl/grants" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "database": {"match": "exact", "value": "datacenters"},
    "measurement": {"match": "exact", "value": "network"},
    "tags": [{"match": "exact", "key": "dc", "value": "west"}],
    "permissions": ["read", "write"],
    "roles": [{"name": "west"}]
  }'

Now, when a user in the east role writes to the network measurement, it must include the tag dc=east, and when the west user writes to network, it must include the tag dc=west. Note that this is only the requirement of the presence of that tag; dc=east,foo=bar will also be accepted.

If a user is in both the east and west roles, they must write points with either dc=east or dc=west. When they query data, they will be able to read points tagged with dc=east or dc=west.