kubehook

Kubehook is a webhook token authentication service for Kubernetes. It provides one API endpoint to generate JSON Web Tokens, and another to validate tokens on behalf of Kubernetes.

Generating a token

Kubehook provides a small web UI to request tokens:

Once a token has been requested the UI explains how to use it:

Kubehook can optionally be configured with a set of Kubernetes clusters to automatically configure. When run with the --kubecfg-template users can simply download a ~/.kube/config file preconfigured with well known clusters.

Deploying Kubehook

Kubehook assumes it is running behind a reverse proxy such as nginx that terminates TLS and authenticates callers. Tokens will be generated for the username provided via a configurable HTTP header - X-Forwarded-User by default.

CFG=$(mktemp -d /tmp/kubehook.XXXX)
cat <<EOF >$CFG/template
apiVersion: v1
kind: Config
clusters:
- name: kubehook
  cluster:
    certificate-authority-data: REDACTED
    server: https://kubehook.example.org
EOF

docker run -d \
  -p 10003:10003 \
  -v $CFG:/cfg \
  -e "KUBEHOOK_SECRET=secret" \
  "planetlabs/kubehook:latest" \
  /kubehook --kubecfg-template /cfg/template

Kubehook supports the following arguments:

$ docker run planetlabs/kubehook:latest /kubehook --help
usage: kubehook [<flags>] <secret>

Authenticates Kubernetes users via JWT tokens.

Flags:
      --help                   Show context-sensitive help (also try --help-long
                               and --help-man).
      --listen=":10003"        Address at which to expose HTTP webhook.
  -d, --debug                  Run with debug logging.
      --shutdown-grace-period=1m  
                               Wait this long for sessions to end before
                               shutting down.
      --audience="github.com/planetlabs/kubehook"  
                               Audience for JWT HMAC creation and verification.
      --user-header="X-Forwarded-User"  
                               HTTP header specifying the authenticated user
                               sending a token generation request.
      --max-lifetime=168h0m0s  Maximum allowed JWT lifetime, in Go's
                               time.ParseDuration format.
      --kubecfg-template=KUBECFG-TEMPLATE  
                               A kubecfg file containing clusters to populate
                               with a user and contexts.
      --client-ca=CLIENT-CA    If set, enables mutual TLS and specifies the path to CA file
                               to use when validating client connections.
      --client-ca-subject=CLIENT-CA-SUBJECT
                               If set, requires that the client CA matches the provided
                               subject (requires --client-ca).
      --tls-cert=TLS-CERT      If set, enables TLS and specifies the path to TLS
                               certificate to use for HTTPS server (requires --tls-key).
      --tls-key=TLS-KEY        Path to TLS key to use for HTTPS server (requires
                               --tls-cert).

Args:
  <secret>  Secret for JWT HMAC signature and verification.

Kubehook is stateless and uses a HMAC shared secret. This means that a token generated by one Kubehook instance can be validated by another, as long as they are configured with the same secret. Note that you must also configure webhook token authentication at the API server before token based authentication will work.

Usage

To generate a token with a 24 hour lifetime:

$ export USERNAME=cooluser
$ curl -i -X POST \
	-H "Content-Type: application/json" \
	-H "X-Forwarded-User: ${USERNAME}" \
	-d "{\"lifetime\": \"24h\"}" \  # Lifetime is parsed via https://golang.org/pkg/time/#ParseDuration
	http://localhost:10003/generate
  
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Mon, 11 Dec 2017 08:00:14 GMT
Content-Length: 208

{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJnaXRodWIuY29tL25lZ3ova3ViZWhvb2siLCJleHAiOjE1MTMwNjU2MTQsIm5iZiI6MTUxMjk3OTIxNCwic3ViIjoiY29vbHVzZXIifQ.ylxC6wFglLBI0_0e0LQftwuqI95mb0L5Wjnp5aCmPHU"}

To download a ~/kube/config file (Kubehook must be running with --kubecfg-template):

$ export USERNAME=cooluser
$ curl -X GET \
	-H "X-Forwarded-User: ${USERNAME}" \
	http://localhost:10003/kubecfg?lifetime=24h > ~/.kube/config

To validate a token (i.e. the endpoint called by the Kubernetes API server):

$ export TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJnaXRodWIuY29tL25lZ3ova3ViZWhvb2siLCJleHAiOjE1MTMwNjU2MTQsIm5iZiI6MTUxMjk3OTIxNCwic3ViIjoiY29vbHVzZXIifQ.ylxC6wFglLBI0_0e0LQftwuqI95mb0L5Wjnp5aCmPHU
$ curl -i -X POST \
    -H "Content-Type: application/json" \
    -d "{\"apiVersion\":\"authentication.k8s.io/v1beta1\",\"kind\":\"TokenReview\",\"spec\":{\"token\":\"${TOKEN}\"}}" \
    http://localhost:10003/authenticate

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Mon, 11 Dec 2017 08:02:10 GMT
Content-Length: 239

{"kind":"TokenReview","apiVersion":"authentication.k8s.io/v1beta1","metadata":{"creationTimestamp":"2017-12-11T08:02:10Z"},"spec":{},"status":{"authenticated":true,"user":{"username":"cooluser","uid":"github.com/planetlabs/kubehook/cooluser"}}}