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

117 lines
3.7 KiB
Markdown
Raw Normal View History

---
title: Configure the Pinniped Concierge to validate webhook tokens
description: Set up webhook-based token authentication on an individual Kubernetes cluster.
cascade:
layout: docs
menu:
docs:
name: Configure Concierge Webhook Authentication
weight: 40
parent: howtos
---
The Concierge can validate arbitrary tokens via an external webhook endpoint using the [same validation process as Kubernetes itself](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#webhook-token-authentication).
## 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](https://kubernetes.io/docs/reference/kubernetes-api/authentication-resources/token-review-v1/#TokenReview).
- 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:
```yaml
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:
```sh
kubectl apply -f my-webhook-authenticator.yaml
```
## Generate a kubeconfig file
Generate a kubeconfig file to target the WebhookAuthenticator:
```sh
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](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins).
It should look something like below:
```yaml
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:
```sh
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:
```sh
2021-07-21 19:10:47 +00:00
kubectl create clusterrolebinding my-user-admin --clusterrole edit --user my-username
```