Add auth-signin annotation

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/README.md

@@ -0,0 +1,45 @@
+## 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`.
+

examples/external-auth/dashboard.ingress.yaml

@@ -0,0 +1,27 @@
+---
+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: 'foo-secret-966'
+    hosts:
+    - 'foo-966.bar.com'
+  rules:
+  - host: 'foo-966.bar.com'
+    http:
+      paths:
+      - path: /
+        backend:
+          serviceName: kubernetes-dashboard
+          servicePort: 80
+      - parh: /oauth2
+        backend:
+          serviceName: oauth2proxy
+          servicePort: 4180
+     

examples/external-auth/deployment.yaml

@@ -0,0 +1,43 @@
+
+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
+        args:
+        - --provider=github
+        - --email-domain=*
+---
+
+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