Reference Documentation

Design docs, concept definitions, and references for APIs and CLIs.

Documentation for Kubernetes v1.6 is no longer actively maintained. The version you are currently viewing is a static snapshot. For up-to-date documentation, see the latest version.

Edit This Page

Overview

Learn more about Kubernetes authorization, including details about creating policies using the supported authorization modules.

In Kubernetes, you must be authenticated (logged in) before your request can be authorized (granted permission to access). For information about authentication, see Accessing Control Overview.

Kubernetes expects attributes that are common to REST API requests. This means that Kubernetes authorization works with existing organization-wide or cloud-provider-wide access control systems which may handle other APIs besides the Kubernetes API.

Determine Whether a Request is Allowed or Denied

Kubernetes authorizes API requests using the API server. It evaluates all of the request attributes against all policies and allows or denies the request. All parts of an API request must be allowed by some policy in order to proceed. This means that permissions are denied by default.

(Although Kubernetes uses the API server, access controls and policies that depend on specific fields of specific kinds of objects are handled by Admission Controllers.)

When multiple authorization modules are configured, each is checked in sequence, and if any module authorizes the request, then the request can proceed. If all modules deny the request, then the request is denied (HTTP status code 403).

Review Your Request Attributes

Kubernetes reviews only the following API request attributes:

Determine the Request Verb

To determine the request verb for a resource API endpoint, review the HTTP verb used and whether or not the request acts on an individual resource or a collection of resources:

HTTP verb request verb
POST create
GET, HEAD get (for individual resources), list (for collections)
PUT update
PATCH patch
DELETE delete (for individual resources), deletecollection (for collections)

Kubernetes sometimes checks authorization for additional permissions using specialized verbs. For example:

Authorization Modules

Custom Modules

Other implementations can be developed fairly easily. The APIserver calls the Authorizer interface:

type Authorizer interface {
  Authorize(a Attributes) error
}

to determine whether or not to allow each API action.

An authorization plugin is a module that implements this interface. Authorization plugin code goes in pkg/auth/authorizer/$MODULENAME.

An authorization module can be completely implemented in go, or can call out to a remote authorization service. Authorization modules can implement their own caching to reduce the cost of repeated authorization calls with the same or similar arguments. Developers should then consider the interaction between caching and revocation of permissions.

Checking API Access

Kubernetes exposes the subjectaccessreviews.v1.authorization.k8s.io resource as a normal resource that allows external access to API authorizer decisions. No matter which authorizer you choose to use, you can issue a POST with a SubjectAccessReview just like the webhook authorizer to the apis/authorization.k8s.io/v1/subjectaccessreviews endpoint and get back a response. For instance:

kubectl create --v=8 -f -  << __EOF__
{
  "apiVersion": "authorization.k8s.io/v1",
  "kind": "SubjectAccessReview",
  "spec": {
    "resourceAttributes": {
      "namespace": "kittensandponies",
      "verb": "get",
      "group": "unicorn.example.org",
      "resource": "pods"
    },
    "user": "jane",
    "group": [
      "group1",
      "group2"
    ],
    "extra": {
      "scopes": [
        "openid",
        "profile"
      ]
    }
  }
}
__EOF__

--- snip lots of output ---

I0913 08:12:31.362873   27425 request.go:908] Response Body: {"kind":"SubjectAccessReview","apiVersion":"authorization.k8s.io/v1","metadata":{"creationTimestamp":null},"spec":{"resourceAttributes":{"namespace":"kittensandponies","verb":"GET","group":"unicorn.example.org","resource":"pods"},"user":"jane","group":["group1","group2"],"extra":{"scopes":["openid","profile"]}},"status":{"allowed":true}}
subjectaccessreview "" created

This is useful for debugging access problems, in that you can use this resource to determine what access an authorizer is granting.

Using Flags for Your Authorization Module

You must include a flag in your policy to indicate which authorization module your policies include:

The following flags can be used: - --authorization-mode=ABAC Attribute-Based Access Control (ABAC) mode allows you to configure policies using local files. - --authorization-mode=RBAC Role-based access control (RBAC) mode allows you to create and store policies using the Kubernetes API. - --authorization-mode=Webhook WebHook is an HTTP callback mode that allows you to manage authorization using a remote REST. - --authorization-mode=AlwaysDeny This flag blocks all requests. Use this flag only for testing. - --authorization-mode=AlwaysAllow This flag allows all requests. Use this flag only if you do not require authorization for your API requests.

You can choose more than one authorization module. If one of the modes is AlwaysAllow, then it overrides the other modes and all API requests are allowed.

Versioning

For version 1.2, clusters created by kube-up.sh are configured so that no authorization is required for any request.

As of version 1.3, clusters created by kube-up.sh are configured so that the ABAC authorization modules are enabled. However, its input file is initially set to allow all users to do all operations. The cluster administrator needs to edit that file, or configure a different authorizer to restrict what users can do.

What’s next

Analytics

Create an Issue Edit this Page