Fix and enhance OIDC example (#934)

* Fix and enhance OIDC example

* Restructure

* Indent

* Add full stop.

* Add link

* Add minimalistic README

* Apply suggestions from code review

Co-authored-by: Joel Speed <Joel.speed@hotmail.co.uk>

Co-authored-by: Joel Speed <Joel.speed@hotmail.co.uk>

contrib/local-environment/README.md

@@ -0,0 +1,3 @@
+# oauth2-proxy: local-environment
+
+Run `make up` to deploy local dex, etcd and oauth2-proxy instances in Docker containers. Review the [`Makefile`](Makefile) for additional deployment options.

docs/docs/configuration/auth.md

@@ -188,11 +188,40 @@ Take note of your `TenantId` if applicable for your situation. The `TenantId` ca
 
 ### OpenID Connect Provider
 
-OpenID Connect is a spec for OAUTH 2.0 + identity that is implemented by many major providers and several open source projects. This provider was originally built against CoreOS Dex and we will use it as an example.
+OpenID Connect is a spec for OAUTH 2.0 + identity that is implemented by many major providers and several open source projects.
 
-1. Launch a Dex instance using the [getting started guide](https://github.com/coreos/dex/blob/master/Documentation/getting-started.md).
+This provider was originally built against CoreOS Dex and we will use it as an example.
-2. Setup oauth2-proxy with the correct provider and using the default ports and callbacks.
+The OpenID Connect Provider (OIDC) can also be used to connect to other Identity Providers such as Okta, an example can be found below.
-3. Login with the fixture use in the dex guide and run the oauth2-proxy with the following args:
+
+#### Dex
+
+To configure the OIDC provider for Dex, perform the following steps:
+
+1. Download Dex:
+
+    ```
+    go get github.com/dexidp/dex
+    ```
+
+    See the [getting started guide](https://github.com/coreos/dex/blob/master/Documentation/getting-started.md) for more details.
+
+2. Setup oauth2-proxy with the correct provider and using the default ports and callbacks. Add a configuration block to the `staticClients` section of `examples/config-dev.yaml`:
+
+    ```
+    - id: oauth2-proxy
+    redirectURIs:
+    - 'http://127.0.0.1:4180/oauth2/callback'
+    name: 'oauth2-proxy'
+    secret: proxy
+    ```
+
+3. Launch Dex: from `$GOPATH/github.com/dexidp/dex`, run:
+
+    ```
+    bin/dex serve examples/config-dev.yaml
+    ```
+
+4. In a second terminal, run the oauth2-proxy with the following args:
 
     ```
     -provider oidc
@@ -200,15 +229,25 @@ OpenID Connect is a spec for OAUTH 2.0 + identity that is implemented by many ma
     -client-id oauth2-proxy
     -client-secret proxy
     -redirect-url http://127.0.0.1:4180/oauth2/callback
-    -oidc-issuer-url http://127.0.0.1:5556
+    -oidc-issuer-url http://127.0.0.1:5556/dex
     -cookie-secure=false
-    -email-domain example.com
+    -cookie-secret=secret
+    -email-domain kilgore.trout
     ```
 
-The OpenID Connect Provider (OIDC) can also be used to connect to other Identity Providers such as Okta. To configure the OIDC provider for Okta, perform
+    To serve the current working directory as a web site under the `/static` endpoint, add:
-the following steps:
 
-#### Configuring the OIDC Provider with Okta
+    ```
+    -upstream file://$PWD/#/static/
+    ```
+
+5. Test the setup by visiting http://127.0.0.1:4180 or http://127.0.0.1:4180/static .
+
+See also [our local testing environment](https://github.com/oauth2-proxy/oauth2-proxy/blob/master/contrib/local-environment) for a self-contained example using Docker and etcd as storage for Dex.
+
+#### Okta
+
+To configure the OIDC provider for Okta, perform the following steps:
 
 1. Log in to Okta using an administrative account. It is suggested you try this in preview first, `example.oktapreview.com`
 2. (OPTIONAL) If you want to configure authorization scopes and claims to be passed on to multiple applications,
@@ -248,13 +287,14 @@ cookie_secret = "ZZZZZ"
     skip_provider_button = true
     ```
 
-The `oidc_issuer_url` is based on URL from your **Authorization Server**'s **Issuer** field in step 2, or simply https://corp.okta.com
+The `oidc_issuer_url` is based on URL from your **Authorization Server**'s **Issuer** field in step 2, or simply https://corp.okta.com .
 The `client_id` and `client_secret` are configured in the application settings.
 Generate a unique `client_secret` to encrypt the cookie.
 
 Then you can start the oauth2-proxy with `./oauth2-proxy --config /etc/example.cfg`
 
-#### Configuring the OIDC Provider with Okta - localhost
+#### Okta - localhost
+
 1. Signup for developer account: https://developer.okta.com/signup/
 2. Create New `Web` Application: https://${your-okta-domain}/dev/console/apps/new
 3. Example Application Settings for localhost: