Add section on access control to the install docs

Describe default behaviour of the Dashboard as it relates to auth, and provide pointers to common solutions for custom authentication and authorization. Include information on config for solutions we've encountered when using authentication only (i.e. prevent `Authorization` header from being forwarded on upstream requests to the Dashboard). Fix typo: 'walkthrough' should be 'walk-through' (noun.) Remove the Istio walk-through as it is out of date and contains some guidance that is counter to current Istio best practices.
pmdarius · Jan 19, 2022 · 6719854 · 6719854
1 parent c6c6c8d
commit 6719854
Show file tree

Hide file tree

Showing 9 changed files with 37 additions and 397 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -112,6 +112,6 @@ http://localhost:9097
 
 ## What's next
 
-Try out some of our [walkthroughs](./walkthrough) for more details on deploying and configuring the
+Try out some of our [walk-throughs](./walkthrough) for more details on deploying and configuring the
 Tekton Dashboard for some common scenarios. For more information, see the
 [Tekton Dashboard GitHub repository](https://github.com/tektoncd/dashboard).
diff --git a/docs/dev/README.md b/docs/dev/README.md
@@ -231,7 +231,7 @@ Keep in mind that When running your Tekton Pipelines, if you see a `fatal: could
 
 You can read the dashboard backend [API docs](./api.md).
 
-Go though our [walk-throughs](../walkthrough/README.md) or learn about [extensions](../extensions.md).
+Try our [walk-throughs](../walkthrough/README.md) or learn about [extensions](../extensions.md).
 
 ---
 

diff --git a/docs/install.md b/docs/install.md
@@ -189,6 +189,21 @@ spec:
 
 You can then access the Dashboard UI at `http(s)://domain.tld/tekton/`
 
+### Access control
+
+The Dashboard does not provide its own authentication or authorization, however it will pass on any authentication headers provided to it by a proxy deployed in front of the Dashboard. These are then handled by the Kubernetes API server allowing for full access control via [Kubernetes RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/). In case of forbidden access the Dashboard will display corresponding error notifications.
+
+See the walk-throughs for an example of [enabling authentication using oauth2-proxy](./walkthrough/walkthrough-oauth2-proxy.md).
+
+By default the Dashboard accesses resources and performs actions in the cluster using the permissions granted to its own ServiceAccount (i.e. the `tekton-dashboard` ServiceAccount in the `tekton-pipelines` namespace). If you wish to have the Dashboard perform actions on behalf of the authenticated user or some other ServiceAccount this can be achieved via [user impersonation](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation). This is known to work with a number of popular solutions including oauth2-proxy, Keycloak, OpenUnison, Traefik, Istio's EnvoyFilter, and more.
+
+Typically when configuring impersonation you would have the proxy forward its ServiceAccount token in the `Authorization` header, and details of the user and groups in the `Impersonate-User` and `Impersonate-Group` headers respectively. See the docs of your chosen solution for details.
+
+If you're using one of these proxies to provide authentication but still want to use the Dashboard's ServiceAccount to access the Kubernetes APIs you may need to modify the proxy config to prevent it from sending the `Authorization` header on upstream requests to the Dashboard. Some examples of relevant config:
+- oauth2-proxy: add the `--pass-authorization-header=false` command line argument or its equivalent to your config https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/overview#command-line-options
+- Istio EnvoyFilter: the external authentication service should return a custom header `x-envoy-auth-headers-to-remove: Authorization` https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/auth/v3/external_auth.proto
+- Traefik: `removeHeader: true` https://doc.traefik.io/traefik/v2.0/middlewares/basicauth/#removeheader
+
 ## Uninstalling the Dashboard on Kubernetes
 
 The Dashboard can be uninstalled by running the following command:

diff --git a/docs/walkthrough/README.md b/docs/walkthrough/README.md
@@ -1,12 +1,11 @@
-# Tekton Dashboard walkthrough
+# Tekton Dashboard walk-through
 
 Walk-throughs are a step-by-step demonstration of a procedure or process.
 We have the following walk-throughs available:
 
 - [Setup everything from scratch using a kind cluster](./walkthrough-kind.md)
 - [Securing access to the Dashboard behind an oauth2 proxy](./walkthrough-oauth2-proxy.md)
 - [Enabling logs persistence](./walkthrough-logs.md)
-- [Setup everything from scratch using a kind cluster and Istio](./walkthrough-istio.md)
 
 ---
 

diff --git a/docs/walkthrough/walkthrough-istio-kiali.png b/docs/walkthrough/walkthrough-istio-kiali.png
-Original file line number
+Diff line change
@@ Expand Up @@
     You can read the dashboard backend [API docs](./api.md).
-    Go though our [walk-throughs](../walkthrough/README.md) or learn about [extensions](../extensions.md).
+    Try our [walk-throughs](../walkthrough/README.md) or learn about [extensions](../extensions.md).
     ---
@@ Expand Down @@