How to Build a Custom Kubernetes Authentication Webhook with GitHub and LDAP

Authentication Overview

In Kubernetes the API server is the central component. Every request passes through three stages: Authentication, Authorization, and AdmissionControl. This article focuses on the Authentication stage.

Authentication Plugins

Kubernetes supports many authentication plugins such as X509 certificates, static tokens, ServiceAccount, OpenID, and Webhook. The article demonstrates the use of a Webhook to delegate authentication to external services.

Developing a Webhook Service

The example is written in Go (1.17.3) and runs against Kubernetes v1.22.3 on CentOS 7.6.

Webhook Specification

The webhook must expose an HTTPS POST endpoint that receives a

TokenReview

object and returns a

TokenReview

with the authentication result.

<code>{
  "apiVersion": "authentication.k8s.io/v1beta1",
  "kind": "TokenReview",
  "spec": { "token": "<持有者令牌>" }
}</code>

If authentication succeeds, the API server expects a response like:

<code>{
  "apiVersion": "authentication.k8s.io/v1beta1",
  "kind": "TokenReview",
  "status": {
    "authenticated": true,
    "user": {
      "username": "[email protected]",
      "uid": "42",
      "groups": ["developers", "qa"],
      "extra": { "extrafield1": ["extravalue1", "extravalue2"] }
    }
  }
}</code>

If authentication fails:

<code>{
  "apiVersion": "authentication.k8s.io/v1beta1",
  "kind": "TokenReview",
  "status": { "authenticated": false }
}</code>

Project Structure

Create the project directory and initialize

go.mod

.

webhook.go

implements the HTTP handler that parses the

TokenReview

, extracts the token type, and calls the appropriate authentication function.

github.go

validates a GitHub token by calling the GitHub API.

ldap.go

authenticates against an OpenLDAP server and returns the groups of the user.

main.go

starts the HTTP server on a configurable port.

Token Formats

GitHub:

github:<token>

LDAP:

ldap:<username>:<password>

Deploying the Webhook

Create a kubeconfig‑style JSON file (webhook-config.json) that points to the webhook service and add the flag

--authentication-token-webhook-config-file

to the kube‑apiserver manifest.

<code># mkdir /etc/kubernetes/webhook
# cat >> webhook-config.json <<EOF
{
  "kind": "Config",
  "apiVersion": "v1",
  "clusters": [
    {
      "name": "github-authn",
      "cluster": { "server": "http://10.0.4.9:9999/auth" }
    }
  ],
  "users": [
    {
      "name": "authn-apiserver",
      "user": { "token": "secret" }
    }
  ],
  "contexts": [
    {
      "name": "webhook",
      "context": { "cluster": "github-authn", "user": "authn-apiserver" }
    }
  ],
  "current-context": "webhook"
}
EOF</code>

Mount the file into the apiserver pod (e.g., via a hostPath volume) and restart the component.

Testing GitHub Authentication

Generate a personal access token on GitHub (see image below), add it to

~/.kube/config

as

token: github:…

, and run

kubectl get po --user=joker

. The webhook logs show

auth by github success

.

Testing LDAP Authentication

Install OpenLDAP, create a base DN, add a user and a group, then configure the token

ldap:jack:123456

in the kubeconfig. After running

kubectl get po --user=jack

the webhook logs show

auth by ldap success

.

Conclusion

Using a webhook makes it easy to integrate Kubernetes authentication with existing enterprise account systems, but the example is simplistic; for production use a more robust solution such as Dex.