Skip to content

doc: add doc for Jwt_authn filter #4527

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
htuch merged 16 commits into from
Oct 3, 2018
Merged

doc: add doc for Jwt_authn filter #4527

Show file tree
Hide file tree
Changes from 14 commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
0ceefa3
polish jwt_authn config.proto
qiwzhang Sep 20, 2018
47e9949
Fix format for jwt_authn config.proto
qiwzhang Sep 21, 2018
e945fea
Add jwt_authn_filter.rst
qiwzhang Sep 21, 2018
18a967d
update 2nd draft
qiwzhang Sep 24, 2018
0e0e590
update 3rd draft
qiwzhang Sep 24, 2018
59d5bfb
update 4th draft
qiwzhang Sep 25, 2018
dcbba99
5ft draft
qiwzhang Sep 25, 2018
a071636
format
qiwzhang Sep 25, 2018
bc7e015
update format
qiwzhang Sep 25, 2018
da83130
update format again
qiwzhang Sep 25, 2018
2ae366c
Update per review
qiwzhang Oct 2, 2018
197f297
remove double quote
qiwzhang Oct 2, 2018
1549260
use attention rst
qiwzhang Oct 2, 2018
aeec5f3
fix annotation usage error
qiwzhang Oct 2, 2018
8994580
update link titles
qiwzhang Oct 3, 2018
3a98356
update another link title
qiwzhang Oct 3, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions api/docs/BUILD
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
111 changes: 59 additions & 52 deletions api/envoy/config/filter/http/jwt_authn/v2alpha/config.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
//
// * `JWT format <https://tools.ietf.org/html/rfc7519>`_

@lizan lizan Oct 3, 2018

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@qiwzhang qiwzhang Oct 3, 2018

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done

// * `OAuth2.0 <https://tools.ietf.org/html/rfc6749>`_
// * `OIDC1.0 <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:
//
Expand All @@ -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.
//
Expand All @@ -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;

Expand Down Expand Up @@ -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;
}
Expand All @@ -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
Expand Down Expand Up @@ -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;
}

Expand Down Expand Up @@ -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 {
Expand Down Expand Up @@ -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.
Expand All @@ -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".
Expand All @@ -301,7 +304,7 @@ message RequirementRule {
// .. code-block:: yaml
//
// match:
// prefix: "/"
// prefix: /
//
envoy.api.v2.route.RouteMatch match = 1 [(validate.rules).message.required = true];

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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;
}
1 change: 1 addition & 0 deletions docs/build.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,7 @@ PROTO_RST="
/envoy/config/filter/http/health_check/v2/health_check/envoy/config/filter/http/health_check/v2/health_check.proto.rst
/envoy/config/filter/http/header_to_metadata/v2/header_to_metadata/envoy/config/filter/http/header_to_metadata/v2/header_to_metadata.proto.rst
/envoy/config/filter/http/ip_tagging/v2/ip_tagging/envoy/config/filter/http/ip_tagging/v2/ip_tagging.proto.rst
/envoy/config/filter/http/jwt_authn/v2alpha/jwt_authn/envoy/config/filter/http/jwt_authn/v2alpha/config.proto.rst
/envoy/config/filter/http/lua/v2/lua/envoy/config/filter/http/lua/v2/lua.proto.rst
/envoy/config/filter/http/rate_limit/v2/rate_limit/envoy/config/filter/http/rate_limit/v2/rate_limit.proto.rst
/envoy/config/filter/http/rbac/v2/rbac/envoy/config/filter/http/rbac/v2/rbac.proto.rst
Expand Down
1 change: 1 addition & 0 deletions docs/root/configuration/http_filters/http_filters.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ HTTP filters
health_check_filter
header_to_metadata_filter
ip_tagging_filter
jwt_authn_filter
lua_filter
rate_limit_filter
rbac_filter
Expand Down
Loading