Improve documentation (nokia#22)

* Improve documentation

Add a flow diagram of for the OIDC plugin and OIDC provider
interaction
Add configuration parameter table
Add example request and responses

* Update README.md

* Generalize OIDC provider example

README.md

@@ -22,6 +22,27 @@ the server itself.
 Introspection functionality add capability for already authenticated users and/or applications that
 already posses acces token to go through kong. The actual token verification is then done by Resource Server.
 
+## How does it work
+
+The diagram below shows the message exchange between the involved parties.
+
+![alt Kong OIDC flow](https://github.com/Trojan295/kong-oidc/raw/issue-15/docs/kong_oidc_flow.png)
+
+The `X-Userinfo` header contains the payload from the Userinfo Endpoint
+
+```
+X-Userinfo: {"preferred_username":"alice","id":"60f65308-3510-40ca-83f0-e9c0151cc680","sub":"60f65308-3510-40ca-83f0-e9c0151cc680"}
+```
+
+The plugin also sets the `ngx.ctx.authenticated_consumer` variable, which can be using in other Kong plugins:
+```
+ngx.ctx.authenticated_consumer = {
+    id = "60f65308-3510-40ca-83f0-e9c0151cc680",   -- sub field from Userinfo
+    username = "alice"                             -- preferred_username from Userinfo
+}
+```
+
+
 ## Dependencies
 
 **kong-oidc** depends on the following package:
@@ -34,3 +55,95 @@ already posses acces token to go through kong. The actual token verification is
 If you're using `luarocks` execute the following:
 
      luarocks install kong-oidc
+
+You also need to set the `KONG_CUSTOM_PLUGINS` environment variable
+
+     export KONG_CUSTOM_PLUGINS=oidc
+     
+## Usage
+
+### Parameters
+
+| Parameter | Default  | Required | description |
+| --- | --- | --- | --- |
+| `name` || true | plugin name, has to be `oidc` |
+| `config.client_id` || true | OIDC Client ID |
+| `config.client_secret` || true | OIDC Client secret |
+| `config.discovery` | https://.well-known/openid-configuration | false | OIDC Discovery Endpoint (`/.well-known/openid-configuration`) |
+| `config.scope` | oidc | false| OAuth2 Token scope. To use OIDC it has to contains the `oidc` scope |
+| `config.ssl_verify` | false | false | Enable SSL verification to OIDC Provider |
+| `config.session_secret` | | false | Additional parameter, which is used to encrypt the session cookie. Needs to be random |
+
+### Enabling
+
+To enable the plugin only for one API:
+
+```
+POST /apis/<api_id>/plugins/ HTTP/1.1
+Host: localhost:8001
+Content-Type: application/x-www-form-urlencoded
+Cache-Control: no-cache
+
+name=oidc&config.client_id=kong-oidc&config.client_secret=29d98bf7-168c-4874-b8e9-9ba5e7382fa0&config.discovery=https%3A%2F%2F<oidc_provider>%2F.well-known%2Fopenid-configuration
+```
+
+To enable the plugin globally:
+```
+POST /apis HTTP/1.1
+Host: localhost:8001
+Content-Type: application/x-www-form-urlencoded
+Cache-Control: no-cache
+
+name=oidc&config.client_id=kong-oidc&config.client_secret=29d98bf7-168c-4874-b8e9-9ba5e7382fa0&config.discovery=https%3A%2F%2F<oidc_provider>%2F.well-known%2Fopenid-configuration
+```
+
+A successful response:
+```
+HTTP/1.1 201 Created
+Date: Tue, 24 Oct 2017 19:37:38 GMT
+Content-Type: application/json; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+Access-Control-Allow-Origin: *
+Server: kong/0.11.0
+
+{
+    "created_at": 1508871239797,
+    "config": {
+        "response_type": "code",
+        "client_id": "kong-oidc",
+        "discovery": "https://<oidc_provider>/.well-known/openid-configuration",
+        "scope": "openid",
+        "ssl_verify": "no",
+        "client_secret": "29d98bf7-168c-4874-b8e9-9ba5e7382fa0",
+        "token_endpoint_auth_method": "client_secret_post"
+    },
+    "id": "58cc119b-e5d0-4908-8929-7d6ed73cb7de",
+    "enabled": true,
+    "name": "oidc",
+    "api_id": "32625081-c712-4c46-b16a-5d6d9081f85f"
+}
+```
+
+### Upstream API request
+
+The plugin adds a additional `X-Userinfo` header to the upstream request, which can be consumer by upstream server:
+
+```
+GET / HTTP/1.1
+Host: netcat:9000
+Connection: keep-alive
+X-Forwarded-For: 172.19.0.1
+X-Forwarded-Proto: http
+X-Forwarded-Host: localhost
+X-Forwarded-Port: 8000
+X-Real-IP: 172.19.0.1
+Cache-Control: max-age=0
+User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/61.0.3163.100 Safari/537.36
+Upgrade-Insecure-Requests: 1
+Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8
+Accept-Encoding: gzip, deflate
+Accept-Language: pl-PL,pl;q=0.8,en-US;q=0.6,en;q=0.4
+Cookie: session=KOn1am4mhQLKazlCA.....
+X-Userinfo: {"preferred_username":"alice","id":"60f65308-3510-40ca-83f0-e9c0151cc680","sub":"60f65308-3510-40ca-83f0-e9c0151cc680"}
+```