Add authn policy design with JWT only #529

lizan · 2022-10-09T08:33:45Z

Fixes #336

Signed-off-by: Lizan Zhou <lizan@tetrate.io>

docs/design/authentication_policy.md

arkodg · 2022-10-10T19:15:43Z

docs/design/authentication_policy.md

+  name: productpage
+spec:
+  type: jwt
+  jwt:


if multiple issuers exist, does the user create multiple authn policies or will this policy allow the user to specify a list of issuers and associated jwksUri ?

#733 provides details. Multiple jwtProviders can be specified in an Authentication. The JWT auth passes if any one of the providers responds with a success. If an HTTPRoute references multiple Authentications, then at least one jwtProviders for each Authentication must pass for JWT auth to succeed.

docs/design/authentication_policy.md

danehans · 2022-10-11T22:44:42Z

@lizan as we discussed during today's Envoy Gateway community meeting, this design should be reviewed with the Gateway API GAMMA team. It would be beneficial for the extension to be supported by both projects.

sunjayBhatia

Great to see some Gateway API extension CRDs being worked on, we're doing the same over at Contour, still in early staged trying to get settled how we will approach the extension mechanisms generally

Left a few comments and questions

If you like we can talk more broadly about how to approach the extension mechanisms, I've started some notes for Contour specifically here: projectcontour/contour#4749 but there is some background info that is more widely applicable as well

Also got some example spikes on how one might implement local rate limiting with Filters vs. Policies here:

sunjayBhatia · 2022-10-14T00:28:34Z

docs/design/authentication_policy.md

