oathkeeper: Document mutator changes (#193)

ory · Aug 12, 2019 · 0602c91 · 0602c91
1 parent 7935b20
commit 0602c91
Show file tree

Hide file tree

Showing 8 changed files with 118 additions and 83 deletions.
diff --git a/apis/oathkeeper.json b/apis/oathkeeper.json
@@ -2027,8 +2027,13 @@
         "match": {
           "$ref": "#/definitions/ruleMatch"
         },
-        "mutator": {
-          "$ref": "#/definitions/ruleHandler"
+        "mutators": {
+          "description": "Mutators is a list of mutation handlers that transform the HTTP request. A common use case is generating a new set of credentials (e.g. JWT) which then will be forwarded to the upstream server. Mutations are performed iteratively from index 0 to n and should all succeed in order for the HTTP request to be forwarded.",
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/ruleHandler"
+          },
+          "x-go-name": "Mutators"
         },
         "upstream": {
           "$ref": "#/definitions/Upstream"

diff --git a/docs/oathkeeper/api-access-rules.md b/docs/oathkeeper/api-access-rules.md
@@ -101,7 +101,7 @@ Access Rules have four principal keys:
   For example, you could check if the subject ("user") is part of the "admin"
   group or if he/she has permission to perform that action. For the full list of
   available authorizers, click [here](pipeline/authz.md).
-- `mutator`: Transform the HTTP request before forwarding it. A common use case
+- `mutators`: A list of mutation handlers that transform the HTTP request before forwarding it. A common use case
   is generating a new set of credentials (e.g. JWT) which then will be forwarded
   to the upstream server. When using ORY Oathkeeper's Decision API, it is
   expected that the API Gateway forwards the mutated HTTP Headers to the
@@ -126,7 +126,7 @@ Rule in JSON format:
   },
   "authenticators": [{ "handler": "noop" }],
   "authorizer": { "handler": "allow" },
-  "mutator": { "handler": "noop" }
+  "mutators": [{ "handler": "noop" }]
 }
 ```
 
@@ -147,8 +147,8 @@ authenticators:
   - handler: noop
 authorizer:
   hander: allow
-mutator:
-  handler: noop
+mutators:
+  - handler: noop
 ```
 
 ## Scoped Credentials

diff --git a/docs/oathkeeper/configure-deploy.md b/docs/oathkeeper/configure-deploy.md
@@ -103,14 +103,16 @@ $ cat << EOF > rules.json
     "authorizer": {
       "handler": "allow"
     },
-    "mutator": {
-      "handler": "header",
-      "config": {
-        "headers": {
-          "X-User": "{{ print .Subject }}"
+    "mutators": [
+      {
+        "handler": "header",
+        "config": {
+          "headers": {
+            "X-User": "{{ print .Subject }}"
+          }
         }
       }
-    }
+    ]
   },
   {
     "id": "deny-anonymous",
@@ -131,9 +133,11 @@ $ cat << EOF > rules.json
     "authorizer": {
       "handler": "deny"
     },
-    "mutator": {
-      "handler": "noop"
-    }
+    "mutators": [
+      {
+        "handler": "noop"
+      }
+    ]
   },
   {
     "id": "allow-anonymous-with-id-token-mutator",
@@ -154,9 +158,11 @@ $ cat << EOF > rules.json
     "authorizer": {
       "handler": "allow"
     },
-    "mutator": {
-      "handler": "id_token"
-    }
+    "mutators": [
+      {
+        "handler": "id_token"
+      }
+    ]
   }
 ]
 EOF

diff --git a/docs/oathkeeper/index.md b/docs/oathkeeper/index.md
@@ -83,9 +83,11 @@ and you have the following rule defined (which allows this request)
   "authorizer": {
     "handler": "allow"
   },
-  "mutator": {
-    "handler": "noop"
-  }
+  "mutators": [
+    {
+      "handler": "noop"
+    }
+  ]
 }
 ```
 
@@ -145,9 +147,11 @@ and you have the following rule defined (which allows this request)
   "authorizer": {
     "handler": "allow"
   },
-  "mutator": {
-    "handler": "noop"
-  }
+  "mutators": [
+    {
+      "handler": "noop"
+    }
+  ]
 }
 ```
 

diff --git a/docs/oathkeeper/pipeline/authn.md b/docs/oathkeeper/pipeline/authn.md
@@ -63,7 +63,7 @@ too.
 ## `noop`
 
 The `noop` handler tells ORY Oathkeeper to bypass authentication, authorization,
-and mutator. This implies that no authorization will be executed and no
+and mutation. This implies that no authorization will be executed and no
 credentials will be issued. It's basically a pass-all authenticator that allows
 any request to be forwarded to the upstream URL.
 
@@ -195,7 +195,7 @@ $ cat ./rules.json
     "handler": "anonymous"
   }],
   "authorizer": { "handler": "allow" },
