Issue 6355: update api/.../jwt_authn/.../README.md

larrywest · larrywest · commit 6ad16804aa99 · 2019-03-26T15:04:51.000-07:00
To describe the (updated) functionality of the value_prefix field.

Signed-off-by: Larry West &lt;Larry_West@intuit.com&gt;
diff --git a/api/envoy/config/filter/http/jwt_authn/v2alpha/README.md b/api/envoy/config/filter/http/jwt_authn/v2alpha/README.md
@@ -29,3 +29,38 @@ If a custom location is desired, `from_headers` or `from_params` can be used to
 ## HTTP header to pass successfully verified JWT
 
 If a JWT is valid, its payload will be passed to the backend in a new HTTP header specified in `forward_payload_header` field. Its value is base64 encoded JWT payload in JSON.
+
+
+## Further header options
+
+In addition to the `name` field, which specifies the HTTP header name,
+the `from_headers` section can specify an optional `value_prefix` value, as in:
+
+```yaml
+    from_headers:
+      - name: bespoke
+        value_prefix: jwt_value
+```
+
+The above will cause the jwt_authn filter to look for the JWT in the `bespoke` header, following the tag `jwt_value`.
+
+Any non-JWT characters (i.e., anything _other than_ alphanumerics, `_`, `-`, and `.`) will be skipped,
+and all following, contiguous, JWT-legal chars will be taken as the JWT.
+
+This means all of the following will return a JWT of `eyJFbnZveSI6ICJyb2NrcyJ9.e30.c2lnbmVk`:
+
+```text
+bespoke: jwt_value=eyJFbnZveSI6ICJyb2NrcyJ9.e30.c2lnbmVk
+
+bespoke: {"jwt_value": "eyJFbnZveSI6ICJyb2NrcyJ9.e30.c2lnbmVk"}
+
+bespoke: beta:true,jwt_value:"eyJFbnZveSI6ICJyb2NrcyJ9.e30.c2lnbmVk",trace=1234
+```
+
+The header `name` may be `Authorization`.
+
+The `value_prefix` must match exactly, i.e., case-sensitively.
+If the `value_prefix` is not found, the header is skipped: not considered as a source for a JWT token.
+
+If there are no JWT-legal characters after the `value_prefix`, the entire string after it
+is taken to be the JWT token. This is unlikely to succeed; the error will reported by the JWT parser.
