From abab76a914e9065cb755dde078c139700655a0e3 Mon Sep 17 00:00:00 2001 From: "data-plane-api(CircleCI)" Date: Wed, 3 Oct 2018 21:49:28 +0000 Subject: [PATCH] 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 Mirrored from https://github.com/envoyproxy/envoy @ d101ae7decfdae148f53ea9d2220444c726dfbfd --- docs/BUILD | 1 + .../http/jwt_authn/v2alpha/config.proto | 111 ++++++++++-------- 2 files changed, 60 insertions(+), 52 deletions(-) diff --git a/docs/BUILD b/docs/BUILD index d7ff0201..c1ad6973 100644 --- 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", diff --git a/envoy/config/filter/http/jwt_authn/v2alpha/config.proto b/envoy/config/filter/http/jwt_authn/v2alpha/config.proto index 85e134bc..153264e4 100644 --- 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 `_. Please see `OAuth2.0 -// `_ and `OIDC1.0 `_ for -// the authentication flow. +// Please see following for JWT authentication flow: +// +// * `JSON Web Token (JWT) `_ +// * `The OAuth 2.0 Authorization Framework `_ +// * `OpenID 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 - // `_. Usually a URL or an email address. + // Specify the `principal `_ 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 `_. that are + // The list of JWT `audiences `_ 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 `_ is needed. to validate - // signature of the JWT. This field specifies where to fetch JWKS. + // `JSON Web Key Set (JWKS) `_ 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 - // `_. Example: + // 1. The Authorization header using the `Bearer schema + // `_. Example:: // - // Authorization: Bearer . + // Authorization: Bearer . // - // 2. `access_token` query parameter. See `this - // `_ + // 2. `access_token `_ 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; }