-  "mutator": { "handler": "noop" }
+  "mutators": [{ "handler": "noop" }]
 }]
 
 $ curl -X GET http://my-app/some-route
@@ -257,7 +257,7 @@ $ cat ./rules.json
     "handler": "cookie_session"
   }],
   "authorizer": { "handler": "allow" },
-  "mutator": { "handler": "noop" }
+  "mutators": [{ "handler": "noop" }]
 }]
 
 $ curl -X GET -b sessionid=abc http://my-app/some-route
@@ -337,7 +337,7 @@ $ cat ./rules.json
     }
   }],
   "authorizer": { "handler": "allow" },
-  "mutator": { "handler": "noop" }
+  "mutators": [{ "handler": "noop" }]
 }]
 
 $ curl -X GET http://my-app/some-route
@@ -460,7 +460,7 @@ $ cat ./rules.json
     }
   }],
   "authorizer": { "handler": "allow" },
-  "mutator": { "handler": "noop" }
+  "mutators": [{ "handler": "noop" }]
 }]
 
 $ curl -X GET http://my-app/some-route
@@ -629,7 +629,7 @@ $ cat ./rules.json
     }
   }],
   "authorizer": { "handler": "allow" },
-  "mutator": { "handler": "noop" }
+  "mutators": [{ "handler": "noop" }]
 }]
 
 $ curl -X GET http://my-app/some-route

diff --git a/docs/oathkeeper/pipeline/authz.md b/docs/oathkeeper/pipeline/authz.md
@@ -62,7 +62,7 @@ $ cat ./rules.json
   },
   "authenticators": [{ "handler": "anonymous" }],
   "authorizer": { "handler": "allow" },
-  "mutator": { "handler": "noop" }
+  "mutators": [{ "handler": "noop" }]
 }]
 
 $ curl -X GET http://my-app/some-route
@@ -105,7 +105,7 @@ $ cat ./rules.json
   },
   "authenticators": [{ "handler": "anonymous" }],
   "authorizer": { "handler": "deny" },
-  "mutator": { "handler": "noop" }
+  "mutators": [{ "handler": "noop" }]
 }]
 
 $ curl -X GET http://my-app/some-route
@@ -248,8 +248,10 @@ $ cat ./rules.json
       "flavor": "exact"
     }
   }
-  "mutator": {
-    "handler": "noop"
-  }
+  "mutators": [
+    {
+      "handler": "noop"
+    }
+  ]
 }]
 ```
diff --git a/docs/oathkeeper/pipeline/mutator.md b/docs/oathkeeper/pipeline/mutator.md
@@ -53,9 +53,11 @@ $ cat ./rules.json
   "authorizer": {
     "handler": "allow"
   },
-  "mutator": {
-    "handler": "noop"
-  }
+  "mutators": [
+    {
+      "handler": "noop"
+    }
+  ]
 }
 
 $ curl -X GET http://my-app/some-route
@@ -218,15 +220,17 @@ $ cat ./rules.json
   "authorizer": {
     "handler": "allow"
   },
-  "mutator": {
-    "handler": "id_token",
-    "config": {
-      "aud": [
-        "audience-1",
-        "audience-2"
-      ]
+  "mutators": [
+    {
+      "handler": "id_token",
+      "config": {
+        "aud": [
+          "audience-1",
+          "audience-2"
+        ]
+      }
     }
-  }
+  ]  
 }
 ```
 
@@ -295,15 +299,17 @@ values out of an abundance of caution and for consistency.
   "authorizer": {
     "handler": "allow"
   },
-  "mutator": {
-    "handler": "headers",
-    "config": {
-      "headers": {
-        "X-User": "{{ print .Subject }}",
-        "X-Some-Arbitrary-Data": "{{ print .Extra.some.arbitrary.data }}"
+  "mutators": [
+    {
+      "handler": "headers",
+      "config": {
+        "headers": {
+          "X-User": "{{ print .Subject }}",
+          "X-Some-Arbitrary-Data": "{{ print .Extra.some.arbitrary.data }}"
+        }
       }
     }
-  }
+  ]
 }
 ```
 
@@ -371,14 +377,16 @@ values out of an abundance of caution and for consistency.
   "authorizer": {
     "handler": "allow"
   },
-  "mutator": {
-    "handler": "cookies",
-    "config": {
-      "cookies": {
-        "user": "{{ print .Subject }}",
-        "some-arbitrary-data": "{{ print .Extra.some.arbitrary.data }}"
+  "mutators": [
+    {
+      "handler": "cookies",
+      "config": {
+        "cookies": {
+          "user": "{{ print .Subject }}",
+          "some-arbitrary-data": "{{ print .Extra.some.arbitrary.data }}"
+        }
       }
     }
-  }
+  ]
 }
 ```