add external auth example

examples/README.md

@@ -57,7 +57,7 @@ SNI + TCP | TLS routing based on SNI hostname | nginx | Advanced
 Name | Description | Platform   | Complexity Level
 -----| ----------- | ---------- | ----------------
 Basic auth | password protect your website | nginx | Intermediate
-External auth plugin | defer to an external auth service | nginx | Intermediate
+[External auth plugin](external-auth/README.md) | defer to an external auth service | nginx | Intermediate
 
 ## Protocols
 

examples/external-auth/.gitignore

@@ -0,0 +1,2 @@
+oauth2proxy.config
+authenticated_emails

examples/external-auth/README.md

@@ -0,0 +1,62 @@
+## External Authentication
+
+### Overview
+
+The `auth-url` and `auth-signin` annotations allow you to use an external
+authentication provider to protect your Ingress resources.
+
+(Note, this annotation requires `nginx-ingress-controller v0.9.0` or greater.)
+
+### Key Detail
+
+This functionality is enabled by deploying multiple Ingress objects for a single host.
+One Ingress object has no special annotations and handles authentication.
+
+Other Ingress objects can then be annotated in such a way that require the user to
+authenticate against the first Ingress's endpoint, and can redirect `401`s to the
+same endpoint.
+
+Sample:
+
+```
+...
+metadata:
+  name: application
+  annotations:
+    "ingress.kubernetes.io/auth-url": "https://$host/oauth2/auth"
+    "ingress.kubernetes.io/signin-url": "https://$host/oauth2/sign_in"
+...
+```
+
+### Example: OAuth2 Proxy + Kubernetes-Dashboard
+
+This example will show you how to deploy [`oauth2_proxy`](https://github.com/bitly/oauth2_proxy)
+into a Kubernetes cluster and use it to protect the Kubernetes Dashboard.
+
+#### Prepare:
+
+1. `export DOMAIN="somedomain.io"`
+2. Install `nginx-ingress`. If you haven't already, consider using `helm`: `$ helm install stable/nginx-ingress`
+3. Make sure you have a TLS cert added as a Secret named `ingress-tls` that corresponds to your `$DOMAIN`.
+
+### Deploy: `oauth2_proxy`
+
+This is the Deployment object that runs `oauth2_proxy`.
+
+1. Configure `oauth2proxy.deployment.yaml` to use the desired provider.
+
+2. Create a secret with the appropriate name and values, matching what is specified in
+   `oauth2proxy.deployment.yaml`.
+
+   For example, as-is with Azure AD, you can use this command:
+   ```
+   kubectl create-secret generic oauth2proxy \
+     --from-literal=COOKIE_SECRET="$(uuidgen)" \
+     --from-literal=TENANT_ID="${TENANT_ID}" \
+     --from-literal=CLIENT_ID="${CLIENT_ID}" \
+     --from-literal=CLIENT_SECRET="${CLIENT_SECRET}"
+   ```
+
+3. Deploy it all: `./deploy.sh`
+
+See the script for further details.

examples/external-auth/authenticated_emails.example

@@ -0,0 +1 @@
+sam@example.com

examples/external-auth/dashboard.ingress.yaml

@@ -0,0 +1,22 @@
+---
+apiVersion: extensions/v1beta1
+kind: Ingress
+metadata:
+  name: dashboard
+  namespace: kube-system
+  annotations:
+    "ingress.kubernetes.io/auth-url": "https://$host/oauth2/auth"
+    "ingress.kubernetes.io/auth-signin": "https://$host/oauth2/sign_in"
+spec:
+  tls:
+  - secretName: 'ingress-tls'
+    hosts:
+    - '__DOMAIN__'
+  rules:
+  - host: '__DOMAIN__'
+    http:
+      paths:
+      - path: /
+        backend:
+          serviceName: kubernetes-dashboard
+          servicePort: 80

examples/external-auth/deploy.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+
+set -x
+set -u
+set -e
+
+echo "deploying oauth2proxy for ${DOMAIN}"
+
+if [[ -z "${DOMAIN:-}" ]]; then
+	echo "You must set \$DOMAIN."
+	exit -1
+fi
+
+if [[ ! -f "authenticated_emails" ]]; then
+	echo "You must create './authenticated_emails'."
+	exit -1
+fi
+
+if [[ ! -f "oauth2proxy.config" ]]; then
+	echo "You must create './oauth2proxy.config'."
+	exit -1
+fi
+
+force_cleanup="n"
+answer="y"
+if kubectl describe secret oauth2proxy &>/dev/null ; then
+	echo "secret 'oauth2proxy' already exists."
+	echo "do you want to replace it and cycle the 'oauth2proxy' container?"
+	read answer
+	if [[ "${answer}" == "y" ]]; then
+		kubectl delete secret oauth2proxy || true
+		kubectl delete deployment oauth2proxy || true
+	fi
+	force_cleanup="y"
+fi
+if [[ "${answer}" == "y" ]]; then
+	kubectl create secret generic oauth2proxy \
+		--from-file=oauth2proxy.config=./oauth2proxy.config \
+		--from-file=authenticated_emails=./authenticated_emails
+fi
+
+sed "s|__DOMAIN__|${DOMAIN}|g" ./oauth2proxy.deployment.yaml | kubectl apply -f -
+sed "s|__DOMAIN__|${DOMAIN}|g" ./oauth2proxy.ingress.yaml | kubectl apply -f -
+sed "s|__DOMAIN__|${DOMAIN}|g" ./oauth2proxy.service.yaml | kubectl apply -f -
+sed "s|__DOMAIN__|${DOMAIN}|g" ./dashboard.ingress.yaml | kubectl apply -f -

examples/external-auth/oauth2proxy.config.example

@@ -0,0 +1,7 @@
+http_address = "0.0.0.0:4180"
+upstreams = [ "http://default-http-backend" ]
+provider = "azure"
+client_id = ""
+client_secret = ""
+cookie_secret = ""
+authenticated_emails_file = "/var/run/secrets/oauth2proxy/authenticated_emails"

examples/external-auth/oauth2proxy.deployment.yaml

@@ -0,0 +1,31 @@
+---
+apiVersion: extensions/v1beta1
+kind: Deployment
+metadata:
+  name: oauth2-proxy
+  labels:
+    k8s-app: oauth2proxy
+spec:
+  replicas: 1
+  template:
+    metadata:
+      labels:
+        k8s-app: oauth2proxy
+    spec:
+      volumes:
+      - name: oauth2proxy-secret
+        secret:
+          secretName: oauth2proxy
+      containers:
+      - name: oauth2proxy
+        image: docker.io/colemickens/oauth2_proxy:latest
+        imagePullPolicy: Always
+        ports:
+        - containerPort: 4180
+        volumeMounts:
+        - name: oauth2proxy-secret
+          readOnly: true
+          mountPath: /var/run/secrets/oauth2proxy
+        command:
+        - oauth2_proxy
+        - --config=/var/run/secrets/oauth2proxy/oauth2proxy.config

examples/external-auth/oauth2proxy.ingress.yaml

@@ -0,0 +1,18 @@
+---
+apiVersion: extensions/v1beta1
+kind: Ingress
+metadata:
+  name: oauth2proxy
+spec:
+  tls:
+  - secretName: 'ingress-tls'
+    hosts:
+    - '__DOMAIN__'
+  rules:
+  - host: '__DOMAIN__'
+    http: 
+      paths:
+      - path: /oauth2
+        backend:
+          serviceName: oauth2proxy
+          servicePort: 4180

examples/external-auth/oauth2proxy.service.yaml

@@ -0,0 +1,15 @@
+---
+apiVersion: v1
+kind: Service
+metadata:
+  labels:
+    k8s-app: oauth2proxy
+  name: oauth2proxy
+spec:
+  ports:
+  - name: http
+    port: 4180
+    protocol: TCP
+    targetPort: 4180
+  selector:
+    k8s-app: oauth2proxy