doc: add doc for Jwt_authn filter by qiwzhang · Pull Request #4527 · envoyproxy/envoy

qiwzhang · 2018-09-25T17:37:23Z

Description: update doc for jwt_authn http filter

format config.proto comment for doc
add a new rst file: docs/root/configuration/http_filters/jwt_authn_filter.rst

Risk Level: None

Docs Changes: Yes

Signed-off-by: Wayne Zhang <qiwzhang@google.com>

qiwzhang · 2018-09-25T17:37:58Z

@lizan @htuch could you help to review it

Signed-off-by: Wayne Zhang <qiwzhang@google.com>

qiwzhang · 2018-09-25T22:24:53Z

Ready for review. PTAL

htuch

Thanks for putting this together, first round of feedback.

htuch · 2018-09-26T17:56:28Z

api/envoy/config/filter/http/jwt_authn/v2alpha/config.proto

 //
 //    - match:
-//         prefix: "/healthz"
+//        prefix: "/healthz"


Nit: can drop these superfluous "..." in the YAML fragments.

htuch · 2018-09-26T17:57:30Z

docs/root/configuration/http_filters/jwt_authn_filter.rst

+JWT Authentication
+==================
+
+This HTTP filter can be used to verify JSON Web Token (JWT). It will verify its signature, expiration time, audiences and issuer. If the JWT verification fails, its request will be rejected. If the JWT verification success, its payload could be forwarded to the upstream for further authorization if desired.


s/success/succeeds/, s/could be forwarded/can be forwarded/

htuch · 2018-09-26T17:57:55Z

docs/root/configuration/http_filters/jwt_authn_filter.rst

+Configuration
+-------------
+
+This HTTP :ref:`filer config <envoy_api_msg_config.filter.http.jwt_authn.v2alpha.JwtAuthentication>` has two fields, *providers* and *rules*. Field *providers* specifies how a JWT should be verified, such as where to extract the token, where to fetch the public key (JWKS) and where to output its payload. Field *rules* specifies matching rules and their requirements. It a request matches a rule, its requirement applies. The requirement specifies which JWT providers should be used.


s/filer config/filter config/

s/It a request matches/If a request matches/

htuch · 2018-09-26T17:58:34Z

docs/root/configuration/http_filters/jwt_authn_filter.rst

+JwtProvider
+~~~~~~~~~~~
+
+:ref:`JwtProvider <envoy_api_msg_config.filter.http.jwt_authn.v2alpha.JwtProvider>` specifies how a JWT should be verified. It has following fields:


s/It has following/It has the following/

htuch · 2018-09-26T17:59:00Z

docs/root/configuration/http_filters/jwt_authn_filter.rst

+
+* *issuer*: the principal that issued the JWT, usually a URL or an email address.
+* *audiences*: a list of JWT audiences allowed to access. A JWT containing any of these audiences will be accepted.
+  If not specified, will not check audiences in the JWT.


If not specified, the audience will not be checked in the JWT.

htuch · 2018-09-26T17:59:42Z

docs/root/configuration/http_filters/jwt_authn_filter.rst

+* *forward*: if true, JWT will be forwarded to the upstream.
+* *from_headers*: extract JWT from HTTP headers.
+* *from_params*: extract JWT from query parameters.
+* *forward_payload_header*: forward the JWT payload in the specified HTTP header.


Ideally most of the field descriptions can be figure out from the proto docs, but if you want to include it here, this is good. We do need to make sure they stay in sync though.

htuch · 2018-09-26T18:00:23Z

docs/root/configuration/http_filters/jwt_authn_filter.rst

+
+  Authorization: Bearer <token>
+
+If fails to extract a JWT from above header, then check query parameter key *access_token* as this example::


s/as this example/as in this example/

htuch · 2018-09-26T18:01:09Z

docs/root/configuration/http_filters/jwt_authn_filter.rst

+
+**Important note** for *remote_jwks*, a **jwks_cluster** cluster is required for Envoy to talk to a JWKS server. Due to this, `OpenID connection discovery <https://openid.net/specs/openid-connect-discovery-1_0.html>`_ is not supported since the URL to fetch JWKS is in the response of the discovery. It is not easy to setup a cluster config for a dynamic URL.
+
+JwtProvider config example one


