You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit e7b6abf
Browse filesBrowse the repository at this point in the historyBrowse files
docs(v2): opt-in authorization for evaluation APIs
Document authorization.exclude.evaluation/ofrep defaults.
Covers the authentication prerequisite for enforcement.
closes#426
Signed-off-by: Roman Dmytrenko <rdmytrenko@gmail.com>
Copy file name to clipboardExpand all lines: docs/v2/configuration/authorization.mdx
+63-2Lines changed: 63 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,7 +12,7 @@ authorization:
12
12
required: true
13
13
```
14
14
15
-
When authorization is set to `required`, the API will ensure valid credentials are present on all management API requests.
15
+
When authorization is set to `required`, the API will ensure valid credentials are present on management API requests. Evaluation and OFREP endpoints are excluded by default. See [Evaluation and OFREP Exclusions](#evaluation-and-ofrep-exclusions) to opt in to enforcement.
16
16
17
17
<Info>
18
18
Once authorization has been set to `required: true` all management API routes will require a valid authentication session as well.
@@ -21,6 +21,41 @@ The UI will require a session-compatible authentication method (e.g. OIDC) to be
21
21
22
22
</Info>
23
23
24
+
## Evaluation and OFREP Exclusions
25
+
26
+
Evaluation (`/evaluate/v1` and `/client/v2` snapshot/stream) and OFREP (`/ofrep`) endpoints bypass authorization by default, even when `authorization.required` is `true`.
27
+
28
+
To enforce authorization on evaluation or OFREP, set the corresponding exclusion option to `false`:
29
+
30
+
```yaml
31
+
authorization:
32
+
required: true
33
+
exclude:
34
+
evaluation: false
35
+
ofrep: false
36
+
```
37
+
38
+
<Note>
39
+
Sections of the API excluded from authentication always skip authorization as
40
+
well, since there is no identity to evaluate policy against. To enforce
41
+
authorization on evaluation or OFREP, you must also require authentication for
42
+
those sections by setting `authentication.exclude.evaluation` and
43
+
`authentication.exclude.ofrep`to `false`.
44
+
</Note>
45
+
46
+
When enforced, evaluation requests use the `evaluate` action instead of `read`. This lets you grant evaluation without granting management reads, for example with namespace-scoped tokens:
47
+
48
+
```rego
49
+
allow if {
50
+
input.request.action == "evaluate"
51
+
input.request.scope == "namespace"
52
+
input.request.environment == "production"
53
+
input.request.namespace == "frontend"
54
+
}
55
+
```
56
+
57
+
See [Configuration Overview](/v2/configuration/overview#authorization) for the full list of options.
58
+
24
59
## Backends
25
60
26
61
Flipt uses [Open Policy Agent (OPA)](https://www.openpolicyagent.org/) to enforce authorization policies. OPA is a general-purpose policy engine that can be used to enforce policies across the stack.
@@ -101,6 +136,30 @@ authorization:
101
136
poll_interval: "1m"
102
137
```
103
138
139
+
### Helper Functions
140
+
141
+
To make it easier to write policies, Flipt provides a set of helper functions that are available to be used for the `input` field.
142
+
143
+
`flipt.is_auth_method(input, method)`
144
+
145
+
The helper function `flipt.is_auth_method(input, method)` can be used to check if the request was authenticated using the specified method.
146
+
147
+
The `method` parameter is the authentication method name as it is registered in Flipt, e.g. `oidc`, `token`, `kubernetes`, `github`, `jwt` (`k8s` is accepted as an alias for `kubernetes`).
148
+
149
+
Example:
150
+
151
+
```rego policy.rego
152
+
package flipt.authz.v2
153
+
154
+
import rego.v1
155
+
156
+
default allow := false
157
+
158
+
allow if {
159
+
flipt.is_auth_method(input, "jwt")
160
+
}
161
+
```
162
+
104
163
## Key Differences from v1
105
164
106
165
Flipt v2 authorization introduces several important changes:
@@ -145,11 +204,13 @@ v2 uses a simplified request structure with `scope` field:
145
204
"scope": "namespace", // or "environment"
146
205
"environment": "production",
147
206
"namespace": "frontend",
148
-
"action": "update"
207
+
"action": "update" // create, read, update, delete, or evaluate
149
208
}
150
209
}
151
210
```
152
211
212
+
The `evaluate` action is used for evaluation, snapshot, and OFREP requests when those endpoints are not excluded from authorization. Use it to grant evaluation without granting management reads.
| authorization.required | Enable or disable authorization validation on requests | false | v2.0.0 |
405
+
| authorization.exclude.evaluation | Exclude evaluation APIs (/evaluate/v1 and /client/v2 snapshot/stream) from authorization checks | true | v2.14.0 |
406
+
| authorization.exclude.ofrep | Exclude OFREP API (/ofrep) from authorization checks | true | v2.14.0 |
407
+
408
+
#### Authorization Exclusions for Evaluation
409
+
410
+
By default, evaluation and OFREP endpoints bypass authorization checks even when `authorization.required` is set to `true`. This preserves backward compatibility.
411
+
412
+
To enforce authorization on evaluation or OFREP, set the corresponding exclusion option to `false`:
Sections of the API excluded from authentication always skip authorization as
431
+
well, since there is no identity to evaluate policy against. To enforce
432
+
authorization on evaluation or OFREP, you must also require authentication for
433
+
those sections by setting `authentication.exclude.evaluation` and
434
+
`authentication.exclude.ofrep`to `false`.
435
+
</Note>
436
+
437
+
When enforced, evaluation requests carry the `evaluate` action (instead of `read`), so you can grant evaluation without granting management reads. See [Authorization](/v2/configuration/authorization) for example policies.
0 commit comments