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

126 lines
4.6 KiB
Markdown
Raw Permalink Normal View History

2018-08-30 18:24:56 +00:00
# External OAUTH Authentication
### Overview
The `auth-url` and `auth-signin` annotations allow you to use an external
authentication provider to protect your Ingress resources.
2018-04-29 06:17:29 +00:00
!!! Important
Minor documentation cleanup (#7826) * clarify link * Add section headers * console blocks * grpc example json was not valid * multi-tls update text The preceding point 1 related to https://github.com/kubernetes-retired/contrib/blob/4f2cb51ef82b4dddb625f6053ad132c1faf07aa1/ingress/controllers/nginx/examples/ingress.yaml and the deployments referenced in https://github.com/kubernetes-retired/contrib/blob/4f2cb51ef82b4dddb625f6053ad132c1faf07aa1/ingress/controllers/nginx/examples/README.md They are not relevant to the current instructions. * add whitespace around parens * grammar setup would be a proper noun, but it is not the intended concept, which is a state * grammar * is-only * via * Use bullets for choices * ingress-controller nginx is a distinct brand. generally this repo talks about ingress-controller, although it is quite inconsistent about how... * drop stray paren * OAuth is a brand and needs an article here also GitHub is a brand * Indent text under numbered lists * use e.g. * Document that customer header config maps changes do not trigger updates This should be removed if https://github.com/kubernetes/ingress-nginx/issues/5238 is fixed. * article * period * infinitive verb + period * clarify that the gRPC server is responsible for listening for TCP traffic and not some other part of the backend application * avoid using ; and reword * whitespace * brand: gRPC * only-does is the right form `for` adds nothing here * spelling: GitHub * punctuation `;` is generally not the right punctuation... * drop stray `to` * sentence * backticks * fix link * Improve readability of compare/vs * Renumber list * punctuation * Favor Ingress-NGINX and Ingress NGINX * Simplify custom header restart text * Undo typo damage Co-authored-by: Josh Soref <jsoref@users.noreply.github.com>
2022-01-17 00:57:28 +00:00
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 `401`s to the
same endpoint.
Sample:
2017-10-13 13:55:03 +00:00
```yaml
...
metadata:
name: application
annotations:
2018-07-04 09:57:51 +00:00
nginx.ingress.kubernetes.io/auth-url: "https://$host/oauth2/auth"
2018-07-19 06:22:05 +00:00
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`](https://github.com/pusher/oauth2_proxy)
Minor documentation cleanup (#7826) * clarify link * Add section headers * console blocks * grpc example json was not valid * multi-tls update text The preceding point 1 related to https://github.com/kubernetes-retired/contrib/blob/4f2cb51ef82b4dddb625f6053ad132c1faf07aa1/ingress/controllers/nginx/examples/ingress.yaml and the deployments referenced in https://github.com/kubernetes-retired/contrib/blob/4f2cb51ef82b4dddb625f6053ad132c1faf07aa1/ingress/controllers/nginx/examples/README.md They are not relevant to the current instructions. * add whitespace around parens * grammar setup would be a proper noun, but it is not the intended concept, which is a state * grammar * is-only * via * Use bullets for choices * ingress-controller nginx is a distinct brand. generally this repo talks about ingress-controller, although it is quite inconsistent about how... * drop stray paren * OAuth is a brand and needs an article here also GitHub is a brand * Indent text under numbered lists * use e.g. * Document that customer header config maps changes do not trigger updates This should be removed if https://github.com/kubernetes/ingress-nginx/issues/5238 is fixed. * article * period * infinitive verb + period * clarify that the gRPC server is responsible for listening for TCP traffic and not some other part of the backend application * avoid using ; and reword * whitespace * brand: gRPC * only-does is the right form `for` adds nothing here * spelling: GitHub * punctuation `;` is generally not the right punctuation... * drop stray `to` * sentence * backticks * fix link * Improve readability of compare/vs * Renumber list * punctuation * Favor Ingress-NGINX and Ingress NGINX * Simplify custom header restart text * Undo typo damage Co-authored-by: Josh Soref <jsoref@users.noreply.github.com>
2022-01-17 00:57:28 +00:00
into a Kubernetes cluster and use it to protect the Kubernetes Dashboard using GitHub as the OAuth2 provider.
2017-10-13 13:55:03 +00:00
#### Prepare
1. Install the kubernetes dashboard
Minor documentation cleanup (#7826) * clarify link * Add section headers * console blocks * grpc example json was not valid * multi-tls update text The preceding point 1 related to https://github.com/kubernetes-retired/contrib/blob/4f2cb51ef82b4dddb625f6053ad132c1faf07aa1/ingress/controllers/nginx/examples/ingress.yaml and the deployments referenced in https://github.com/kubernetes-retired/contrib/blob/4f2cb51ef82b4dddb625f6053ad132c1faf07aa1/ingress/controllers/nginx/examples/README.md They are not relevant to the current instructions. * add whitespace around parens * grammar setup would be a proper noun, but it is not the intended concept, which is a state * grammar * is-only * via * Use bullets for choices * ingress-controller nginx is a distinct brand. generally this repo talks about ingress-controller, although it is quite inconsistent about how... * drop stray paren * OAuth is a brand and needs an article here also GitHub is a brand * Indent text under numbered lists * use e.g. * Document that customer header config maps changes do not trigger updates This should be removed if https://github.com/kubernetes/ingress-nginx/issues/5238 is fixed. * article * period * infinitive verb + period * clarify that the gRPC server is responsible for listening for TCP traffic and not some other part of the backend application * avoid using ; and reword * whitespace * brand: gRPC * only-does is the right form `for` adds nothing here * spelling: GitHub * punctuation `;` is generally not the right punctuation... * drop stray `to` * sentence * backticks * fix link * Improve readability of compare/vs * Renumber list * punctuation * Favor Ingress-NGINX and Ingress NGINX * Simplify custom header restart text * Undo typo damage Co-authored-by: Josh Soref <jsoref@users.noreply.github.com>
2022-01-17 00:57:28 +00:00
```console
kubectl create -f https://raw.githubusercontent.com/kubernetes/kops/master/addons/kubernetes-dashboard/v1.10.1.yaml
```
Minor documentation cleanup (#7826) * clarify link * Add section headers * console blocks * grpc example json was not valid * multi-tls update text The preceding point 1 related to https://github.com/kubernetes-retired/contrib/blob/4f2cb51ef82b4dddb625f6053ad132c1faf07aa1/ingress/controllers/nginx/examples/ingress.yaml and the deployments referenced in https://github.com/kubernetes-retired/contrib/blob/4f2cb51ef82b4dddb625f6053ad132c1faf07aa1/ingress/controllers/nginx/examples/README.md They are not relevant to the current instructions. * add whitespace around parens * grammar setup would be a proper noun, but it is not the intended concept, which is a state * grammar * is-only * via * Use bullets for choices * ingress-controller nginx is a distinct brand. generally this repo talks about ingress-controller, although it is quite inconsistent about how... * drop stray paren * OAuth is a brand and needs an article here also GitHub is a brand * Indent text under numbered lists * use e.g. * Document that customer header config maps changes do not trigger updates This should be removed if https://github.com/kubernetes/ingress-nginx/issues/5238 is fixed. * article * period * infinitive verb + period * clarify that the gRPC server is responsible for listening for TCP traffic and not some other part of the backend application * avoid using ; and reword * whitespace * brand: gRPC * only-does is the right form `for` adds nothing here * spelling: GitHub * punctuation `;` is generally not the right punctuation... * drop stray `to` * sentence * backticks * fix link * Improve readability of compare/vs * Renumber list * punctuation * Favor Ingress-NGINX and Ingress NGINX * Simplify custom header restart text * Undo typo damage Co-authored-by: Josh Soref <jsoref@users.noreply.github.com>
2022-01-17 00:57:28 +00:00
2. Create a [custom GitHub OAuth application](https://github.com/settings/applications/new)
Minor documentation cleanup (#7826) * clarify link * Add section headers * console blocks * grpc example json was not valid * multi-tls update text The preceding point 1 related to https://github.com/kubernetes-retired/contrib/blob/4f2cb51ef82b4dddb625f6053ad132c1faf07aa1/ingress/controllers/nginx/examples/ingress.yaml and the deployments referenced in https://github.com/kubernetes-retired/contrib/blob/4f2cb51ef82b4dddb625f6053ad132c1faf07aa1/ingress/controllers/nginx/examples/README.md They are not relevant to the current instructions. * add whitespace around parens * grammar setup would be a proper noun, but it is not the intended concept, which is a state * grammar * is-only * via * Use bullets for choices * ingress-controller nginx is a distinct brand. generally this repo talks about ingress-controller, although it is quite inconsistent about how... * drop stray paren * OAuth is a brand and needs an article here also GitHub is a brand * Indent text under numbered lists * use e.g. * Document that customer header config maps changes do not trigger updates This should be removed if https://github.com/kubernetes/ingress-nginx/issues/5238 is fixed. * article * period * infinitive verb + period * clarify that the gRPC server is responsible for listening for TCP traffic and not some other part of the backend application * avoid using ; and reword * whitespace * brand: gRPC * only-does is the right form `for` adds nothing here * spelling: GitHub * punctuation `;` is generally not the right punctuation... * drop stray `to` * sentence * backticks * fix link * Improve readability of compare/vs * Renumber list * punctuation * Favor Ingress-NGINX and Ingress NGINX * Simplify custom header restart text * Undo typo damage Co-authored-by: Josh Soref <jsoref@users.noreply.github.com>
2022-01-17 00:57:28 +00:00
![Register OAuth2 Application](images/register-oauth-app.png)
2017-03-09 14:39:18 +00:00
Minor documentation cleanup (#7826) * clarify link * Add section headers * console blocks * grpc example json was not valid * multi-tls update text The preceding point 1 related to https://github.com/kubernetes-retired/contrib/blob/4f2cb51ef82b4dddb625f6053ad132c1faf07aa1/ingress/controllers/nginx/examples/ingress.yaml and the deployments referenced in https://github.com/kubernetes-retired/contrib/blob/4f2cb51ef82b4dddb625f6053ad132c1faf07aa1/ingress/controllers/nginx/examples/README.md They are not relevant to the current instructions. * add whitespace around parens * grammar setup would be a proper noun, but it is not the intended concept, which is a state * grammar * is-only * via * Use bullets for choices * ingress-controller nginx is a distinct brand. generally this repo talks about ingress-controller, although it is quite inconsistent about how... * drop stray paren * OAuth is a brand and needs an article here also GitHub is a brand * Indent text under numbered lists * use e.g. * Document that customer header config maps changes do not trigger updates This should be removed if https://github.com/kubernetes/ingress-nginx/issues/5238 is fixed. * article * period * infinitive verb + period * clarify that the gRPC server is responsible for listening for TCP traffic and not some other part of the backend application * avoid using ; and reword * whitespace * brand: gRPC * only-does is the right form `for` adds nothing here * spelling: GitHub * punctuation `;` is generally not the right punctuation... * drop stray `to` * sentence * backticks * fix link * Improve readability of compare/vs * Renumber list * punctuation * Favor Ingress-NGINX and Ingress NGINX * Simplify custom header restart text * Undo typo damage Co-authored-by: Josh Soref <jsoref@users.noreply.github.com>
2022-01-17 00:57:28 +00:00
- 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`
Minor documentation cleanup (#7826) * clarify link * Add section headers * console blocks * grpc example json was not valid * multi-tls update text The preceding point 1 related to https://github.com/kubernetes-retired/contrib/blob/4f2cb51ef82b4dddb625f6053ad132c1faf07aa1/ingress/controllers/nginx/examples/ingress.yaml and the deployments referenced in https://github.com/kubernetes-retired/contrib/blob/4f2cb51ef82b4dddb625f6053ad132c1faf07aa1/ingress/controllers/nginx/examples/README.md They are not relevant to the current instructions. * add whitespace around parens * grammar setup would be a proper noun, but it is not the intended concept, which is a state * grammar * is-only * via * Use bullets for choices * ingress-controller nginx is a distinct brand. generally this repo talks about ingress-controller, although it is quite inconsistent about how... * drop stray paren * OAuth is a brand and needs an article here also GitHub is a brand * Indent text under numbered lists * use e.g. * Document that customer header config maps changes do not trigger updates This should be removed if https://github.com/kubernetes/ingress-nginx/issues/5238 is fixed. * article * period * infinitive verb + period * clarify that the gRPC server is responsible for listening for TCP traffic and not some other part of the backend application * avoid using ; and reword * whitespace * brand: gRPC * only-does is the right form `for` adds nothing here * spelling: GitHub * punctuation `;` is generally not the right punctuation... * drop stray `to` * sentence * backticks * fix link * Improve readability of compare/vs * Renumber list * punctuation * Favor Ingress-NGINX and Ingress NGINX * Simplify custom header restart text * Undo typo damage Co-authored-by: Josh Soref <jsoref@users.noreply.github.com>
2022-01-17 00:57:28 +00:00
![Register OAuth2 Application](images/register-oauth-app-2.png)
2017-03-09 14:39:18 +00:00
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:
Minor documentation cleanup (#7826) * clarify link * Add section headers * console blocks * grpc example json was not valid * multi-tls update text The preceding point 1 related to https://github.com/kubernetes-retired/contrib/blob/4f2cb51ef82b4dddb625f6053ad132c1faf07aa1/ingress/controllers/nginx/examples/ingress.yaml and the deployments referenced in https://github.com/kubernetes-retired/contrib/blob/4f2cb51ef82b4dddb625f6053ad132c1faf07aa1/ingress/controllers/nginx/examples/README.md They are not relevant to the current instructions. * add whitespace around parens * grammar setup would be a proper noun, but it is not the intended concept, which is a state * grammar * is-only * via * Use bullets for choices * ingress-controller nginx is a distinct brand. generally this repo talks about ingress-controller, although it is quite inconsistent about how... * drop stray paren * OAuth is a brand and needs an article here also GitHub is a brand * Indent text under numbered lists * use e.g. * Document that customer header config maps changes do not trigger updates This should be removed if https://github.com/kubernetes/ingress-nginx/issues/5238 is fixed. * article * period * infinitive verb + period * clarify that the gRPC server is responsible for listening for TCP traffic and not some other part of the backend application * avoid using ; and reword * whitespace * brand: gRPC * only-does is the right form `for` adds nothing here * spelling: GitHub * punctuation `;` is generally not the right punctuation... * drop stray `to` * sentence * backticks * fix link * Improve readability of compare/vs * Renumber list * punctuation * Favor Ingress-NGINX and Ingress NGINX * Simplify custom header restart text * Undo typo damage Co-authored-by: Josh Soref <jsoref@users.noreply.github.com>
2022-01-17 00:57:28 +00:00
- 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:
```console
$ kubectl create -f oauth2-proxy.yaml
```
#### Test
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:
2017-10-13 13:55:03 +00:00
Minor documentation cleanup (#7826) * clarify link * Add section headers * console blocks * grpc example json was not valid * multi-tls update text The preceding point 1 related to https://github.com/kubernetes-retired/contrib/blob/4f2cb51ef82b4dddb625f6053ad132c1faf07aa1/ingress/controllers/nginx/examples/ingress.yaml and the deployments referenced in https://github.com/kubernetes-retired/contrib/blob/4f2cb51ef82b4dddb625f6053ad132c1faf07aa1/ingress/controllers/nginx/examples/README.md They are not relevant to the current instructions. * add whitespace around parens * grammar setup would be a proper noun, but it is not the intended concept, which is a state * grammar * is-only * via * Use bullets for choices * ingress-controller nginx is a distinct brand. generally this repo talks about ingress-controller, although it is quite inconsistent about how... * drop stray paren * OAuth is a brand and needs an article here also GitHub is a brand * Indent text under numbered lists * use e.g. * Document that customer header config maps changes do not trigger updates This should be removed if https://github.com/kubernetes/ingress-nginx/issues/5238 is fixed. * article * period * infinitive verb + period * clarify that the gRPC server is responsible for listening for TCP traffic and not some other part of the backend application * avoid using ; and reword * whitespace * brand: gRPC * only-does is the right form `for` adds nothing here * spelling: GitHub * punctuation `;` is generally not the right punctuation... * drop stray `to` * sentence * backticks * fix link * Improve readability of compare/vs * Renumber list * punctuation * Favor Ingress-NGINX and Ingress NGINX * Simplify custom header restart text * Undo typo damage Co-authored-by: Josh Soref <jsoref@users.noreply.github.com>
2022-01-17 00:57:28 +00:00
```console
$ kubectl create -f vouch-proxy.yaml
Minor documentation cleanup (#7826) * clarify link * Add section headers * console blocks * grpc example json was not valid * multi-tls update text The preceding point 1 related to https://github.com/kubernetes-retired/contrib/blob/4f2cb51ef82b4dddb625f6053ad132c1faf07aa1/ingress/controllers/nginx/examples/ingress.yaml and the deployments referenced in https://github.com/kubernetes-retired/contrib/blob/4f2cb51ef82b4dddb625f6053ad132c1faf07aa1/ingress/controllers/nginx/examples/README.md They are not relevant to the current instructions. * add whitespace around parens * grammar setup would be a proper noun, but it is not the intended concept, which is a state * grammar * is-only * via * Use bullets for choices * ingress-controller nginx is a distinct brand. generally this repo talks about ingress-controller, although it is quite inconsistent about how... * drop stray paren * OAuth is a brand and needs an article here also GitHub is a brand * Indent text under numbered lists * use e.g. * Document that customer header config maps changes do not trigger updates This should be removed if https://github.com/kubernetes/ingress-nginx/issues/5238 is fixed. * article * period * infinitive verb + period * clarify that the gRPC server is responsible for listening for TCP traffic and not some other part of the backend application * avoid using ; and reword * whitespace * brand: gRPC * only-does is the right form `for` adds nothing here * spelling: GitHub * punctuation `;` is generally not the right punctuation... * drop stray `to` * sentence * backticks * fix link * Improve readability of compare/vs * Renumber list * punctuation * Favor Ingress-NGINX and Ingress NGINX * Simplify custom header restart text * Undo typo damage Co-authored-by: Josh Soref <jsoref@users.noreply.github.com>
2022-01-17 00:57:28 +00:00
```
#### Test
Test the integration by accessing the configured URL, e.g. `https://foo.bar.com`
2017-03-09 14:39:18 +00:00
![Register OAuth2 Application](images/github-auth.png)
Minor documentation cleanup (#7826) * clarify link * Add section headers * console blocks * grpc example json was not valid * multi-tls update text The preceding point 1 related to https://github.com/kubernetes-retired/contrib/blob/4f2cb51ef82b4dddb625f6053ad132c1faf07aa1/ingress/controllers/nginx/examples/ingress.yaml and the deployments referenced in https://github.com/kubernetes-retired/contrib/blob/4f2cb51ef82b4dddb625f6053ad132c1faf07aa1/ingress/controllers/nginx/examples/README.md They are not relevant to the current instructions. * add whitespace around parens * grammar setup would be a proper noun, but it is not the intended concept, which is a state * grammar * is-only * via * Use bullets for choices * ingress-controller nginx is a distinct brand. generally this repo talks about ingress-controller, although it is quite inconsistent about how... * drop stray paren * OAuth is a brand and needs an article here also GitHub is a brand * Indent text under numbered lists * use e.g. * Document that customer header config maps changes do not trigger updates This should be removed if https://github.com/kubernetes/ingress-nginx/issues/5238 is fixed. * article * period * infinitive verb + period * clarify that the gRPC server is responsible for listening for TCP traffic and not some other part of the backend application * avoid using ; and reword * whitespace * brand: gRPC * only-does is the right form `for` adds nothing here * spelling: GitHub * punctuation `;` is generally not the right punctuation... * drop stray `to` * sentence * backticks * fix link * Improve readability of compare/vs * Renumber list * punctuation * Favor Ingress-NGINX and Ingress NGINX * Simplify custom header restart text * Undo typo damage Co-authored-by: Josh Soref <jsoref@users.noreply.github.com>
2022-01-17 00:57:28 +00:00
![GitHub authentication](images/oauth-login.png)
2017-03-09 15:09:49 +00:00
![Kubernetes dashboard](images/dashboard.png)