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

External OAUTH Authentication

Overview

The auth-url and auth-signin annotations allow you to use an external authentication provider to protect your Ingress resources.

!!! Important This annotation requires ingress-nginx-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 401s to the same endpoint.

Sample:

...
metadata:
  name: application
  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"
...

Example: OAuth2 Proxy + Kubernetes-Dashboard

This example will show you how to deploy oauth2_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

   kubectl create -f https://raw.githubusercontent.com/kubernetes/kops/master/addons/kubernetes-dashboard/v1.10.1.yaml
   

2. Create a custom GitHub OAuth application

   

   • 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/callback, like https://foo.bar.com/oauth2/callback

   

3. Configure values in the file 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. Deploy the oauth2 proxy and the ingress rules by running:

   $ kubectl create -f oauth2-proxy.yaml
   

Test

Test the integration by accessing the configured URL, e.g. https://foo.bar.com

Example: Vouch Proxy + Kubernetes-Dashboard

This example will show you how to deploy 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

   kubectl create -f https://raw.githubusercontent.com/kubernetes/kops/master/addons/kubernetes-dashboard/v1.10.1.yaml
   

2. Create a custom GitHub OAuth application

   

   • 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

   

3. Configure Vouch Proxy values in the file 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:

   $ kubectl create -f vouch-proxy.yaml
   

Test

Test the integration by accessing the configured URL, e.g. https://foo.bar.com