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.

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

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

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

If authentication fails:

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

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.

# 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

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.