ContainerImage.Pinniped/site/content/docs/howto/concierge/configure-concierge-webhook.md

title	description	cascade	menu
Configure the Pinniped Concierge to validate webhook tokens	Set up webhook-based token authentication on an individual Kubernetes cluster.	layout docs	docs name weight parent Webhook Authentication 50 howto-configure-concierge

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

Prerequisites

Before starting, you should have the [command-line tool installed]({{< ref "install-cli" >}}) locally and [Concierge running in your cluster]({{< ref "install-concierge" >}}).

You should also have a custom TokenReview webhook endpoint:

• Your webhook endpoint must handle the authentication.k8s.io/v1 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:

apiVersion: authentication.concierge.pinniped.dev/v1alpha1
kind: WebhookAuthenticator
metadata:
  name: my-webhook-authenticator
spec:
  # HTTPS endpoint to be called as a webhook
  endpoint: https://my-webhook.example.com/any/path
  tls:
    # 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
clusters:
- cluster:
    certificate-authority-data: LS0tLS[...]
    server: https://my-kubernetes-api-endpoint.example.com:59986
  name: pinniped
contexts:
- context:
    cluster: pinniped
    user: pinniped
  name: pinniped
users:
- name: pinniped
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      command: /usr/local/bin/pinniped
      args:
      - login
      - oidc
      - login
      - static
      - --enable-concierge
      - --concierge-api-group-suffix=pinniped.dev
      - --concierge-authenticator-name=my-webhook-authenticator
      - --concierge-authenticator-type=webhook
      - --concierge-endpoint=https://127.0.0.1:59986
      - --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