doc: add doc for Jwt_authn filter (#4527)

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> Mirrored from https://github.com/envoyproxy/envoy @ d101ae7decfdae148f53ea9d2220444c726dfbfd
7 years ago · abab76a914
parent 0e0bd7ff9e
commit abab76a914
2 changed files with 60 additions and 52 deletions
--- a/docs/BUILD
+++ b/docs/BUILD
@ -36,6 +36,7 @@ proto_library(
        "//envoy/config/filter/http/header_to_metadata/v2:header_to_metadata",
        "//envoy/config/filter/http/health_check/v2:health_check",
        "//envoy/config/filter/http/ip_tagging/v2:ip_tagging",
+        "//envoy/config/filter/http/jwt_authn/v2alpha:jwt_authn",
        "//envoy/config/filter/http/lua/v2:lua",
        "//envoy/config/filter/http/rate_limit/v2:rate_limit",
        "//envoy/config/filter/http/rbac/v2:rbac",
--- a/envoy/config/filter/http/jwt_authn/v2alpha/config.proto
+++ b/envoy/config/filter/http/jwt_authn/v2alpha/config.proto
@ -11,10 +11,19 @@ import "google/protobuf/empty.proto";
 import "google/protobuf/wrappers.proto";
 import "validate/validate.proto";

-// This message specifies how a JSON Web Token (JWT) can be verified. JWT format is defined
-// `here <https://tools.ietf.org/html/rfc7519>`_. Please see `OAuth2.0
-//  <https://tools.ietf.org/html/rfc6749>`_ and `OIDC1.0  <http://openid.net/connect>`_ for
-// the authentication flow.
+// Please see following for JWT authentication flow:
+//
+// * `JSON Web Token (JWT) <https://tools.ietf.org/html/rfc7519>`_
+// * `The OAuth 2.0 Authorization Framework <https://tools.ietf.org/html/rfc6749>`_
+// * `OpenID Connect <http://openid.net/connect>`_
+//
+// A JwtProvider message specifies how a JSON Web Token (JWT) can be verified. It specifies:
+//
+// * issuer: the principal that issues the JWT. It has to match the one from the token.
+// * allowed audiences: the ones in the token have to be listed here.
+// * how to fetch public key JWKS to verify the token signature.
+// * how to extract JWT token in the request.
+// * how to pass successfully verified token payload.
 //
 // Example:
 //
@ -32,15 +41,15 @@ import "validate/validate.proto";
 //         seconds: 300
 //
 message JwtProvider {
-  // Identifies the principal that issued the JWT. See `here
-  //  <https://tools.ietf.org/html/rfc7519#section-4.1.1>`_. Usually a URL or an email address.
+  // Specify the `principal <https://tools.ietf.org/html/rfc7519#section-4.1.1>`_ that issued
+  // the JWT, usually a URL or an email address.
  //
  // Example: https://securetoken.google.com
  // Example: 1234567-compute@developer.gserviceaccount.com
  //
  string issuer = 1 [(validate.rules).string.min_bytes = 1];

-  // The list of JWT `audiences <https://tools.ietf.org/html/rfc7519#section-4.1.3>`_. that are
+  // The list of JWT `audiences <https://tools.ietf.org/html/rfc7519#section-4.1.3>`_ are
  // allowed to access. A JWT containing any of these audiences will be accepted. If not specified,
  // will not check audiences in the token.
  //
@ -54,8 +63,8 @@ message JwtProvider {
  //
  repeated string audiences = 2;

-  // `JSON Web Key Set <https://tools.ietf.org/html/rfc7517#appendix-A>`_ is needed. to validate
-  // signature of the JWT. This field specifies where to fetch JWKS.
+  // `JSON Web Key Set (JWKS) <https://tools.ietf.org/html/rfc7517#appendix-A>`_ is needed to
+  // validate signature of a JWT. This field specifies where to fetch JWKS.
  oneof jwks_source_specifier {
    option (validate.required) = true;

@ -90,7 +99,7 @@ message JwtProvider {
    // .. code-block:: yaml
    //
    //    local_jwks:
-    //      inline_string: "ACADADADADA"
+    //      inline_string: ACADADADADA
    //
    envoy.api.v2.core.DataSource local_jwks = 4;
  }
@ -103,18 +112,16 @@ message JwtProvider {
  //
  // If no explicit location is specified, the following default locations are tried in order:
  //
-  // 1. The Authorization header using the Bearer schema. See `here
-  //     <https://tools.ietf.org/html/rfc6750#section-2.1>`_. Example:
+  // 1. The Authorization header using the `Bearer schema
+  // <https://tools.ietf.org/html/rfc6750#section-2.1>`_. Example::
  //
-  //       Authorization: Bearer <token>.
+  //    Authorization: Bearer <token>.
  //
-  // 2. `access_token` query parameter. See `this
-  // <https://tools.ietf.org/html/rfc6750#section-2.3>`_
+  // 2. `access_token <https://tools.ietf.org/html/rfc6750#section-2.3>`_ query parameter.
  //
-
  // Multiple JWTs can be verified for a request. Each JWT has to be extracted from the locations
-  // its issuer specified or from the default locations.
-
+  // its provider specified or from the default locations.
+  //
  // Specify the HTTP headers to extract JWT token. For examples, following config:
  //
  // .. code-block:: yaml
@ -149,10 +156,6 @@ message JwtProvider {
  //    base64_encoded(jwt_payload_in_JSON)
  //
  // If it is not specified, the payload will not be forwarded.
-  // Multiple JWTs in a request from different issuers will be supported. Multiple JWTs from the
-  // same issuer will not be supported. Each issuer can config this `forward_payload_header`. If
-  // multiple JWTs from different issuers want to forward their payloads, their
-  // `forward_payload_header` should be different.
  string forward_payload_header = 8;
 }

@ -201,37 +204,37 @@ message ProviderWithAudiences {
 //  # Example 1: not required with an empty message
 //
 //  # Example 2: require A
-//  provider_name: "provider-A"
+//  provider_name: provider-A
 //
 //  # Example 3: require A or B
 //  requires_any:
 //    requirements:
-//      - provider_name: "provider-A"
-//      - provider_name: "provider-B"
+//      - provider_name: provider-A
+//      - provider_name: provider-B
 //
 //  # Example 4: require A and B
 //  requires_all:
 //    requirements:
-//      - provider_name: "provider-A"
-//      - provider_name: "provider-B"
+//      - provider_name: provider-A
+//      - provider_name: provider-B
 //
 //  # Example 5: require A and (B or C)
 //  requires_all:
 //    requirements:
-//      - provider_name: "provider-A"
+//      - provider_name: provider-A
 //      - requires_any:
 //        requirements:
-//          - provider_name: "provider-B"
-//          - provider_name: "provider-C"
+//          - provider_name: provider-B
+//          - provider_name: provider-C
 //
 //  # Example 6: require A or (B and C)
 //  requires_any:
 //    requirements:
-//      - provider_name: "provider-A"
+//      - provider_name: provider-A
 //      - requires_all:
 //        requirements:
-//          - provider_name: "provider-B"
-//          - provider_name: "provider-C"
+//          - provider_name: provider-B
+//          - provider_name: provider-C
 //
 message JwtRequirement {
  oneof requires_type {
@ -277,7 +280,7 @@ message JwtRequirementAndList {
 // .. code-block:: yaml
 //
 //    - match:
-//         prefix: "/healthz"
+//        prefix: /healthz
 //
 // In above example, "requires" field is empty for /healthz prefix match,
 // it means that requests matching the path prefix don't require JWT authentication.
@ -287,8 +290,8 @@ message JwtRequirementAndList {
 // .. code-block:: yaml
 //
 //    - match:
-//         prefix: "/"
-//      requires: { provider_name: "provider-A" }
+//        prefix: /
+//      requires: { provider_name: provider-A }
 //
 // In above example, all requests matched the path prefix require jwt authentication
 // from "provider-A".
@ -301,7 +304,7 @@ message RequirementRule {
  // .. code-block:: yaml
  //
  //    match:
-  //       prefix: "/"
+  //      prefix: /
  //
  envoy.api.v2.route.RouteMatch match = 1 [(validate.rules).message.required = true];

@ -333,22 +336,22 @@ message RequirementRule {
 //   rules:
 //      # Not jwt verification is required for /health path
 //      - match:
-//          prefix: "/health"
+//          prefix: /health
 //
 //      # Jwt verification for provider1 is required for path prefixed with "prefix"
 //      - match:
-//          prefix: "/prefix"
+//          prefix: /prefix
 //        requires:
-//          provider_name: "provider1"
+//          provider_name: provider1
 //
 //      # Jwt verification for either provider1 or provider2 is required for all other requests.
 //      - match:
-//          prefix: "/"
+//          prefix: /
 //        requires:
 //          requires_any:
 //            requirements:
-//              - provider_name: "provider1"
-//              - provider_name: "provider2"
+//              - provider_name: provider1
+//              - provider_name: provider2
 //
 message JwtAuthentication {
  // Map of provider names to JwtProviders.
@ -380,22 +383,26 @@ message JwtAuthentication {
  // .. code-block:: yaml
  //
  // rules:
-  //   - match: { prefix: "/healthz" }
-  //   - match: { prefix: "/baz" }
+  //   - match:
+  //       prefix: /healthz
+  //   - match:
+  //       prefix: /baz
  //     requires:
-  //       provider_name: "provider1"
-  //   - match: { prefix: "/foo" }
+  //       provider_name: provider1
+  //   - match:
+  //       prefix: /foo
  //     requires:
  //       requires_any:
  //         requirements:
-  //           - provider_name: "provider1"
-  //           - provider_name: "provider2"
-  //   - match: { prefix: "/bar" }
+  //           - provider_name: provider1
+  //           - provider_name: provider2
+  //   - match:
+  //       prefix: /bar
  //     requires:
  //       requires_all:
  //         requirements:
-  //           - provider_name: "provider1"
-  //           - provider_name: "provider2"
+  //           - provider_name: provider1
+  //           - provider_name: provider2
  //
  repeated RequirementRule rules = 2;
 }