Kubernetes Authentication Webhook

This post analyzes the Webhook-based Kubernetes Authentication technique.

1. Kubernetes Authentication Webhook

Kubernetes provides a Webhook-based authentication technique. The Webhook-based authentication technique has the advantage of being able to integrate with various forms of external authentication servers. [Figure 1] shows the Webhook-based Kubernetes authentication technique. The Kubernetes Client (kubectl) obtains a Token from the external authentication server through an authentication process. The Kubernetes Client that has obtained the Token passes the Token to the Kubernetes API Server through the Authorization: Bearer $TOKEN Header. The Kubernetes API Server that has received the Token is authenticated by passing a TokenReview Object containing the Token information to the external authentication server.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

apiVersion: v1
kind: Config
# clusters refers to the remote authentication server.
clusters:
  - name: authentication-server
    cluster:
      certificate-authority: authentication-server-ca-crt-path
      server: https://authentication-server.ssup2.com/authenticate

# users refers to the API server's webhook configuration.
users:
  - name: k8s-api-server
    user:
      client-certificate: k8s-api-server-crt-path
      client-key: k8s-api-server-crt-key-path

current-context: webhook
contexts:
- context:
    cluster: authentication-server
    user: k8s-api-server
  name: webhook

The way to configure an external authentication server for the Kubernetes API Server is to pass a Webhook Config file through the --authentication-token-webhook-config-file Option. The Webhook Config file has the same format as a kubeconfig file, but its configuration contents are different. [Text 1] shows the Webhook Config. The Cluster entry stores information related to the external authentication server, and the User entry stores the certificate information the Kubernetes API Server uses when communicating with the external authentication server.

1
2
3
4
5
6
7
8

{
  "apiVersion": "authentication.k8s.io/v1",
  "kind": "TokenReview",
  "spec": {
    "token": "<token>",
    "audiences": ["https://ssup2.com", "https://ssup3.com"]
  }
}

To pass the Token to the external authentication server, the Kubernetes API Server internally creates a TokenReview Object and stores the Token in the Spec of the TokenReview Object. The Kubernetes API Server then passes the created TokenReview Object to the external authentication server. [Text 2] shows the TokenReview Object that the Kubernetes API Server passes to the external authentication server.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "apiVersion": "authentication.k8s.io/v1",
  "kind": "TokenReview",
  "status": {
    "authenticated": true,
    "user": {
      "username": "ssup2",
      "groups": ["system:masters", "kube"]
    },
    "audiences": ["https://ssup2.com", "https://ssup3.com"]
  }
}

1
2
3
4
5
6
7
8

{
  "apiVersion": "authentication.k8s.io/v1",
  "kind": "TokenReview",
  "status": {
    "authenticated": false,
    "error": "Credentials are expired"
  }
}

If the Token is valid, the external authentication server that has received the TokenReview Object stores the information that authentication succeeded, the name of the User the Token authenticates, and the Group information the User belongs to in the Status of the TokenReview Object, and passes it to the Kubernetes API Server. If the Token is not valid, it stores the information that authentication failed in the Status of the TokenReview Object and passes it to the Kubernetes API Server. [Text 3] shows the Status of the TokenReview Object set by the external authentication server when the Token is valid, and [Text 4] shows the Status of the TokenReview Object set by the external authentication server when the Token is not valid.

2. References

• Kubernetes Authenticating - Webhook Token Authentication : https://kubernetes.io/docs/reference/access-authn-authz/authentication/#webhook-token-authentication
• Complete Guide to k8s Authentication #4 - Webhook Authentication : https://coffeewhale.com/kubernetes/authentication/webhook/2020/05/05/auth04/