oathkeeper: Document ID Token changes (#195)

docs/oathkeeper/pipeline/mutator.md

@@ -185,14 +185,43 @@ The first private key found in the JSON Web Key Set defined by
 
 ### Per-Rule Configuration
 
-Additionally, this mutator allows you to specify the audience of the ID token
-per access rule. Setting the audience is optional:
+Additionally, this mutator allows you to specify custom claims, like the audience of ID tokens,
+via the `claims` field of the mutator's `config` field. The keys represent names of claims and the values
+are arbitrary data structures which will be parsed by the Go [text/template](https://golang.org/pkg/text/template/)
+package for value substitution, receiving the
+[AuthenticationSession](https://github.com/ory/oathkeeper/blob/92c09fb28552949cd034ed5555c87dfda91407a3/proxy/authenticator.go#L19)
+struct:
+
+```go
+type AuthenticationSession struct {
+	Subject string
+	Extra   map[string]interface{}
+	Header  http.Header
+}
+```
+
+Note that the `AuthenticationSession` struct has a field named `Extra` which is
+a `map[string]interface{}`, which receives varying introspection data from the
+authentication process. Because the contents of `Extra` are so variable, nested
+and potentially non-existent values need special handling by the `text/template`
+parser, and a `print` FuncMap function has been provided to ensure
+that non-existent map values will simply return an empty string, rather
+than `<no value>`.
+
+If you find that your claims contain the string `<no value>` then you have most
+likely omitted the `print` function, and it is recommended you use it for all
+values out of an abundance of caution and for consistency.
+
+Custom claims are optional:
 
 ```json
 {
   "handler": "id_token",
   "config": {
-    "aud": ["https://my-backend-service/some/endpoint"]
+    "claims": {
+      "aud": ["https://my-backend-service/some/endpoint"],
+      "def": "{{ print .Extra.some.arbitrary.data }}"
+    }
   }
 }
 ```
@@ -227,7 +256,11 @@ $ cat ./rules.json
         "aud": [
           "audience-1",
           "audience-2"
-        ]
+        ],
+        "claims": {
+          "abc": "{{ print .Subject }}",
+          "def": "{{ print .Extra.some.arbitrary.data }}"
+        }
       }
     }
   ]
@@ -347,11 +380,11 @@ type AuthenticationSession struct {
 }
 ```
 
-Note that the `AuthenticationSession` struct has a field name `Extra` which is a
+Note that the `AuthenticationSession` struct has a field named `Extra` which is a
 `map[string]interface{}`, which receives varying introspection data from the
 authentication process. Because the contents of `Extra` are so variable, nested
 and potentially non-existent values need special handling by the `text/template`
-parser, and a `print` FuncMap function has been provided to ensure the
+parser, and a `print` FuncMap function has been provided to ensure that
 non-existent map values will simply return an empty string, rather than
 `<no value>`.