Pinniped Logo

Pinniped Documentation

Configure the Pinniped Concierge to validate webhook tokens

The Concierge can validate arbitrary tokens via an external webhook endpoint using the same validation process as Kubernetes itself.


Before starting, you should have the command-line tool installed locally and Concierge running in your cluster.

You should also have a custom TokenReview webhook endpoint:

  • Your webhook endpoint must handle the TokenReview API.

  • Your webhook must be accessible from the Concierge pod over HTTPS.

Create a WebhookAuthenticator

Create a WebhookAuthenticator describing how to validate tokens using your webhook:

kind: WebhookAuthenticator
  name: my-webhook-authenticator
  # HTTPS endpoint to be called as a webhook
    # base64-encoded PEM CA bundle (optional)
    certificateAuthorityData: "LS0tLS1CRUdJTi[...]"

If you’ve saved this into a file my-webhook-authenticator.yaml, then install it into your cluster using:

kubectl apply -f my-webhook-authenticator.yaml

Generate a kubeconfig file

Generate a kubeconfig file to target the WebhookAuthenticator:

pinniped get kubeconfig \
  --static-token-env MY_CLUSTER_ACCESS_TOKEN \
  > my-cluster.yaml

This creates a kubeconfig YAML file my-cluster.yaml that targets your WebhookAuthenticator using pinniped login static as an ExecCredential plugin.

It should look something like below:

apiVersion: v1
kind: Config
current-context: pinniped
- cluster:
    certificate-authority-data: LS0tLS[...]
  name: pinniped
- context:
    cluster: pinniped
    user: pinniped
  name: pinniped
- name: pinniped
      command: /usr/local/bin/pinniped
      - login
      - oidc
      - login
      - static
      - --enable-concierge
      - --concierge-authenticator-name=my-webhook-authenticator
      - --concierge-authenticator-type=webhook
      - --concierge-endpoint=
      - --concierge-ca-bundle-data=LS0tLS[...]
      - --token-env=MY_CLUSTER_ACCESS_TOKEN

Use the kubeconfig file

Set the $MY_CLUSTER_ACCESS_TOKEN environment variable and use the kubeconfig with kubectl to access your cluster:

MY_CLUSTER_ACCESS_TOKEN=secret-token kubectl --kubeconfig my-cluster.yaml get namespaces

You should see:

  • The pinniped login static command is silently executed automatically by kubectl.

  • The command-line tool sends your token to the Concierge which validates it by making a request to your webhook endpoint.

  • In your shell, you see your clusters namespaces.

    If instead you get an access denied error, you may need to create a ClusterRoleBinding for the username/groups returned by your webhook, for example:

    kubectl create clusterrolebinding my-user-admin --clusterrole edit --user my-username