+
+In the first phase, Envoy Gateway will implement JWT Bearer Token authentication.
+
+In general those policy translates into Envoy HTTP filters at HTTP connection manager level, and route specific settings will be applied for each route. These APIs are expressed in a Policy CRD and attached to Gateway API resources with [Policy Attachement](https://gateway-api.sigs.k8s.io/references/policy-attachment/).


re: route specific settings will be applied for each route

The Gateway API Policy targetRef field does not yet have a way to specify a sub-section of a resource, so applying a Policy to an individual route rule is not "directly" possible, unless you require users to separate that route rule into its own HTTPRoute resource (in this case you might have a Policy target a Gateway and another target an attached HTTPRoute that specifies some overrides just for it)

Am I understanding the intent here properly? Might be good to flesh out some more examples on how this might work

see also: kubernetes-sigs/gateway-api#1489

thanks for writing down that in depth analysis !
and surfacing some limitations with the PolicyAttachment that exist today.
Hoping those get incorporated soon, @youngnick has already acknowledged this !

Until then, since we plan on adding new features such as authentication in our next v0.3.0 release, imho we should peruse the existing spec for now

From the Gateway API Policy Attachment spec:

Although Policy attachment can be used to target an entire Route or Backend, it cannot currently be used to target specific Route rules or backend references.

Based on this information, it appears that an authentication API fits better as an implementation-specific filter since HTTPRoute rules may require different authentication specs. In the future, EG can add GWAPI Policy Attachment support for authentication defaulting and overrides.

HTTPRoute Filters themselves also have some drawbacks as they may not directly translate to Envoy HTTP Filters, given the scope they are configurable at.

HTTPRoute Filters can be configured per-Route Rule or per-Backend and Envoy HTTP Filters mostly have the bulk of their configuration as part of the Filter in a per-virtualhost HTTPConnectionManager FilterChain. I say "mostly" here because many filters enable per-Route enablement/disablement, but most of the configuration (e.g. JWT provider specification: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/jwt_authn/v3/config.proto#envoy-v3-api-msg-extensions-filters-http-jwt-authn-v3-jwtauthentication) lives at the higher level Filter object.

We may be able to have per-route JWT providers we collect from HTTPRoute Filter objects and then configure on the Envoy JWT HTTP Filter, but I haven't actually tried it so not sure how complex that will get.

Contour implemented this recently in HTTPProxy here:

https://github.com/projectcontour/contour/blob/4badccc7267aeec2644f9122ed7ca1547934a5b5/design/jwt-verification-design.md

https://projectcontour.io/docs/v1.23.0/config/jwt-verification/

Curious to see your thoughts @lizan if you've gotten a chance to spike this out as a Policy vs. a Filter

HTTPRoute Filters can be configured per-Route Rule or per-Backend

#733 implements authN as an HTTPRoute filter.

We may be able to have per-route JWT providers we collect from HTTPRoute Filter objects and then configure on the Envoy JWT HTTP Filter, but I haven't actually tried it so not sure how complex that will get.

I am going to test this as an approach for implementing authN. @lizan please comment if you have any suggestions.

docs/design/authentication_policy.md

arkodg · 2022-11-01T16:46:55Z

@lizan any new insights wrt this PR ?
this PR / Issue will be setting the standard for other advanced features scheduled in this release and should be the reference pattern for those features such as ratelimiting, cors, etc

The one thing I'd add is to consider limiting the Policy CRDs to 1 or 2 i.e.

one generic policy CRD with features as top level fields

apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: Policy
 .....
 spec:
   authentication:
   .....
   ratelimiting:
   ....

one generic policy CRD with networking (shapes traffic) and security (authenticates & authorizes traffic) as top fields

apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: Policy
 .....
 spec:
   security:
     authentication:
     ....
   networking:
     ratelimiting:
     .....

2 Policy CRDs - one for networking and the other for security

apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: SecurityPolicy
 ....
 ....
 spec:
   authentication:

apiVersion: gateway.envoyproxy.io/v1alpha1
 kind: NetworkingPolicy
 ....
 spec:
   ratelimiting:
   ....

danehans · 2022-11-01T23:32:55Z

During today's EG community meeting, a consensus was achieved for using separate API types to express request authentication and other advanced Envoy features, e.g. #671, #670, etc.

arkodg · 2022-11-02T04:06:39Z

During today's EG community meeting, a consensus was achieved for using separate API types to express request authentication and other advanced Envoy features, e.g. #671, #670, etc.

@danehans raised #677 so all our votes are recorded and maintainers who weren't able to attend can also vote.

Co-authored-by: Arko Dasgupta <arkodg@users.noreply.github.com> Signed-off-by: Lizan Zhou <lizan@tetrate.io>

Signed-off-by: danehans <daneyonhansen@gmail.com>

Refactors request auth design doc

Signed-off-by: danehans <daneyonhansen@gmail.com>

Signed-off-by: Lizan Zhou <lizan@tetrate.io>

Co-authored-by: Arko Dasgupta <arkodg@users.noreply.github.com> Signed-off-by: Lizan Zhou <lizan@tetrate.io>

Signed-off-by: danehans <daneyonhansen@gmail.com>

Rebases Resolves Review Feedback

danehans · 2022-11-16T18:04:38Z

Based on #675 (comment), maintainers have agreed to use an HTTPRoute implementation-specific filter to implement request authentication. The design doc currently follows this approach.

Signed-off-by: danehans <daneyonhansen@gmail.com>

arkodg · 2022-11-17T00:17:58Z

docs/latest/design/request-authentication.md

+
+### Security API Group
+
+A new API group, `security.gateway.envoyproxy.io` is introduced to group security-related APIs. This will allow security


curious why a new group is needed ?
why not graduate individual extensions from v1alpha1 to v1beta1 similar to what Gateway API does https://github.com/kubernetes-sigs/gateway-api/tree/main/apis

A group is not needed per se. The reason for the group is documented. I don't have a strong opinion on the topic. We grouped the config APIs, so we've already established a pattern.

codecov-commenter · 2022-11-17T02:17:41Z

Codecov Report

Merging #529 (362eb96) into main (b8f234b) will increase coverage by 0.71%.
The diff coverage is 60.16%.

@@            Coverage Diff             @@
##             main     #529      +/-   ##
==========================================
+ Coverage   62.72%   63.43%   +0.71%     
==========================================
  Files          42       47       +5     
  Lines        4496     5927    +1431     
==========================================
+ Hits         2820     3760     +940     
- Misses       1532     1929     +397     
- Partials      144      238      +94

Impacted Files	Coverage Δ
internal/cmd/certgen.go	`12.82% <ø> (ø)`
internal/cmd/server.go	`7.62% <0.00%> (-0.27%)`	⬇️
internal/cmd/versions.go	`50.00% <0.00%> (+21.42%)`	⬆️
internal/cmd/xdstest.go	`3.65% <ø> (ø)`
internal/crypto/certgen.go	`77.21% <ø> (ø)`
internal/envoygateway/config/config.go	`0.00% <ø> (ø)`
internal/gatewayapi/sort.go	`97.56% <ø> (+20.81%)`	⬆️
internal/infrastructure/kubernetes/labels.go	`100.00% <ø> (ø)`
internal/ir/infra.go	`67.41% <ø> (ø)`
internal/ir/zz_generated.deepcopy.go	`19.09% <0.00%> (+19.09%)`	⬆️
... and 51 more

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

danehans · 2022-11-17T14:42:48Z

docs/latest/design/request-authentication.md

+- Should local JWKS be implemented before remote JWKS?
+- How should Envoy obtain the trusted CA for a remote JWKS?
+- Should HTTPS be the only supported scheme for remote JWKS?
+- Should OR'ing JWT providers be supported?


I'm working through the implementation to support this.

danehans · 2022-11-17T14:47:52Z

docs/latest/design/request-authentication.md

+- OIDC
+- External authentication
+
+## Outstanding Questions


I would appreciate any feedback to help resolve these outstanding questions.

arkodg · 2022-11-17T22:26:31Z

docs/latest/design/request-authentication.md

+
+## Outstanding Questions
+
+- If Envoy Gateway owns the Authentication API, is an xDS IR equivalent needed?


auth will be a field within the xds IR route or listener struct

Correct, and auth will be of type #733 as opposed to an internal-only API type. This is because we own this API as opposed to any of the core or extended Gateway APIs.

docs/latest/design/request-authentication.md

lizan · 2022-11-18T18:29:36Z

docs/latest/design/request-authentication.md

+    ...
+        default_filter_chain:
+          filters:
+          - name: envoy.filters.network.http_connection_manager_1


This won't work, HCM is a terminal filter, so any filter after that won't be effect and be rejected.

@lizan I have updated the JWT xDS configuration example, PTAL.

Signed-off-by: danehans <daneyonhansen@gmail.com>

lizan · 2022-11-28T18:09:48Z

docs/latest/design/request-authentication.md

+                    rules:
+                      - match:
+                          exact: /foo
+                        requires:
+                          provider_name: default-example1-example1
+                      - match:
+                          exact: /bar
+                        requires:
+                          provider_name: default-example2-example2


This works, though we might end up with per route config and requirement map when this grows.

kflynn

Overall I think this looks really good. As discussed in the 29 November Envoy Gateway meeting, I think it's important that this stay at alpha until we have real-world usage to back it up.

kflynn · 2022-11-29T22:15:11Z

docs/latest/design/request-authentication.md

+## Outstanding Questions
+
+- If Envoy Gateway owns the Authentication API, is an xDS IR equivalent needed?
+- Should local JWKS be implemented before remote JWKS?


Given the next two questions about remote JWKS, I'd definitely vote in favor of local first.

Not sure why my previous comment is not shown anymore #529 (comment)

Remote JWKS first is strongly preferred as for most of public JWT issuer, keys are rotated quite frequently. (e.g. Google OAuth2 public key https://www.googleapis.com/oauth2/v3/certs rotates daily IIRC).

Rest of questions answered there as well.

+1 on prioritizing remote jwks.

docs/latest/design/request-authentication.md

danehans · 2022-11-30T22:36:47Z

Definitely worth considering what status updates would make sense.

@kflynn I agree. I would like to add status as a follow-on after implementing the API and gaining an understanding of how it's used.

danehans · 2022-11-30T22:41:25Z

Overall I think this looks really good. As discussed in the 29 November Envoy Gateway meeting, I think it's important that this stay at alpha until we have real-world usage to back it up.

@kflynn agreed and why I created #714.

Signed-off-by: danehans <daneyonhansen@gmail.com>

danehans · 2022-11-30T23:42:47Z

commit 947359c removes the security API group and renames the API to AuthenticationFilter.

cc: @arkodg @youngnick

lizan requested a review from a team as a code owner October 9, 2022 08:33

Add authn policy design with JWT only

9a6ed41

Signed-off-by: Lizan Zhou <lizan@tetrate.io>

lizan force-pushed the authn_policy_doc branch from a591307 to 9a6ed41 Compare October 9, 2022 08:34

arkodg reviewed Oct 10, 2022

View reviewed changes

docs/design/authentication_policy.md Outdated Show resolved Hide resolved

arkodg reviewed Oct 10, 2022

View reviewed changes

docs/design/authentication_policy.md Outdated Show resolved Hide resolved

arkodg reviewed Oct 10, 2022

View reviewed changes

docs/design/authentication_policy.md Outdated Show resolved Hide resolved

arkodg reviewed Oct 10, 2022

View reviewed changes

docs/design/authentication_policy.md Outdated Show resolved Hide resolved

arkodg reviewed Oct 10, 2022

View reviewed changes

docs/design/authentication_policy.md Outdated Show resolved Hide resolved

arkodg reviewed Oct 10, 2022

View reviewed changes

docs/design/authentication_policy.md Outdated Show resolved Hide resolved

danehans added the documentation Improvements or additions to documentation label Oct 12, 2022

danehans modified the milestones: 0.2.0, 0.3.0-rc.1 Oct 12, 2022

sunjayBhatia reviewed Oct 14, 2022

View reviewed changes

danehans mentioned this pull request Nov 1, 2022

Add Global Rate Limiting Support #670

Closed

7 tasks

arkodg mentioned this pull request Nov 1, 2022

Design Authentication Policy as a GatewayAPI Extension #336

Closed

danehans mentioned this pull request Nov 1, 2022

Add Support for WAF #671

Open

7 tasks

danehans mentioned this pull request Nov 2, 2022

decision: Segmenting API Gateway features into PolicyAttachment CRDs #677

Closed

lizan and others added 2 commits November 2, 2022 10:45

Update docs/design/authentication_policy.md

b5c4755

Co-authored-by: Arko Dasgupta <arkodg@users.noreply.github.com> Signed-off-by: Lizan Zhou <lizan@tetrate.io>

Update docs/design/authentication_policy.md

3cb97e1

Co-authored-by: Arko Dasgupta <arkodg@users.noreply.github.com> Signed-off-by: Lizan Zhou <lizan@tetrate.io>

sunjayBhatia mentioned this pull request Nov 2, 2022

Gateway API extensions: Usage of Policy Attachment vs. Filters #675

Closed

arkodg added the priority/high Label used to express the "high" priority level label Nov 3, 2022

danehans mentioned this pull request Nov 7, 2022

Update roadmap for v0.3.0 #695

Merged

danehans and others added 2 commits November 8, 2022 12:19

Refactors request auth design doc

69bd6e4

Signed-off-by: danehans <daneyonhansen@gmail.com>

Merge pull request #2 from danehans/lizan_authn_policy_doc_refactor

36b850f

Refactors request auth design doc

danehans and others added 5 commits November 11, 2022 13:38

Refactors request auth design doc

69923b3

Signed-off-by: danehans <daneyonhansen@gmail.com>

Add authn policy design with JWT only

d821123

Signed-off-by: Lizan Zhou <lizan@tetrate.io>

Update docs/design/authentication_policy.md

33772f7

Co-authored-by: Arko Dasgupta <arkodg@users.noreply.github.com> Signed-off-by: Lizan Zhou <lizan@tetrate.io>

Update docs/design/authentication_policy.md

aa4c617

Co-authored-by: Arko Dasgupta <arkodg@users.noreply.github.com> Signed-off-by: Lizan Zhou <lizan@tetrate.io>

Resolves Review Feedback

12f33db

Signed-off-by: danehans <daneyonhansen@gmail.com>

danehans mentioned this pull request Nov 15, 2022

Support Authentication Overrides and Defaults #731

Closed

Merge pull request #3 from danehans/lizan_authn_policy_doc_update

90ed4e2

Rebases Resolves Review Feedback

danehans mentioned this pull request Nov 16, 2022

Adds Request Authentication API #733

Merged

danehans added 2 commits November 16, 2022 10:43

Removes duplicative docs

3b1e792

Signed-off-by: danehans <daneyonhansen@gmail.com>

Refers to PR 773 for API Details

362eb96

Signed-off-by: danehans <daneyonhansen@gmail.com>

arkodg reviewed Nov 17, 2022

View reviewed changes

danehans reviewed Nov 17, 2022

View reviewed changes

arkodg reviewed Nov 17, 2022

View reviewed changes

docs/latest/design/request-authentication.md Show resolved Hide resolved

arkodg reviewed Nov 17, 2022

View reviewed changes

docs/latest/design/request-authentication.md Outdated Show resolved Hide resolved

lizan commented Nov 18, 2022

View reviewed changes

Refactors JWT xDS Config

8c2fde2

Signed-off-by: danehans <daneyonhansen@gmail.com>

lizan commented Nov 28, 2022

View reviewed changes

kflynn previously approved these changes Nov 29, 2022

View reviewed changes

youngnick reviewed Nov 29, 2022

View reviewed changes

docs/latest/design/request-authentication.md Show resolved Hide resolved

Removes API Group and Renames API to AuthenticationFilter

947359c

Signed-off-by: danehans <daneyonhansen@gmail.com>

danehans dismissed kflynn’s stale review via 947359c November 30, 2022 23:41

arkodg approved these changes Dec 6, 2022

View reviewed changes

danehans merged commit 0456aa7 into envoyproxy:main Dec 7, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add authn policy design with JWT only #529

Add authn policy design with JWT only #529

lizan commented Oct 9, 2022 •

edited by danehans

Loading

arkodg Oct 10, 2022

danehans Nov 28, 2022

danehans commented Oct 11, 2022

sunjayBhatia left a comment

sunjayBhatia Oct 14, 2022

sunjayBhatia Nov 1, 2022

arkodg Nov 1, 2022

danehans Nov 2, 2022

sunjayBhatia Nov 2, 2022

danehans Nov 28, 2022

arkodg commented Nov 1, 2022

danehans commented Nov 1, 2022

arkodg commented Nov 2, 2022

danehans commented Nov 16, 2022

arkodg Nov 17, 2022

danehans Nov 17, 2022

codecov-commenter commented Nov 17, 2022

danehans Nov 17, 2022

danehans Nov 17, 2022

arkodg Nov 17, 2022

danehans Nov 28, 2022

lizan Nov 18, 2022

danehans Nov 28, 2022

lizan Nov 28, 2022

kflynn left a comment

kflynn Nov 29, 2022

lizan Nov 29, 2022

danehans Nov 30, 2022

danehans commented Nov 30, 2022

danehans commented Nov 30, 2022

danehans commented Nov 30, 2022


		In the first phase, Envoy Gateway will implement JWT Bearer Token authentication.

		In general those policy translates into Envoy HTTP filters at HTTP connection manager level, and route specific settings will be applied for each route. These APIs are expressed in a Policy CRD and attached to Gateway API resources with [Policy Attachement](https://gateway-api.sigs.k8s.io/references/policy-attachment/).


		### Security API Group

		A new API group, `security.gateway.envoyproxy.io` is introduced to group security-related APIs. This will allow security


		## Outstanding Questions

		- If Envoy Gateway owns the Authentication API, is an xDS IR equivalent needed?

Add authn policy design with JWT only #529

Add authn policy design with JWT only #529

Conversation

lizan commented Oct 9, 2022 • edited by danehans Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

danehans commented Oct 11, 2022

sunjayBhatia left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

arkodg commented Nov 1, 2022

danehans commented Nov 1, 2022

arkodg commented Nov 2, 2022

danehans commented Nov 16, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov-commenter commented Nov 17, 2022

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kflynn left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

danehans commented Nov 30, 2022

danehans commented Nov 30, 2022

danehans commented Nov 30, 2022

lizan commented Oct 9, 2022 •

edited by danehans

Loading