Project: Pinniped (Provisioning / Key Management)
File: supervisor-without-concierge-demo.md

title: Learn to use the Pinniped Supervisor without the Concierge description: See how the Pinniped Supervisor can work directly with the Kube API server to provide authentication to Kubernetes clusters. cascade: layout: docs menu: docs: name: Supervisor without Concierge parent: tutorials weight: 200 This tutorial shows how to use the Pinniped Supervisor and Pinniped command-line tool to provide federated identity with a single sign-on user experience on many Kubernetes clusters, without using the Pinniped Concierge. If you would like to learn how to use the Pinniped Supervisor and Concierge together, please instead see this other tutorial: The Kubernetes API server can be configured to trust an OIDC identity provider to provide authentication for the cluster. This is done by setting the `--oidc-*` command-line flags of the `kube-apiserver` command-line tool inside the Pod spec of the Kubernetes API server Pods. The details of these command-line flags are described in the and in the . These flags can be used to configure the Pinniped Supervisor as the OIDC provider for your clusters. If your cluster's Kubernetes distribution does not allow you to adjust these command-line flags, then this approach will not work for those clusters. For example, most cloud providers will not allow these flags to be adjusted. In that case, you can use the Pinniped Concierge to provide the equivalent functionality on those clusters. Additionally, if you would like to be able to easily change this configuration at any time on your cluster, then you can use the Pinniped Concierge instead of these `kube-apiserver` command-line flags, even on a cluster where you have control over these flags. The Pinniped Concierge offers a custom resource called JWTAuthenticator which can be dynamically configured at any time, which is roughly equivalent to using these `kube-apiserver` command-line flags. One Pinniped Supervisor can provide authentication for many Kubernetes clusters. Each cluster can either use the Pinniped Concierge or use the `kube-apiserver` command-line flags, and both approaches can be mixed and matched on different clusters all with a single Pinniped Supervisor. A Kubernetes cluster of a type which allows you to adjust the command-line flags of `kube-apiserver`. Don't have a cluster handy? Consider using on your local machine. See below for an example of using kind. A kubeconfig where the current context points to the cluster and has administrator-like privileges on that cluster. A Pinniped Supervisor already installed and running on another cluster, and already configured with a working FederationDomain, TLS certificates, and an external identity provider (e.g. an OIDCIdentityProvider, LDAPIdentityProvider, or ActiveDirectoryIdentityProvider). Don't have a Pinniped Supervisor ready? Please refer to the other documents on this site to help you get one up and running and sufficiently configured. This tutorial does not show to install and configure the Pinniped

Those steps are shown in the , so if you would like you could follow the steps of that tutorial to install and configure a Pinniped Supervisor before returning to this tutorial. The `kube-apiserver` command-line flags may be configured on each cluster to trust your Pinniped Supervisor to provide user authentication to that cluster. Add the following flags to the existing list of flags for your cluster: ```bash --oidc-issuer-url="https://my-supervisor.example.com/my-issuer" --oidc-ca-file="/etc/ca-certificates/supervisor/root-ca.pem" --oidc-client-id="my-cluster-342klb7h" --oidc-signing-algs="ES256" --oidc-username-claim="username" --oidc-groups-claim="groups" --oidc-username-prefix="pinniped:" --oidc-groups-prefix="pinniped:" ``` Use the `--oidc-client-id` to choose a string that is unique for each cluster. This could be a GUID or some other random letters and numbers, and can be combined with a human-readable portion if desired. When a user first authenticates to the Pinniped Supervisor, it will issue an ID token with the `aud` (audience) claim set to the name of the client, which will be either `pinniped-cli` (for the kubectl use case) or will start with `client.oauth.pinniped.dev-` (for a web app client using the OIDCClient CR). Avoid using these names for the `--oidc-client-id` value to ensure that these initial ID tokens cannot be used to authenticate to your cluster. Next, the client will make another call to the Pinniped Supervisor to obtain a new ID token which is scoped to one specific cluster. This new token will have the `aud` claim's value changed to the cluster's unique value. This is the only token that will be sent to that cluster. The `--oidc-client-id` flag of `kube-apiserver` tells it to validate the `aud` claim on the incoming ID tokens. This cluster-scoped ID token will not be accepted by any other cluster, because no other cluster should use the same unique value for this flag. This improves the security of your clusters by making this token only valuable on a single cluster. The procedure to add these command-line flags to the `kube-apiserver`'s list of command-line flags depends on the distribution of Kubernetes that you are using. Please refer to the documentation for your distribution. Note that you can configure these flags even if the Pinniped Supervisor is not running yet. The Kube API server will continuously try to find the Pinniped Supervisor at the configured URL until it works. You can use the Pinniped command-line tool to create a kubeconfig that will work with your Pinniped Supervisor and your cluster. When using the Pinniped Concierge on the cluster, the Pinniped command-line tool will auto-discover many settings for the kubeconfig. However, when configuring the `kube-apiserver` flags instead of using the Pinniped Concierge, then you must give more hints to the Pinniped command-line tool to help it create the kubeconfig. Here is how you would create a kubeconfig for the example configuration of the `kube-apiserver` flags shown above: ```bash pinniped get kubeconfig \ --no-concierge \ --oidc-issuer "https://my-supervisor.example.com/my-issuer" \ --oidc-ca-bundle "supervisorrootca_cert.pem" \ --oidc-request-audience "my-cluster-342klb7h" \ --kubeconfig "my-admin-kubeconfig-for-this-cluster.yaml" \ >

