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

2024-01-28 16:32:47 +00:00 · 2024-01-28 16:32:47 +00:00 · 7d75abb0ff
commit 7d75abb0ff
parent 5acc4230ee
4 changed files with 218 additions and 54 deletions
--- a/docs/examples/auth/oauth-external-auth/README.md
+++ b/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):
-
-    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:
+4. Deploy the oauth2 proxy and the ingress rules by 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)

--- a/docs/examples/auth/oauth-external-auth/dashboard-ingress.yaml
+++ b/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__
--- a/docs/examples/auth/oauth-external-auth/oauth2-proxy.yaml
+++ b/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
--- a/docs/examples/auth/oauth-external-auth/vouch-proxy.yaml
+++ b/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