From fcfc67678696faed9fa0be1534181db2e3c1a8f3 Mon Sep 17 00:00:00 2001 From: Andrew Chen Date: Tue, 23 May 2017 13:56:57 -0700 Subject: [PATCH] Reimplement #3767 --- _data/reference.yml | 1 + docs/admin/authorization/abac.md | 155 +++++++++++++++++++++++++++++++ 2 files changed, 156 insertions(+) create mode 100644 docs/admin/authorization/abac.md diff --git a/_data/reference.yml b/_data/reference.yml index b5dd77a3aa..1513ca464d 100644 --- a/_data/reference.yml +++ b/_data/reference.yml @@ -16,6 +16,7 @@ toc: - title: Authorization section: - docs/admin/authorization/index.md + - docs/admin/authorization/abac.md - docs/admin/authorization/rbac.md - docs/reference/deprecation-policy.md diff --git a/docs/admin/authorization/abac.md b/docs/admin/authorization/abac.md new file mode 100644 index 0000000000..c4c398f5a5 --- /dev/null +++ b/docs/admin/authorization/abac.md @@ -0,0 +1,155 @@ +--- +assignees: +- erictune +- lavalamp +- deads2k +- liggitt +title: ABAC Mode +--- + +{% capture overview %} +Attribute-based access control (ABAC) defines an access control paradigm whereby access rights are granted to users through the use of policies which combine attributes together. +{% endcapture %} + +{% capture body %} +## Policy File Format + +For mode `ABAC`, also specify `--authorization-policy-file=SOME_FILENAME`. + +The file format is [one JSON object per line](http://jsonlines.org/). There +should be no enclosing list or map, just one map per line. + +Each line is a "policy object". A policy object is a map with the following +properties: + + - Versioning properties: + - `apiVersion`, type string; valid values are "abac.authorization.kubernetes.io/v1beta1". Allows versioning and conversion of the policy format. + - `kind`, type string: valid values are "Policy". Allows versioning and conversion of the policy format. + - `spec` property set to a map with the following properties: + - Subject-matching properties: + - `user`, type string; the user-string from `--token-auth-file`. If you specify `user`, it must match the username of the authenticated user. + - `group`, type string; if you specify `group`, it must match one of the groups of the authenticated user. `system:authenticated` matches all authenticated requests. `system:unauthenticated` matches all unauthenticated requests. + - Resource-matching properties: + - `apiGroup`, type string; an API group. + - Ex: `extensions` + - Wildcard: `*` matches all API groups. + - `namespace`, type string; a namespace. + - Ex: `kube-system` + - Wildcard: `*` matches all resource requests. + - `resource`, type string; a resource type + - Ex: `pods` + - Wildcard: `*` matches all resource requests. + - Non-resource-matching properties: + - `nonResourcePath`, type string; non-resource request paths. + - Ex: `/version` or `/apis` + - Wildcard: + - `*` matches all non-resource requests. + - `/foo/*` matches all subpaths of `/foo/`. + - `readonly`, type boolean, when true, means that the policy only applies to get, list, and watch operations. + +**NOTES:** An unset property is the same as a property set to the zero value for its type +(e.g. empty string, 0, false). However, unset should be preferred for +readability. + +In the future, policies may be expressed in a JSON format, and managed via a +REST interface. + +## Authorization Algorithm + +A request has attributes which correspond to the properties of a policy object. + +When a request is received, the attributes are determined. Unknown attributes +are set to the zero value of its type (e.g. empty string, 0, false). + +A property set to `"*"` will match any value of the corresponding attribute. + +The tuple of attributes is checked for a match against every policy in the +policy file. If at least one line matches the request attributes, then the +request is authorized (but may fail later validation). + +To permit any authenticated user to do something, write a policy with the +group property set to `"system:authenticated"`. + +To permit any unauthenticated user to do something, write a policy with the +group property set to `"system:unauthenticated"`. + +To permit a user to do anything, write a policy with the apiGroup, namespace, +resource, and nonResourcePath properties set to `"*"`. + +## Kubectl + +Kubectl uses the `/api` and `/apis` endpoints of api-server to negotiate +client/server versions. To validate objects sent to the API by create/update +operations, kubectl queries certain swagger resources. For API version `v1` +those would be `/swaggerapi/api/v1` & `/swaggerapi/experimental/v1`. + +When using ABAC authorization, those special resources have to be explicitly +exposed via the `nonResourcePath` property in a policy (see [examples](#examples) below): + +* `/api`, `/api/*`, `/apis`, and `/apis/*` for API version negotiation. +* `/version` for retrieving the server version via `kubectl version`. +* `/swaggerapi/*` for create/update operations. + +To inspect the HTTP calls involved in a specific kubectl operation you can turn +up the verbosity: + + kubectl --v=8 version + +## Examples + + 1. Alice can do anything to all resources: + + ```json + {"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "alice", "namespace": "*", "resource": "*", "apiGroup": "*"}} + ``` + 2. Kubelet can read any pods: + + ```json + {"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "kubelet", "namespace": "*", "resource": "pods", "readonly": true}} + ``` + 3. Kubelet can read and write events: + + ```json + {"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "kubelet", "namespace": "*", "resource": "events"}} + ``` + 4. Bob can just read pods in namespace "projectCaribou": + + ```json + {"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"user": "bob", "namespace": "projectCaribou", "resource": "pods", "readonly": true}} + ``` + 5. Anyone can make read-only requests to all non-resource paths: + + ```json + {"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"group": "system:authenticated", "readonly": true, "nonResourcePath": "*"}} + {"apiVersion": "abac.authorization.kubernetes.io/v1beta1", "kind": "Policy", "spec": {"group": "system:unauthenticated", "readonly": true, "nonResourcePath": "*"}} + ``` + +[Complete file example](http://releases.k8s.io/{{page.githubbranch}}/pkg/auth/authorizer/abac/example_policy_file.jsonl) + +## A quick note on service accounts + +A service account automatically generates a user. The user's name is generated +according to the naming convention: + +```shell +system:serviceaccount:: +``` +Creating a new namespace also causes a new service account to be created, of +this form: + +```shell +system:serviceaccount::default +``` + +For example, if you wanted to grant the default service account in the +kube-system full privilege to the API, you would add this line to your policy +file: + +```json +{"apiVersion":"abac.authorization.kubernetes.io/v1beta1","kind":"Policy","spec":{"user":"system:serviceaccount:kube-system:default","namespace":"*","resource":"*","apiGroup":"*"}} +``` + +The apiserver will need to be restarted to pickup the new policy lines. + +{% endcapture %} +{% include templates/concept.md %} \ No newline at end of file