> For the complete documentation index, see [llms.txt](https://rocdu.gitbook.io/ingress-nginx-docs-cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rocdu.gitbook.io/ingress-nginx-docs-cn/docs/examples/auth/oauth-external-auth.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 `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:

```yaml
...
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`](https://github.com/pusher/oauth2_proxy) into a Kubernetes cluster and use it to protect the Kubernetes Dashboard using github as 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
```

1. Create a [custom Github OAuth application](https://github.com/settings/applications/new)

![Register OAuth2 Application](https://2115764490-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Lt98ioOKNGkWgrAdshG%2F-Lt99I5lem3Hdo4AoDDO%2F-Lt99L9gC3QXij0EA2Ya%2Fregister-oauth-app.png?generation=1573202260804085\&alt=media)

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

![Register OAuth2 Application](https://2115764490-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Lt98ioOKNGkWgrAdshG%2F-Lt99I5lem3Hdo4AoDDO%2F-Lt99L9ii2khdjW7FZfn%2Fregister-oauth-app-2.png?generation=1573202257723373\&alt=media)

1. Configure oauth2\_proxy values in the file oauth2-proxy.yaml with the values:
2. OAUTH2\_PROXY\_CLIENT\_ID with the github `<Client ID>`
3. OAUTH2\_PROXY\_CLIENT\_SECRET with the github `<Client Secret>`
4. OAUTH2\_PROXY\_COOKIE\_SECRET with value of `python -c 'import os,base64; print base64.b64encode(os.urandom(16))'`
5. Customize the contents of the file dashboard-ingress.yaml:

Replace `__INGRESS_HOST__` with a valid FQDN and `__INGRESS_SECRET__` with a Secret with a valid SSL certificate.

1. Deploy the oauth2 proxy and the ingress rules running:

```
$ kubectl create -f oauth2-proxy.yaml,dashboard-ingress.yaml
```

Test the oauth integration accessing the configured URL, like `https://foo.bar.com`

![Register OAuth2 Application](https://2115764490-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Lt98ioOKNGkWgrAdshG%2F-Lt99I5lem3Hdo4AoDDO%2F-Lt99L9kqfZqCFjGhu3f%2Fgithub-auth.png?generation=1573202257481099\&alt=media)

![Github authentication](https://2115764490-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Lt98ioOKNGkWgrAdshG%2F-Lt99I5lem3Hdo4AoDDO%2F-Lt99L9mOQvslX3hUB5Y%2Foauth-login.png?generation=1573202260447493\&alt=media)

![Kubernetes dashboard](https://2115764490-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Lt98ioOKNGkWgrAdshG%2F-Lt99I5lem3Hdo4AoDDO%2F-Lt99L9oBtwLeMPo-l-o%2Fdashboard.png?generation=1573202257545264\&alt=media)