2020-12-18 00:08:51 +00:00
---
2021-02-22 23:52:23 +00:00
title: Learn to use the Pinniped Concierge
description: See how the Pinniped Concierge works to provide a uniform login flow across different Kubernetes clusters.
2020-12-18 00:08:51 +00:00
cascade:
layout: docs
2021-02-17 23:02:57 +00:00
menu:
docs:
name: Concierge with Webhook
2021-02-22 23:52:23 +00:00
parent: tutorials
2021-02-17 23:02:57 +00:00
weight: 100
2020-12-18 00:08:51 +00:00
---
## Prerequisites
2021-03-16 18:00:31 +00:00
1. A Kubernetes cluster of a type supported by Pinniped as described in [architecture ](/docs/background/architecture ).
2020-12-18 00:08:51 +00:00
Don't have a cluster handy? Consider using [kind ](https://kind.sigs.k8s.io/ ) on your local machine.
See below for an example of using kind.
2021-03-16 18:00:31 +00:00
1. An authenticator of a type supported by Pinniped as described in [architecture ](/docs/background/architecture ).
2020-12-18 00:08:51 +00:00
2020-12-18 00:42:45 +00:00
Don't have an authenticator of a type supported by Pinniped handy? No problem, there is a demo authenticator
2020-12-18 00:08:51 +00:00
available. Start by installing local-user-authenticator on the same cluster where you would like to try Pinniped
by following the directions in [deploy/local-user-authenticator/README.md ](https://github.com/vmware-tanzu/pinniped/blob/main/deploy/local-user-authenticator/README.md ).
See below for an example of deploying this on kind.
2021-02-22 23:52:23 +00:00
1. A kubeconfig where the current context points to the cluster and has administrator-like
2020-12-18 00:08:51 +00:00
privileges on that cluster.
## Overview
2021-02-22 23:52:23 +00:00
Installing and trying the Pinniped Concierge on any cluster consists of the following general steps. See the next section below
2020-12-18 00:08:51 +00:00
for a more specific example of installing onto a local kind cluster, including the exact commands to use for that case.
2021-02-22 23:52:23 +00:00
1. [Install the Concierge ]({{< ref "../howto/install-concierge" >}} ).
1. [Install the Pinniped command-line tool ]({{< ref "../howto/install-cli" >}} ).
1. Configure the Concierge with a
[JWT ]({{< ref "../howto/configure-concierge-jwt" >}} ) or
[webhook ]({{< ref "../howto/configure-concierge-webhook" >}} ) authenticator.
1. Generate a kubeconfig using the Pinniped command-line tool (run `pinniped get kubeconfig --help` for more information).
1. Run `kubectl` commands using the generated kubeconfig.
The Pinniped Concierge is automatically be used for authentication during those commands.
2020-12-18 00:08:51 +00:00
2021-02-22 23:52:23 +00:00
## Example of deploying on kind
2020-12-18 00:08:51 +00:00
[kind ](https://kind.sigs.k8s.io ) is a tool for creating and managing Kubernetes clusters on your local machine
2021-02-22 23:52:23 +00:00
which uses Docker containers as the cluster's nodes. This is a convenient way to try out Pinniped on a local
2020-12-18 00:08:51 +00:00
non-production cluster.
2021-02-22 23:52:23 +00:00
The following steps deploy the latest release of Pinniped on kind using the local-user-authenticator component
2020-12-18 18:06:09 +00:00
as the authenticator.
2020-12-18 00:08:51 +00:00
1. Install the tools required for the following steps.
2021-02-22 23:52:23 +00:00
- [Install kind ](https://kind.sigs.k8s.io/docs/user/quick-start/ ), if not already installed. For example, `brew install kind` on macOS.
2020-12-18 00:08:51 +00:00
2021-02-22 23:52:23 +00:00
- kind depends on Docker. If not already installed, [install Docker ](https://docs.docker.com/get-docker/ ), for example `brew cask install docker` on macOS.
2020-12-18 00:08:51 +00:00
- This demo requires `kubectl` , which comes with Docker, or can be [installed separately ](https://kubernetes.io/docs/tasks/tools/install-kubectl/ ).
2021-02-22 23:52:23 +00:00
- This demo requires a tool capable of generating a `bcrypt` hash to interact with
2020-12-18 00:08:51 +00:00
the webhook. The example below uses `htpasswd` , which is installed on most macOS systems, and can be
2021-02-22 23:52:23 +00:00
installed on some Linux systems via the `apache2-utils` package (for example, `apt-get install
2020-12-18 00:08:51 +00:00
apache2-utils`).
1. Create a new Kubernetes cluster using `kind create cluster` . Optionally provide a cluster name using the `--name` flag.
2021-02-22 23:52:23 +00:00
kind automatically updates your kubeconfig to point to the new cluster as a user with administrator-like permissions.
2020-12-18 00:08:51 +00:00
2020-12-18 18:06:09 +00:00
1. Deploy the local-user-authenticator app. This is a demo authenticator. In production, you would configure
an authenticator that works with your real identity provider, and therefore would not need to deploy or configure local-user-authenticator.
2020-12-18 00:08:51 +00:00
2021-02-22 23:52:23 +00:00
```sh
2021-01-28 15:24:11 +00:00
kubectl apply -f https://get.pinniped.dev/latest/install-local-user-authenticator.yaml
2020-12-18 00:08:51 +00:00
```
The `install-local-user-authenticator.yaml` file includes the default deployment options.
If you would prefer to customize the available options, please
see [deploy/local-user-authenticator/README.md ](https://github.com/vmware-tanzu/pinniped/blob/main/deploy/local-user-authenticator/README.md )
for instructions on how to deploy using `ytt` .
2021-05-24 16:50:16 +00:00
If you prefer to install a specific version, replace `latest` in the URL with the version number such as `v0.8.0` .
2021-01-28 15:24:11 +00:00
2021-01-04 20:31:53 +00:00
1. Create a test user named `pinny-the-seal` in the local-user-authenticator namespace.
2020-12-18 00:08:51 +00:00
2021-02-22 23:52:23 +00:00
```sh
2020-12-18 00:08:51 +00:00
kubectl create secret generic pinny-the-seal \
--namespace local-user-authenticator \
--from-literal=groups=group1,group2 \
--from-literal=passwordHash=$(htpasswd -nbBC 10 x password123 | sed -e "s/^x://")
```
1. Fetch the auto-generated CA bundle for the local-user-authenticator's HTTP TLS endpoint.
2021-02-22 23:52:23 +00:00
```sh
2020-12-18 00:08:51 +00:00
kubectl get secret local-user-authenticator-tls-serving-certificate --namespace local-user-authenticator \
-o jsonpath={.data.caCertificate} \
| tee /tmp/local-user-authenticator-ca-base64-encoded
```
2020-12-18 18:06:09 +00:00
1. Deploy the Pinniped Concierge.
2020-12-18 00:08:51 +00:00
2021-02-22 23:52:23 +00:00
```sh
2021-01-28 15:24:11 +00:00
kubectl apply -f https://get.pinniped.dev/latest/install-pinniped-concierge.yaml
2020-12-18 00:08:51 +00:00
```
The `install-pinniped-concierge.yaml` file includes the default deployment options.
2021-02-22 23:52:23 +00:00
If you would prefer to customize the available options, please see the [Concierge installation guide ]({{< ref "../howto/install-concierge" >}} )
2020-12-18 00:08:51 +00:00
for instructions on how to deploy using `ytt` .
2020-12-18 18:06:09 +00:00
1. Create a `WebhookAuthenticator` object to configure the Pinniped Concierge to authenticate using local-user-authenticator.
2020-12-18 00:08:51 +00:00
```bash
2021-02-09 18:59:32 +00:00
cat < < EOF | kubectl create -f -
2020-12-18 00:08:51 +00:00
apiVersion: authentication.concierge.pinniped.dev/v1alpha1
kind: WebhookAuthenticator
metadata:
name: local-user-authenticator
spec:
endpoint: https://local-user-authenticator.local-user-authenticator.svc/authenticate
tls:
certificateAuthorityData: $(cat /tmp/local-user-authenticator-ca-base64-encoded)
EOF
```
2021-02-22 23:52:23 +00:00
1. Download the latest version of the Pinniped command-line tool for your platform.
On macOS or Linux, you can do this using Homebrew:
```sh
brew install vmware-tanzu/pinniped/pinniped-cli
```
2020-12-18 00:08:51 +00:00
2021-02-22 23:52:23 +00:00
On other platforms, see the [command-line installation guide ]({{< ref "../howto/install-cli" >}} ) for more details.
2020-12-18 00:08:51 +00:00
2020-12-18 18:06:09 +00:00
1. Generate a kubeconfig for the current cluster. Use `--static-token` to include a token which should
2021-02-22 23:52:23 +00:00
allow you to authenticate as the user that you created previously.
```sh
pinniped get kubeconfig \
--static-token "pinny-the-seal:password123" \
--concierge-authenticator-type webhook \
--concierge-authenticator-name local-user-authenticator \
> /tmp/pinniped-kubeconfig
2020-12-18 00:08:51 +00:00
```
1. Try using the generated kubeconfig to issue arbitrary `kubectl` commands as
the `pinny-the-seal` user.
2021-02-22 23:52:23 +00:00
```sh
kubectl --kubeconfig /tmp/pinniped-kubeconfig \
get pods -n pinniped-concierge
2020-12-18 00:08:51 +00:00
```
Because this user has no RBAC permissions on this cluster, the previous command
2021-02-22 23:52:23 +00:00
results in the error `Error from server (Forbidden): pods is forbidden: User "pinny-the-seal" cannot list resource "pods" in API group "" in the namespace "pinniped-concierge"` .
2020-12-18 00:08:51 +00:00
However, this does prove that you are authenticated and acting as the `pinny-the-seal` user.
2021-02-22 23:52:23 +00:00
1. As the administrator user, create RBAC rules for the test user to give them permissions to perform actions on the cluster.
2020-12-18 00:08:51 +00:00
For example, grant the test user permission to view all cluster resources.
2021-02-22 23:52:23 +00:00
```sh
kubectl create clusterrolebinding pinny-can-read \
--clusterrole view \
--user pinny-the-seal
2020-12-18 00:08:51 +00:00
```
1. Use the generated kubeconfig to issue arbitrary `kubectl` commands as the `pinny-the-seal` user.
2021-02-22 23:52:23 +00:00
```sh
kubectl --kubeconfig /tmp/pinniped-kubeconfig \
get pods -n pinniped-concierge
2020-12-18 00:08:51 +00:00
```
The user has permission to list pods, so the command succeeds this time.
2021-02-22 23:52:23 +00:00
Pinniped has provided authentication into the cluster for your `kubectl` command. 🎉
2020-12-18 00:08:51 +00:00
1. Carry on issuing as many `kubectl` commands as you'd like as the `pinny-the-seal` user.
2021-02-22 23:52:23 +00:00
Each invocation uses Pinniped for authentication.
2020-12-18 00:08:51 +00:00
You may find it convenient to set the `KUBECONFIG` environment variable rather than passing `--kubeconfig` to each invocation.
2021-02-22 23:52:23 +00:00
```sh
2020-12-18 00:08:51 +00:00
export KUBECONFIG=/tmp/pinniped-kubeconfig
kubectl get namespaces
kubectl get pods -A
```