``` Use `--no-concierge` to indicate that you are not using the Pinniped Concierge on this cluster. The `--oidc-issuer` value should exactly match the issuer URL configured in the `kube-apiserver`'s `--oidc-issuer-url` flag and the `spec.issuer` of your Supervisor's FederationDomain. The `--oidc-ca-bundle` flag is only required when the machine on which you are running this command is not going to trust your Supervisor's FederationDomain's TLS certificates, e.g. if you used a self-signed CA. This file would have the same content as the file that you provided to `kube-apiserver`'s `--oidc-ca-file` flag. The `--oidc-request-audience` value should exactly match the value that you chose for the `kube-apiserver`'s `--oidc-client-id` flag. The `--kubeconfig` value is the admin kubeconfig of the cluster for which you would like to generate a Pinniped-compatible kubeconfig. This is not needed when your current context is already set to the cluster. The command will output the new Pinniped-compatible kubeconfig to stdout. Optionally redirect this to a file. is a tool for creating and managing Kubernetes clusters on your local machine which uses Docker containers as the cluster's nodes. This is a convenient way to try out this feature on a local non-production cluster. The following steps deploy the latest release of Pinniped on kind using the local-user-authenticator component as the authenticator. Install the tools required for the following steps. , if not already installed. For example, `brew install kind` on macOS. kind depends on Docker. If not already installed, , for example `brew cask install docker` on macOS. This demo requires `kubectl`, which comes with Docker, or can be . . Create a kind configuration yaml file to ask kind to configure the `kube-apiserver` flags. Note that some of these values will need to be adjusted as described in the comments below before using this file in the next step. ```yaml kind: Cluster apiVersion: kind.x-k8s.io/v1alpha4 nodes: role: control-plane extraMounts: hostPath: /Users/ryan/supervisorrootca_cert.pem containerPath: /etc/ca-certificates/supervisor/root-ca.pem readOnly: true kubeadmConfigPatches: | apiVersion: kubeadm.k8s.io/v1beta3 kind: ClusterConfiguration apiServer: extraArgs: oidc-issuer-url: "https://my-supervisor.example.com/my-issuer" oidc-client-id: "my-cluster-342klb7h" # choose a unique value oidc-signing-algs: "ES256" oidc-username-claim: "username" oidc-groups-claim: "groups" oidc-username-prefix: "pinniped:" oidc-groups-prefix: "pinniped:" oidc-ca-file: "/etc/ca-certificates/supervisor/root-ca.pem" ``` Save this as a new yaml file, for example `cluster-config.yaml`. Create a new Kubernetes cluster using `kind create cluster --config cluster-config.yaml`. Optionally provide a cluster name using the `--name` flag. kind automatically updates your kubeconfig to point to the new cluster as a user with administrator-like permissions. Wait for this command to successfully complete before moving on. Create a Pinniped-compatible kubeconfig for this new cluster. Note that the previous `kind create cluster` command automatically changed your current kubeconfig context to point at the new cluster. ```sh pinniped get kubeconfig \ --no-concierge \ --oidc-issuer "https://my-supervisor.example.com/my-issuer" \ --oidc-ca-bundle "supervisorrootca_cert.pem" \ --oidc-request-audience "my-cluster-342klb7h" \ > /tmp/pinniped-kubeconfig.yaml ``` Try using the generated kubeconfig to issue arbitrary `kubectl`

The first time you run a kubectl command, you will be automatically prompted to authenticate using the external identity provider that is configured in the Pinniped Supervisor. ```sh kubectl --kubeconfig /tmp/pinniped-kubeconfig.yaml get pods -A ``` Because this user has no RBAC permissions on this cluster, the previous command results in the error `Error from server (Forbidden): pods is forbidden: User "your-username-will-show-here" cannot list resource "pods" in API group "" at the cluster scope`, where `your-username-will-show-here` will be your actual username from the Pinniped Supervisor. However, this error does prove that you are authenticated and acting as that identity from the Pinniped Supervisor on this kind cluster. If desired, you can use the administrator kubeconfig to create RBAC RoleBindings and ClusterRoleBindings for that user or for the groups to which that user belongs. Carry on issuing as many `kubectl` commands as you'd like as that user. You will not be prompted to log in again for 9 hours for this cluster or for any other similarly configured cluster which uses the same Pinniped Supervisor FederationDomain issuer. Each time a few minutes have passed, the next kubectl command will use the Pinniped command-line tool to securely refresh your identity from the external identity provider that is configured in the Pinniped Supervisor without user interaction. During this refresh, your group memberships may be updated from the external identity provider, or you may be prompted to log in again if the Pinniped Supervisor determines that external identity provider does not want your session to continue. You may find it convenient to set the `KUBECONFIG` environment variable rather than passing `--kubeconfig` to each invocation. ```sh export KUBECONFIG=/tmp/pinniped-kubeconfig.yaml kubectl get namespaces kubectl get pods -A ``` Alternatively, you could use the `kubectl config view` command to merge this kubeconfig into another kubeconfig. Take a look at the contents of the `/tmp/pinniped-kubeconfig.yaml` file. It does not contain any particular user's identity, nor does it contain any credentials. It only contains a recipe for how any user can authenticate. You can safely distribute this file to all users of this cluster. Anyone who uses this kubeconfig will be prompted to authenticate using the external identity provider that is configured in the Pinniped Supervisor. Each user will need to on any machine where they would like to use the kubeconfig. There is an outstanding Kubernetes enhancement proposal to make this Kubernetes API server's OIDC authentication settings configurable using a new Kubernetes API resource. At the time of writing this Pinniped document, the proposal is still under review by the Kubernetes maintainers. If implemented in a future release of Kubernetes, this would remove the need to edit the command-line flags of the `kube-apiserver` binary, making it easier to configure an OIDC provider for your cluster in a standard way. The details and status of this proposal may be found in .