docs: Add vouch-proxy OAuth example (#10929)

docs/examples/auth/oauth-external-auth/README.md

@@ -51,25 +51,72 @@ into a Kubernetes cluster and use it to protect the Kubernetes Dashboard using G
 
     ![Register OAuth2 Application](images/register-oauth-app-2.png)
 
-3. Configure oauth2_proxy values in the file [`oauth2-proxy.yaml`](https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/auth/oauth-external-auth/oauth2-proxy.yaml) with the values:
+3. Configure values in the file [`oauth2-proxy.yaml`](https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/auth/oauth-external-auth/oauth2-proxy.yaml) with the values:
 
     - OAUTH2_PROXY_CLIENT_ID with the github `<Client ID>`
     - OAUTH2_PROXY_CLIENT_SECRET with the github `<Client Secret>`
     - OAUTH2_PROXY_COOKIE_SECRET with value of `python -c 'import os,base64; print(base64.b64encode(os.urandom(16)).decode("ascii"))'`
+    - (optional, but recommended) OAUTH2_PROXY_GITHUB_USERS with GitHub usernames to allow to login
+    - `__INGRESS_HOST__` with a valid FQDN (e.g. `foo.bar.com`)
+    - `__INGRESS_SECRET__` with a Secret with a valid SSL certificate
 
-4. Customize the contents of the file [`dashboard-ingress.yaml`](https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/auth/oauth-external-auth/dashboard-ingress.yaml):
+4. Deploy the oauth2 proxy and the ingress rules by running:
-
-    Replace `__INGRESS_HOST__` with a valid FQDN and `__INGRESS_SECRET__` with a Secret with a valid SSL certificate.
-
-5. Deploy the oauth2 proxy and the ingress rules running:
 
     ```console
-    $ kubectl create -f oauth2-proxy.yaml,dashboard-ingress.yaml
+    $ kubectl create -f oauth2-proxy.yaml
     ```
 
-### Test
+#### Test
 
-Test the oauth integration accessing the configured URL, e.g. `https://foo.bar.com`
+Test the integration by accessing the configured URL, e.g. `https://foo.bar.com`
+
+![Register OAuth2 Application](images/github-auth.png)
+
+![GitHub authentication](images/oauth-login.png)
+
+![Kubernetes dashboard](images/dashboard.png)
+
+
+### Example: Vouch Proxy + Kubernetes-Dashboard
+
+This example will show you how to deploy [`Vouch Proxy`](https://github.com/vouch/vouch-proxy)
+into a Kubernetes cluster and use it to protect the Kubernetes Dashboard using GitHub as the OAuth2 provider.
+
+#### Prepare
+
+1. Install the kubernetes dashboard
+
+    ```console
+    kubectl create -f https://raw.githubusercontent.com/kubernetes/kops/master/addons/kubernetes-dashboard/v1.10.1.yaml
+    ```
+
+2. Create a [custom GitHub OAuth application](https://github.com/settings/applications/new)
+
+    ![Register OAuth2 Application](images/register-oauth-app.png)
+
+    - Homepage URL is the FQDN in the Ingress rule, like `https://foo.bar.com`
+    - Authorization callback URL is the same as the base FQDN plus `/oauth2/auth`, like `https://foo.bar.com/oauth2/auth`
+
+    ![Register OAuth2 Application](images/register-oauth-app-2.png)
+
+3. Configure Vouch Proxy values in the file [`vouch-proxy.yaml`](https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/auth/oauth-external-auth/vouch-proxy.yaml) with the values:
+
+    - VOUCH_COOKIE_DOMAIN with value of `<Ingress Host>`
+    - OAUTH_CLIENT_ID with the github `<Client ID>`
+    - OAUTH_CLIENT_SECRET with the github `<Client Secret>`
+    - (optional, but recommended) VOUCH_WHITELIST with GitHub usernames to allow to login
+    - `__INGRESS_HOST__` with a valid FQDN (e.g. `foo.bar.com`)
+    - `__INGRESS_SECRET__` with a Secret with a valid SSL certificate
+
+4. Deploy Vouch Proxy and the ingress rules by running:
+
+    ```console
+    $ kubectl create -f vouch-proxy.yaml
+    ```
+
+#### Test
+
+Test the integration by accessing the configured URL, e.g. `https://foo.bar.com`
 
 ![Register OAuth2 Application](images/github-auth.png)
 

docs/examples/auth/oauth-external-auth/dashboard-ingress.yaml

@@ -1,45 +0,0 @@
-apiVersion: networking.k8s.io/v1
-kind: Ingress
-metadata:
-  annotations:
-    nginx.ingress.kubernetes.io/auth-url: "https://$host/oauth2/auth"
-    nginx.ingress.kubernetes.io/auth-signin: "https://$host/oauth2/start?rd=$escaped_request_uri"
-  name: external-auth-oauth2
-  namespace: kube-system
-spec:
-  ingressClassName: nginx
-  rules:
-  - host: __INGRESS_HOST__
-    http:
-      paths:
-      - path: /
-        pathType: Prefix
-        backend:
-          service:
-            name: kubernetes-dashboard
-            port:
-              number: 80
----
-
-apiVersion: networking.k8s.io/v1
-kind: Ingress
-metadata:
-  name: oauth2-proxy
-  namespace: kube-system
-spec:
-  ingressClassName: nginx
-  rules:
-  - host: __INGRESS_HOST__
-    http:
-      paths:
-      - path: /oauth2
-        pathType: Prefix
-        backend:
-          service:
-            name: oauth2-proxy
-            port:
-              number: 4180
-  tls:
-  - hosts:
-    - __INGRESS_HOST__
-    secretName: __INGRESS_SECRET__

docs/examples/auth/oauth-external-auth/oauth2-proxy.yaml

@@ -31,6 +31,9 @@ spec:
         # docker run -ti --rm python:3-alpine python -c 'import secrets,base64; print(base64.b64encode(base64.b64encode(secrets.token_bytes(16))));'
         - name: OAUTH2_PROXY_COOKIE_SECRET
           value: SECRET
+        # Recommended: remove email-domain=* in args and set an allowlist
+        # - name: OAUTH2_PROXY_GITHUB_USERS
+        #   value: alice,bob
         image: quay.io/oauth2-proxy/oauth2-proxy:latest
         imagePullPolicy: Always
         name: oauth2-proxy
@@ -55,3 +58,52 @@ spec:
     targetPort: 4180
   selector:
     k8s-app: oauth2-proxy
+
+---
+
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: oauth2-proxy
+  namespace: kube-system
+spec:
+  ingressClassName: nginx
+  rules:
+  - host: __INGRESS_HOST__
+    http:
+      paths:
+      - path: /oauth2
+        pathType: Prefix
+        backend:
+          service:
+            name: oauth2-proxy
+            port:
+              number: 4180
+  tls:
+  - hosts:
+    - __INGRESS_HOST__
+    secretName: __INGRESS_SECRET__
+
+---
+
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  annotations:
+    nginx.ingress.kubernetes.io/auth-url: "https://$host/oauth2/auth"
+    nginx.ingress.kubernetes.io/auth-signin: "https://$host/oauth2/start?rd=$escaped_request_uri"
+  name: external-auth-oauth2
+  namespace: kube-system
+spec:
+  ingressClassName: nginx
+  rules:
+  - host: __INGRESS_HOST__
+    http:
+      paths:
+      - path: /
+        pathType: Prefix
+        backend:
+          service:
+            name: kubernetes-dashboard
+            port:
+              number: 80

docs/examples/auth/oauth-external-auth/vouch-proxy.yaml

@@ -0,0 +1,110 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  labels:
+    k8s-app: vouch-proxy
+  name: vouch-proxy
+  namespace: kube-system
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      k8s-app: vouch-proxy
+  template:
+    metadata:
+      labels:
+        k8s-app: vouch-proxy
+    spec:
+      containers:
+      - env:
+        - name: VOUCH_ALLOWALLUSERS
+          value: true
+        # Recommended: remove VOUCH_ALLOWALLUSERS and set an allowlist
+        # - name: VOUCH_WHITELIST
+        #   value: alice,bob
+        - name: VOUCH_COOKIE_DOMAIN
+          value: <Ingress Host>
+        - name: VOUCH_LISTEN
+          value: 0.0.0.0
+        - name: VOUCH_DOCUMENT_ROOT
+          value: oauth2
+        # See https://github.com/vouch/vouch-proxy/tree/master/config for different provider examples
+        - name: OAUTH_PROVIDER
+          value: github
+        - name: OAUTH_CLIENT_ID
+          value: <Client ID>
+        - name: OAUTH_CLIENT_SECRET
+          value: <Client Secret>
+        image: quay.io/vouch/vouch-proxy:latest
+        imagePullPolicy: Always
+        name: vouch-proxy
+        ports:
+        - containerPort: 9090
+          protocol: TCP
+
+---
+
+apiVersion: v1
+kind: Service
+metadata:
+  labels:
+    k8s-app: vouch-proxy
+  name: vouch-proxy
+  namespace: kube-system
+spec:
+  ports:
+  - name: http
+    port: 9090
+    protocol: TCP
+    targetPort: 9090
+  selector:
+    k8s-app: vouch-proxy
+
+---
+
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: vouch-proxy
+  namespace: kube-system
+spec:
+  ingressClassName: nginx
+  rules:
+  - host: __INGRESS_HOST__
+    http:
+      paths:
+      - path: /oauth2
+        pathType: Prefix
+        backend:
+          service:
+            name: vouch-proxy
+            port:
+              number: 9090
+  tls:
+  - hosts:
+    - __INGRESS_HOST__
+    secretName: __INGRESS_SECRET__
+
+---
+
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  annotations:
+    nginx.ingress.kubernetes.io/auth-url: "https://$host/oauth2/validate"
+    nginx.ingress.kubernetes.io/auth-signin: "https://$host/oauth2/login?url=$scheme://$http_host$request_uri"
+  name: external-auth-oauth2
+  namespace: kube-system
+spec:
+  ingressClassName: nginx
+  rules:
+  - host: __INGRESS_HOST__
+    http:
+      paths:
+      - path: /
+        pathType: Prefix
+        backend:
+          service:
+            name: kubernetes-dashboard
+            port:
+              number: 80