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,27 +188,66 @@ 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
     -provider-display-name "My OIDC Provider"
     -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,
@@ -231,30 +270,31 @@ you may wish to configure an authorization server for each application. Otherwis
 * Under **Assignments** select the users or groups you wish to access your application.
 4. Create a configuration file like the following:
 
-```
+    ```
-provider = "oidc"
+    provider = "oidc"
-redirect_url = "https://example.corp.com/oauth2/callback"
+    redirect_url = "https://example.corp.com/oauth2/callback"
-oidc_issuer_url = "https://corp.okta.com/oauth2/abCd1234"
+    oidc_issuer_url = "https://corp.okta.com/oauth2/abCd1234"
-upstreams = [
+    upstreams = [
-    "https://example.corp.com"
+        "https://example.corp.com"
-]
+    ]
-email_domains = [
+    email_domains = [
-    "corp.com"
+        "corp.com"
-]
+    ]
-client_id = "XXXXX"
+    client_id = "XXXXX"
-client_secret = "YYYYY"
+    client_secret = "YYYYY"
-pass_access_token = true
+    pass_access_token = true
-cookie_secret = "ZZZZZ"
+    cookie_secret = "ZZZZZ"
-skip_provider_button = true
+    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:
@@ -267,25 +307,25 @@ Then you can start the oauth2-proxy with `./oauth2-proxy --config /etc/example.c
 4. Make note of the `Client ID` and `Client secret`, they are needed in a future step
 5. Make note of the **default** Authorization Server Issuer URI from: https://${your-okta-domain}/admin/oauth2/as
 6. Example config file `/etc/localhost.cfg`
-   ```
+    ```
-   provider = "oidc"
+    provider = "oidc"
-   redirect_url = "http://localhost:4180/oauth2/callback"
+    redirect_url = "http://localhost:4180/oauth2/callback"
-   oidc_issuer_url = "https://${your-okta-domain}/oauth2/default"
+    oidc_issuer_url = "https://${your-okta-domain}/oauth2/default"
-   upstreams = [
+    upstreams = [
-       "http://0.0.0.0:8080"
+        "http://0.0.0.0:8080"
-   ]
+    ]
-   email_domains = [
+    email_domains = [
-       "*"
+        "*"
-   ]
+    ]
-   client_id = "XXX"
+    client_id = "XXX"
-   client_secret = "YYY"
+    client_secret = "YYY"
-   pass_access_token = true
+    pass_access_token = true
-   cookie_secret = "ZZZ"
+    cookie_secret = "ZZZ"
-   cookie_secure = false
+    cookie_secure = false
-   skip_provider_button = true
+    skip_provider_button = true
-   # Note: use the following for testing within a container
+    # Note: use the following for testing within a container
-   # http_address = "0.0.0.0:4180"
+    # http_address = "0.0.0.0:4180"
-   ```
+    ```
 7. Then you can start the oauth2-proxy with `./oauth2-proxy --config /etc/localhost.cfg`
 
 ### login.gov Provider