Prefer semantic naming of config examples to "one"/"two", e.g. "simple", "header-based"..

htuch · 2018-09-26T18:02:54Z

docs/root/configuration/http_filters/jwt_authn_filter.rst

+
+* *provider_name* is **provider_name1**
+* *issuer* is **https://example.com**
+* *audiences*: **bookstore_android.apps.googleusercontent.com** and **bookstore_web.apps.googleusercontent.com**


I don't think we need the trivial field correspondences to be explained, only the ones with some point-of-interest.

htuch · 2018-09-26T19:30:07Z

docs/root/configuration/http_filters/jwt_authn_filter.rst

+RequirementRule
+~~~~~~~~~~~~~~~
+
+:ref:`RequirementRule <envoy_api_msg_config.filter.http.jwt_authn.v2alpha.RequirementRule>` has two fields: *match* and *requires*. The field *match* specifies how a request can be matched; e.g. by HTTP headers, or by query parameters, or by path prefixes. The field *requires* specifies the JWT requirement, e.g. which provider is required. Multiple providers may be required in such complex forms as "require_all" or "require_any".


Something like this seems to make sense to do inline in the API docs rather than independent RST.

Removed most of them

potatop · 2018-09-26T19:39:00Z

docs/root/configuration/http_filters/jwt_authn_filter.rst

+JWT Authentication
+==================
+
+This HTTP filter can be used to verify JSON Web Token (JWT). It will verify its signature, expiration time, audiences and issuer. If the JWT verification fails, its request will be rejected. If the JWT verification success, its payload could be forwarded to the upstream for further authorization if desired.


There is a check for not before time too

envoy/source/extensions/filters/http/jwt_authn/authenticator.cc

Line 135 in 9bd3805

