From b9cf0e88ed9b5a3fdb74e7800c94148f828c4f6b Mon Sep 17 00:00:00 2001 From: "data-plane-api(CircleCI)" Date: Fri, 8 Jun 2018 14:57:25 +0000 Subject: [PATCH] Add documentation for external authorization filter. (#3379) Signed-off-by: Saurabh Mohan Mirrored from https://github.com/envoyproxy/envoy @ a2abe7a4fae83cc2ad45700e59f4be52cbd3baac --- docs/BUILD | 2 ++ envoy/api/v2/core/http_uri.proto | 3 ++- .../http/ext_authz/v2alpha/ext_authz.proto | 18 ++++++++++++++---- .../network/ext_authz/v2/ext_authz.proto | 13 ++++++++----- .../auth/v2alpha/attribute_context.proto | 11 +++++++---- envoy/service/auth/v2alpha/external_auth.proto | 7 +++++-- 6 files changed, 38 insertions(+), 16 deletions(-) diff --git a/docs/BUILD b/docs/BUILD index 7d31e61a..d1910c4e 100644 --- a/docs/BUILD +++ b/docs/BUILD @@ -58,6 +58,8 @@ proto_library( "//envoy/data/accesslog/v2:accesslog", "//envoy/data/tap/v2alpha:capture", "//envoy/service/accesslog/v2:als", + "//envoy/service/auth/v2alpha:attribute_context", + "//envoy/service/auth/v2alpha:external_auth", "//envoy/service/discovery/v2:ads", "//envoy/service/load_stats/v2:lrs", "//envoy/service/metrics/v2:metrics_service", diff --git a/envoy/api/v2/core/http_uri.proto b/envoy/api/v2/core/http_uri.proto index 92097778..0c0ab766 100644 --- a/envoy/api/v2/core/http_uri.proto +++ b/envoy/api/v2/core/http_uri.proto @@ -7,8 +7,9 @@ import "gogoproto/gogo.proto"; import "validate/validate.proto"; +// [#protodoc-title: HTTP Service URI ] + // Envoy external URI descriptor -// [#not-implemented-hide:] message HttpUri { // The HTTP server URI. It should be a full FQDN with protocol, host and path. // diff --git a/envoy/config/filter/http/ext_authz/v2alpha/ext_authz.proto b/envoy/config/filter/http/ext_authz/v2alpha/ext_authz.proto index a9392b85..9d602298 100644 --- a/envoy/config/filter/http/ext_authz/v2alpha/ext_authz.proto +++ b/envoy/config/filter/http/ext_authz/v2alpha/ext_authz.proto @@ -6,7 +6,12 @@ option go_package = "v2alpha"; import "envoy/api/v2/core/grpc_service.proto"; import "envoy/api/v2/core/http_uri.proto"; -// The external authorization HTTP service configuration. +// [#protodoc-title: HTTP External Authorization ] +// The external authorization HTTP service configuration +// :ref:`configuration overview `. + +// [#not-implemented-hide:] +// [#comment: The HttpService is under development and will be supported soon.] message HttpService { // Sets the HTTP server URI which the authorization requests must be sent to. envoy.api.v2.core.HttpUri server_uri = 1; @@ -15,20 +20,25 @@ message HttpService { string path_prefix = 2; } +// External Authorization filter calls out to an external service over the +// gRPC Authorization API defined by +// :ref:`CheckRequest `. +// A failed check will cause this filter to close the HTTP request with 403(Forbidden). message ExtAuthz { oneof services { // The external authorization gRPC service configuration. + // The default timeout is set to 200ms by this filter. envoy.api.v2.core.GrpcService grpc_service = 1; // The external authorization HTTP service configuration. + // [#not-implemented-hide:] HttpService http_service = 3; } // The filter's behaviour in case the external authorization service does - // not respond back. If set to true then in case of failure to get a - // response back from the authorization service or getting a response that - // is NOT denied then traffic will be permitted. + // not respond back. When it is set to true, Envoy will also allow traffic in case of + // communication failure between authorization service and the proxy. // Defaults to false. bool failure_mode_allow = 2; } diff --git a/envoy/config/filter/network/ext_authz/v2/ext_authz.proto b/envoy/config/filter/network/ext_authz/v2/ext_authz.proto index f6716386..020fb8e5 100644 --- a/envoy/config/filter/network/ext_authz/v2/ext_authz.proto +++ b/envoy/config/filter/network/ext_authz/v2/ext_authz.proto @@ -7,22 +7,25 @@ import "envoy/api/v2/core/grpc_service.proto"; import "validate/validate.proto"; -// [#not-implemented-hide:] +// [#protodoc-title: Network External Authorization ] +// The network layer external authorization service configuration +// :ref:`configuration overview `. + // External Authorization filter calls out to an external service over the // gRPC Authorization API defined by -// :ref:`external_auth `. +// :ref:`CheckRequest `. // A failed check will cause this filter to close the TCP connection. message ExtAuthz { // The prefix to use when emitting statistics. string stat_prefix = 1 [(validate.rules).string.min_bytes = 1]; // The external authorization gRPC service configuration. + // The default timeout is set to 200ms by this filter. envoy.api.v2.core.GrpcService grpc_service = 2; // The filter's behaviour in case the external authorization service does - // not respond back. If set to true then in case of failure to get a - // response back from the authorization service or getting a response that - // is NOT denied then traffic will be permitted. + // not respond back. When it is set to true, Envoy will also allow traffic in case of + // communication failure between authorization service and the proxy. // Defaults to false. bool failure_mode_allow = 3; } diff --git a/envoy/service/auth/v2alpha/attribute_context.proto b/envoy/service/auth/v2alpha/attribute_context.proto index a8c4bd0b..3ef8fe39 100644 --- a/envoy/service/auth/v2alpha/attribute_context.proto +++ b/envoy/service/auth/v2alpha/attribute_context.proto @@ -1,13 +1,16 @@ syntax = "proto3"; -// [#proto-status: draft] - package envoy.service.auth.v2alpha; import "envoy/api/v2/core/address.proto"; import "google/protobuf/timestamp.proto"; +// [#protodoc-title: Attribute Context ] + +// See :ref:`network filter configuration overview ` +// and :ref:`HTTP filter configuration overview `. + // An attribute is a piece of metadata that describes an activity on a network. // For example, the size of an HTTP request, or the status code of an HTTP response. // @@ -115,8 +118,8 @@ message AttributeContext { // This is analogous to http_request.headers, however these contents will not be sent to the // upstream server. Context_extensions provide an extension mechanism for sending additional - // information to the auth server without modifying the proto definition. It maps to the internal - // opaque context in the filter chain. + // information to the auth server without modifying the proto definition. It maps to the + // internal opaque context in the filter chain. map context_extensions = 10; } diff --git a/envoy/service/auth/v2alpha/external_auth.proto b/envoy/service/auth/v2alpha/external_auth.proto index 29acfa29..601c4dea 100644 --- a/envoy/service/auth/v2alpha/external_auth.proto +++ b/envoy/service/auth/v2alpha/external_auth.proto @@ -1,7 +1,5 @@ syntax = "proto3"; -// [#proto-status: draft] - package envoy.service.auth.v2alpha; option go_package = "v2alpha"; option java_generic_services = true; @@ -11,6 +9,11 @@ import "envoy/service/auth/v2alpha/attribute_context.proto"; import "google/rpc/status.proto"; import "validate/validate.proto"; +// [#protodoc-title: Authorization Service ] + +// The authorization service request messages used by external authorization :ref:`network filter +// ` and :ref:`HTTP filter `. + // A generic interface for performing authorization check on incoming // requests to a networked service. service Authorization {