Pinniped Logo

Pinniped Documentation

Overview

    Background

    Tutorials

    How-to Guides

    Concierge Configuration

    Supervisor Configuration

    Reference

    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.

    Prerequisites

    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 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 for connections to webhook (optional).
    # Alternatively, the CA bundle can be specified in a Secret or
    # ConfigMap that will be dynamically watched by Pinniped for
    # changes to the CA bundle (see API docs for details).
    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