if (jwt_->nbf_ > unix_timestamp) {

potatop · 2018-09-26T19:47:11Z

docs/root/configuration/http_filters/jwt_authn_filter.rst

+
+  /path?access_token=<JWT>
+
+In the :ref:`filter config <envoy_api_msg_config.filter.http.jwt_authn.v2alpha.JwtAuthentication>`, *providers* is a map, to map *provider_name* to a :ref:`JwtProvider <envoy_api_msg_config.filter.http.jwt_authn.v2alpha.JwtProvider>`. The *provider_name* has to be unique, it is referred in the `JwtRequirement <envoy_api_msg_config.filter.http.jwt_authn.v2alpha.JwtRequirement>` in its *provider_name* field.


The *provider_name* must be unique?

Signed-off-by: Wayne Zhang <qiwzhang@google.com>

htuch

Looks good, one last minor change from my side.

htuch · 2018-10-02T21:48:52Z

docs/root/configuration/http_filters/jwt_authn_filter.rst

+* Field *match* specifies how a request can be matched; e.g. by HTTP headers, or by query parameters, or by path prefixes.
+* Field *requires* specifies the JWT requirement, e.g. which provider is required.
+
+**Important notes:**


Can you use Sphinx RST directives for this? http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives

Signed-off-by: Wayne Zhang <qiwzhang@google.com>

lizan · 2018-10-03T08:49:09Z

api/envoy/config/filter/http/jwt_authn/v2alpha/config.proto

-// the authentication flow.
+// Please see following for JWT authentication flow:
+//
+// * `JWT format <https://tools.ietf.org/html/rfc7519>`_


nit: Can you update the link title matches the document linked to?
i.e. JSON Web Token (JWT), The OAuth 2.0 Authorization Framework, OpenID Connect

lizan · 2018-10-03T08:51:28Z

docs/root/configuration/http_filters/jwt_authn_filter.rst

+    hosts:
+      socket_address:
+        address: example.com
+        portValue: 80


nit: port_value

Signed-off-by: Wayne Zhang <qiwzhang@google.com>

docs/root/configuration/http_filters/jwt_authn_filter.rst

Signed-off-by: Wayne Zhang <qiwzhang@google.com>

N/A

update doc for jwt_authn http filter format config.proto comment for doc add a new rst file: docs/root/configuration/http_filters/jwt_authn_filter.rst Risk Level: None Docs Changes: Yes Signed-off-by: Wayne Zhang <qiwzhang@google.com> Signed-off-by: Aaltan Ahmad <aa@stripe.com>

qiwzhang added 8 commits September 25, 2018 17:26

polish jwt_authn config.proto

0ceefa3

Signed-off-by: Wayne Zhang <qiwzhang@google.com>

Fix format for jwt_authn config.proto

47e9949

Signed-off-by: Wayne Zhang <qiwzhang@google.com>

Add jwt_authn_filter.rst

e945fea

Signed-off-by: Wayne Zhang <qiwzhang@google.com>

update 2nd draft

18a967d

Signed-off-by: Wayne Zhang <qiwzhang@google.com>

update 3rd draft

0e0e590

Signed-off-by: Wayne Zhang <qiwzhang@google.com>

update 4th draft

59d5bfb

Signed-off-by: Wayne Zhang <qiwzhang@google.com>

5ft draft

dcbba99

Signed-off-by: Wayne Zhang <qiwzhang@google.com>

format

a071636

Signed-off-by: Wayne Zhang <qiwzhang@google.com>

lizan self-assigned this Sep 25, 2018

update format

bc7e015

Signed-off-by: Wayne Zhang <qiwzhang@google.com>

htuch self-assigned this Sep 25, 2018

update format again

da83130

Signed-off-by: Wayne Zhang <qiwzhang@google.com>

htuch suggested changes Sep 26, 2018

View reviewed changes

potatop reviewed Sep 26, 2018

View reviewed changes

qiwzhang added 2 commits October 2, 2018 18:48

Update per review

2ae366c

Signed-off-by: Wayne Zhang <qiwzhang@google.com>

remove double quote

197f297

Signed-off-by: Wayne Zhang <qiwzhang@google.com>

htuch previously requested changes Oct 2, 2018

View reviewed changes

qiwzhang added 2 commits October 2, 2018 22:00

use attention rst

1549260

Signed-off-by: Wayne Zhang <qiwzhang@google.com>

fix annotation usage error

aeec5f3

Signed-off-by: Wayne Zhang <qiwzhang@google.com>

lizan reviewed Oct 3, 2018

View reviewed changes

update link titles

8994580

Signed-off-by: Wayne Zhang <qiwzhang@google.com>

lizan reviewed Oct 3, 2018

View reviewed changes

docs/root/configuration/http_filters/jwt_authn_filter.rst Outdated Show resolved Hide resolved

update another link title

3a98356

Signed-off-by: Wayne Zhang <qiwzhang@google.com>

lizan approved these changes Oct 3, 2018

View reviewed changes

htuch merged commit d101ae7 into envoyproxy:master Oct 3, 2018


		Authorization: Bearer <token>

		If fails to extract a JWT from above header, then check query parameter key access_token as this example::


		Important note for remote_jwks, a jwks_cluster cluster is required for Envoy to talk to a JWKS server. Due to this, `OpenID connection discovery <https://openid.net/specs/openid-connect-discovery-1_0.html>`_ is not supported since the URL to fetch JWKS is in the response of the discovery. It is not easy to setup a cluster config for a dynamic URL.

		JwtProvider config example one


		/path?access_token=<JWT>

		In the :ref:`filter config <envoy_api_msg_config.filter.http.jwt_authn.v2alpha.JwtAuthentication>`, providers is a map, to map provider_name to a :ref:`JwtProvider <envoy_api_msg_config.filter.http.jwt_authn.v2alpha.JwtProvider>`. The provider_name has to be unique, it is referred in the `JwtRequirement <envoy_api_msg_config.filter.http.jwt_authn.v2alpha.JwtRequirement>` in its provider_name field.

Conversation

qiwzhang commented Sep 25, 2018

Uh oh!

qiwzhang commented Sep 25, 2018

Uh oh!

qiwzhang commented Sep 25, 2018

Uh oh!

htuch left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

htuch left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants