Add FGA guide #1173
Add FGA guide #1173
Conversation
rbetts
left a comment
rbetts
left a comment
There was a problem hiding this comment.
I found the scenario approach very useful. I left a few minor comments; otherwise, has my approval, fwiw.
|
|
||
| ### Concepts | ||
|
|
||
| To use fine-grained authorization (hereafter "FGA"), you must first enable authentication in your configuration file. |
There was a problem hiding this comment.
How do I enable auth in the configuration file - link to other doc here?
There was a problem hiding this comment.
@rkuchan would you mind pushing a commit to add this and the other link that Ryan suggested?
| 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.) |
| 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. |
There was a problem hiding this comment.
That was left over from a previous iteration of the guide. I've removed it now.
| ``` | ||
|
|
||
| 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. |
| 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_. |
There was a problem hiding this comment.
s/series/tags/ the series is made up of the database, measurement, and tags.
| 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. |
There was a problem hiding this comment.
should read "access to series". FGA controls access to series, we should make sure the wording is consistent.
| 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. |
There was a problem hiding this comment.
"selectors" is probably best avoided, we have been using "selector" internally to refer to the combination of database, measurement, and tags matches. I would change this whole line, something along the lines of:
Restrictions limit access to the series that match the database, measurement, and tags specified. The different access permissions (currently just "read" and "write") can be restricted independently depending on the scenario.
| 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_. |
There was a problem hiding this comment.
Again, maybe update the wording:
Grants will allow access, according to the listed permissions, to restricted series for the users and roles specified.
|
|
||
| ### Modifying grants and restrictions | ||
|
|
||
| To configure FGA, you will need access to the meta nodes' HTTP ports (which run on port 8089 by default). |
There was a problem hiding this comment.
It's actually 8091, 8089 is the RPC port.
| }' | ||
| ``` | ||
|
|
||
| After applying this restriction and before applying any grants, the east and west users will not be authorized to write to the database. |
There was a problem hiding this comment.
They will not be authorized to read, either.
|
|
||
| ##### 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. |
| ##### 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. |
There was a problem hiding this comment.
I would replace "coarse-grained" with "broad", and "fine-grained" with "narrow" here. The whole API is fine-grained authorization, and it's probably best to not re-use terminology.
| 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. |
There was a problem hiding this comment.
Don't mention regex, we might avoid it in favor of exact, prefix, and eventually dynamic. Only the first two will be allowed for now, though.
|
Thanks for the good feedback @joelegasse. |
|
Links added, @mark-rushakoff. Thank you for putting this together! |
No description provided.