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
Copy file name to clipboardexpand all lines: docs/CedarIntroduction.md
+9-3
Original file line number
Diff line number
Diff line change
@@ -64,7 +64,7 @@ forbid (
64
64
65
65
How does Cedar know if a principal is in a group?
66
66
When evaluating a request, Cedar has several inputs.
67
-
(You can play with some examples in the [Cedar Playground](https://www.cedarpolicy.com/en/playground)):
67
+
(You can play with some examples for Kubernetes in the [Cedar Playground](https://www.cedarpolicy.com/en/playground)):
68
68
69
69
* A JSON list of entity structures to be considered
70
70
* A principal identifier, which must be in the entities list
@@ -114,12 +114,12 @@ If an entity is a member of another entity type, the Entities list must say so.
114
114
```
115
115
116
116
Given the above input, the entity with the id `507B11AD-4DE0-44B1-AB7C-99C0C04854B1` and the name `alice` has a `parents` reference to the Group type named `viewers`, so in this case Alice is a member of the group `viewers`.
117
-
Cedar also supports membership on resource entities and verbs, but we don't use them in this project.
117
+
Cedar also supports membership on resource entities and verbs, which we'll get to later.
118
118
119
119
## Schema
120
120
121
121
When writing policy how do you know what is a valid attribute of a type so you can write policy against it?
122
-
Cedar policy supports a [schema] defining all valid entities (principals and resources), their attributes, actions, and which actions apply to which entities (principal and resources).
122
+
Cedar policy supports a [schema] defining all valid entities (principals and resources), their attributes, actions, which actions apply to which entities (principal and resources), and what the context structure for a given action is.
123
123
You can see the Cedar schema used for Kubernetes authorization this project in [human][authz_human_schema] and [json][authz_json_schema] format.
Copy file name to clipboardexpand all lines: docs/CedarSchemas.md
+86-18
Original file line number
Diff line number
Diff line change
@@ -12,7 +12,7 @@ The referenced schemas are primarily created to document the entity shapes and a
12
12
13
13
## Authorizer cedarschema
14
14
15
-
For the full authorization schema, see [cedarschema/k8s-authorization.cedarschema](../cedarschema/k8s-authorization.cedarschema).
15
+
For the authorization schema, see [cedarschema/k8s-authorization.cedarschema](../cedarschema/k8s-authorization.cedarschema).
16
16
17
17
### Principals
18
18
@@ -30,10 +30,10 @@ This project supports the following Principal entities:
30
30
"extra"?: Set < ExtraAttribute >,
31
31
"name": __cedar::String
32
32
};
33
-
type Extra = {
34
-
"key": __cedar::String,
35
-
"values"?: Set < __cedar::String >
36
-
};
33
+
type Extra = {
34
+
"key": __cedar::String,
35
+
"values"?: Set < __cedar::String >
36
+
};
37
37
```
38
38
* `k8s::ServiceAccount`. When a user's name in a [SubjectAccessReview] starts with `system:serviceaccount:`, the authorizer sets the principal type to `k8s::ServiceAccount` with the following attributes.
39
39
```cedarschema
@@ -70,7 +70,7 @@ permit (
70
70
};
71
71
```
72
72
73
-
We do have a resource group for all readOnly actions. It encompasses `get`/`list`/`watch`, and is called `readOnly`, and only applies to `k8s::Resource` resources.
73
+
We do have an action group for all read-only actions. It encompasses `get`/`list`/`watch`, and is called `readOnly`, and only applies to `k8s::Resource` resources.
74
74
75
75
```cedar
76
76
permit (
@@ -85,15 +85,19 @@ permit (
85
85
86
86
### Resources
87
87
88
-
> Note: `"resource"`, `"k8s::Resource"`, and `"resource.resource`, why the redundancy?!
88
+
> **`"resource"`, `"k8s::Resource"`, and `"resource.resource`, why the redundancy?!**
89
89
>
90
90
> This is an unfortunate naming collision. Cedar policies always have a `resource` as part of the policy.
91
91
> We call Kubernetes typed objects `k8s::Resource` as opposed to the `k8s::NonResourceURL` type, because that's what Kubernetes calls them.
92
92
> And finally, Kubernetes authorization checks refer to they type of object as a `resource`, along with the object's `apiGroup`, `namespace`, `name`, etc.
93
93
94
94
We define two primary resource types for this authorizer:
95
95
96
-
*`NonResourceURL`: This is for non-resource requests made to the Kubernetes API server. Examples include `/healthz`, `/livez`, `/metrics`, and subpaths. (Hint: run `kubectl get --raw /` to see others) Paths can match a `*` on the suffix.
96
+
*`NonResourceURL`: This is for non-resource requests made to the Kubernetes API server.
97
+
Examples include `/healthz`, `/livez`, `/metrics`, and subpaths
98
+
(Hint: run `kubectl get --raw /` to see others).
99
+
A request's path is also used as the identifier in the entity list when evaluated for authorization.
100
+
Paths can match a `*` on the suffix.
97
101
```cedarschema
98
102
entity NonResourceURL = {
99
103
"path": __cedar::String
@@ -117,7 +121,8 @@ We define two primary resource types for this authorizer:
117
121
resource == k8s::NonResourceURL::"/version"
118
122
);
119
123
```
120
-
* `Resource`: This is for resource requests made to the Kubernetes API server. Entity IDs on resources are the constructed URL path being made for the request.
124
+
* `Resource`: This is for resource requests made to the Kubernetes API server.
125
+
Entity IDs on resources are the constructed URL path being made for the request.
121
126
```cedarschema
122
127
entity Resource = {
123
128
"apiGroup": __cedar::String,
@@ -166,7 +171,7 @@ We define two primary resource types for this authorizer:
166
171
};
167
172
```
168
173
169
-
`Resource` has a `fieldSelector` and `labelSelector` types. These were added in Kubernetes 1.31 behind the [`AuthorizeWithSelectors`][AuthorizeWithSelectors] feature gate so authorizers can enforce that a watch or list request has a field or label selector:
174
+
`Resource` has a `fieldSelector` and `labelSelector` types. These were [added in Kubernetes 1.31][AuthorizeWithSelectors] behind the `AuthorizeWithSelectors` feature gate so authorizers can enforce that a watch or list request has a field or label selector:
This can be used to enforce attribute-based access policies, such as a user can only get/list/watch resources where the label `owner` equals the user's name
192
+
Selectors can be used to enforce attribute-based access policies, such as enforcing that a user can only get/list/watch resources where the label `owner` equals the user's name
188
193
```cedar
189
194
permit (
190
-
principal is User,
195
+
principal is k8s::User,
191
196
action in [k8s::Action::"list", k8s::Action::"watch"],
To make an impersonated request as another user, Kubernetes sends multiple authorization requests to an authorizer: one for each attribute being impersonated: The user's name, the UID (if set), the groups (if set), and the userInfo extra key/value map (entity tags are [not yet supported in cedar-go](https://github.com/cedar-policy/cedar-go/issues/47)). To support this, we define a few types:
228
+
To make an impersonated request as another user, Kubernetes sends multiple authorization requests to an authorizer: one for each attribute being impersonated: The user's name, the UID (if set), the groups (if set), and the userInfo extra key/value map. To support this, we define a few types:
224
229
225
230
*`Group`. This structure is the same from the principal type. This only functions if the user can also impersonate the requested username.:
226
231
```cedar
@@ -255,7 +260,10 @@ To make an impersonated request as another user, Kubernetes sends multiple autho
255
260
```
256
261
* `Extra`: To allow impersonating a principal's key/values extra info, the policy's resource type must be `Extra`. This only functions if the user can also impersonate the requested username.
257
262
```cedarschema
258
-
entity PrincipalUID;
263
+
entity Extra = {
264
+
"key": __cedar::String,
265
+
"values"?: Set < __cedar::String >
266
+
};
259
267
```
260
268
Examples:
261
269
```cedar
@@ -344,10 +352,10 @@ forbid (
344
352
);
345
353
```
346
354
347
-
All admission actions currently apply to any Kubernetes type that have a [`metav1.ObjectMeta`][objmeta] or [`corev1.ListMeta`][listmeta].
355
+
Most admission actions currently apply to any Kubernetes type that have a [`metav1.ObjectMeta`][objmeta].
Until [cedar-go supports entity maps][go-entity-maps], we've manually added `KeyValue` and `KeyValues` types into the `meta::v1` namespace to support key/value labels.
383
+
Until [cedar-go supports entity maps][go-entity-maps], we've manually added `KeyValue` and `KeyValueStringSlice` types into the `meta::v1` namespace to support key/value labels.
375
384
Any Kubernetes types that consist of `map[string]string{}` or `map[string][]string{}` are converted to a Set of KeyValue or KeyValueStringSlice.
The Kubernetes `CONNECT` admission action only applies to a small set of structures that don't appear in the Kubernetes OpenAPI Schema, so we inject them manually:
411
+
```cedarschema
412
+
namespace core::v1 {
413
+
// other types and entities
414
+
entity NodeProxyOptions = {
415
+
"apiVersion": __cedar::String,
416
+
"kind": __cedar::String,
417
+
"path": __cedar::String
418
+
};
419
+
entity PodAttachOptions = {
420
+
"apiVersion": __cedar::String,
421
+
"command": Set < __cedar::String >,
422
+
"container": __cedar::String,
423
+
"kind": __cedar::String,
424
+
"stderr": __cedar::Bool,
425
+
"stdin": __cedar::Bool,
426
+
"stdout": __cedar::Bool,
427
+
"tty": __cedar::Bool
428
+
};
429
+
entity PodExecOptions = {
430
+
"apiVersion": __cedar::String,
431
+
"command": Set < __cedar::String >,
432
+
"container": __cedar::String,
433
+
"kind": __cedar::String,
434
+
"stderr": __cedar::Bool,
435
+
"stdin": __cedar::Bool,
436
+
"stdout": __cedar::Bool,
437
+
"tty": __cedar::Bool
438
+
};
439
+
entity PodPortForwardOptions = {
440
+
"apiVersion": __cedar::String,
441
+
"kind": __cedar::String,
442
+
"ports"?: Set < __cedar::String >
443
+
};
444
+
entity PodProxyOptions = {
445
+
"apiVersion": __cedar::String,
446
+
"kind": __cedar::String,
447
+
"path": __cedar::String
448
+
};
449
+
entity ServiceProxyOptions = {
450
+
"apiVersion": __cedar::String,
451
+
"kind": __cedar::String,
452
+
"path": __cedar::String
453
+
};
454
+
}
455
+
```
456
+
457
+
Policy can be used to forbid proxying to those types:
Copy file name to clipboardexpand all lines: docs/Limitations.md
+2-2
Original file line number
Diff line number
Diff line change
@@ -27,7 +27,7 @@ RBAC would require the following policy to permit a port-forward request.
27
27
apiVersion: rbac.authorization.k8s.io/v1
28
28
kind: ClusterRole
29
29
metadata:
30
-
name: deployment-manager
30
+
name: service-port-forwarder
31
31
rules:
32
32
- apiGroups:
33
33
- ""
@@ -109,7 +109,7 @@ namespace k8s {
109
109
## Expressiveness limitations
110
110
111
111
A core tenet of Cedar is to be analyzable, meaning that the language can verify that a policy is valid and will not error.
112
-
A general `map`/`filter` function on dynamic inputs [is not analyzible][rfc21], and not a candidate for the project.
112
+
A general `map`/`filter` function on dynamic inputs and ordered lists [are not analyzible][rfc21], and not a candidate for Cedar.
113
113
This prevents specifically checking subfields over sets of structures, which is a common Kubernetes policy management requirement.
114
114
Cedar is powered by [automated reasoning], including an [SMT solver], which does not implement loops or map functions.
115
115
Rather than viewing Cedar as a replacement for admission restrictions tools like [Open Policy Agent/Gatekeeper][gatekeeper] or [Kyverno][kyverno], it is best seen as an additional tool for access control enforcement.
0 commit comments