From 2e1654991c1063f51deee7f0b71c204d4cb31618 Mon Sep 17 00:00:00 2001 From: R-Lawton Date: Fri, 29 Nov 2024 17:49:39 +0000 Subject: [PATCH] Reverting name changes for personas Signed-off-by: R-Lawton --- README.md | 10 ++-- doc/overviews/auth.md | 93 +++++++++++++++++++--------------- doc/overviews/rate-limiting.md | 6 +-- 3 files changed, 59 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index c2aeb0c3c..87402f64b 100644 --- a/README.md +++ b/README.md @@ -52,8 +52,8 @@ The kuadrant control plane owns the following [Custom Resource Definitions, CRDs | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | AuthPolicy CRD [\[doc\]](doc/overviews/auth.md) [[reference]](doc/reference/authpolicy.md) | Enable AuthN and AuthZ based access control on workloads | [AuthPolicy CR](https://github.com/Kuadrant/kuadrant-operator/blob/main/examples/toystore/authpolicy.yaml) | | RateLimitPolicy CRD [\[doc\]](doc/overviews/rate-limiting.md) [[reference]](doc/reference/ratelimitpolicy.md) | Enable access control on workloads based on HTTP rate limiting | [RateLimitPolicy CR](https://raw.githubusercontent.com/Kuadrant/kuadrant-operator/main/examples/toystore/ratelimitpolicy_httproute.yaml) | -| DNSPolicy CRD [\[doc\]](doc/overviews/dns.md) [[reference]](doc/reference/dnspolicy.md) | Enable DNS management | [DNSPolicy CR](config/samples/kuadrant_v1_dnspolicy.yaml) | -| TLSPolicy CRD [\[doc\]](doc/overviews/tls.md) [[reference]](doc/reference/tlspolicy.md) | Enable TLS management | [TLSPolicy CR](config/samples/kuadrant_v1_tlspolicy.yaml) | +| DNSPolicy CRD [\[doc\]](doc/overviews/dns.md) [[reference]](doc/reference/dnspolicy.md) | Enable DNS management | [DNSPolicy CR](config/samples/kuadrant_v1_dnspolicy.yaml) | +| TLSPolicy CRD [\[doc\]](doc/overviews/tls.md) [[reference]](doc/reference/tlspolicy.md) | Enable TLS management | [TLSPolicy CR](config/samples/kuadrant_v1_tlspolicy.yaml) | Additionally, Kuadrant provides the following CRDs @@ -151,9 +151,9 @@ EOF The user guides section of the docs gathers several use-cases as well as the instructions to implement them using kuadrant. -- [Simple Rate Limiting for Application Developers](doc/user-guides/ratelimiting/simple-rl-for-app.md) -- [Authenticated Rate Limiting for Application Developers](doc/user-guides/ratelimiting/authenticated-rl-for-app.md) -- [Gateway Rate Limiting for Cluster Operators](doc/user-guides/ratelimiting/multi-rlp-multi-listener.md) +- [Simple Rate Limiting for Application Developers](doc/user-guides/ratelimiting/simple-rl-for-app-developers.md) +- [Authenticated Rate Limiting for Application Developers](doc/user-guides/ratelimiting/authenticated-rl-for-app-developers.md.md) +- [Gateway Rate Limiting for Cluster Operators](doc/user-guides/ratelimiting/gateway-rl-for-cluster-operators.md) - [Authenticated Rate Limiting with JWTs and Kubernetes RBAC](doc/user-guides/ratelimiting/authenticated-rl-with-jwt-and-k8s-authnz.md) ## [Kuadrant Rate Limiting](doc/overviews/rate-limiting.md) diff --git a/doc/overviews/auth.md b/doc/overviews/auth.md index 7b270ba7e..6a4713392 100644 --- a/doc/overviews/auth.md +++ b/doc/overviews/auth.md @@ -12,6 +12,7 @@ A Kuadrant AuthPolicy custom resource: ### Envoy's External Authorization Protocol Kuadrant's Auth implementation relies on the Envoy's [External Authorization](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/ext_authz_filter) protocol. The workflow per request goes: + 1. On incoming request, the gateway checks the matching rules for enforcing the auth rules, as stated in the AuthPolicy custom resources and targeted Gateway API networking objects 2. If the request matches, the gateway sends one [CheckRequest](https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/auth/v3/external_auth.proto#envoy-v3-api-msg-service-auth-v3-checkrequest) to the external auth service ("Authorino"). 3. The external auth service responds with a [CheckResponse](https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/auth/v3/external_auth.proto#service-auth-v3-checkresponse) back to the gateway with either an `OK` or `DENIED` response code. @@ -24,18 +25,18 @@ An AuthPolicy and its targeted Gateway API networking resource contain all the s The `AuthPolicy` spec includes the following parts: -* A reference to an existing Gateway API resource (`spec.targetRef`) -* Authentication/authorization scheme (`spec.rules`) -* Top-level additional conditions (`spec.when`) -* List of named patterns (`spec.patterns`) +- A reference to an existing Gateway API resource (`spec.targetRef`) +- Authentication/authorization scheme (`spec.rules`) +- Top-level additional conditions (`spec.when`) +- List of named patterns (`spec.patterns`) The auth scheme specify rules for: -* Authentication (`spec.rules.authentication`) -* External auth metadata fetching (`spec.rules.metadata`) -* Authorization (`spec.rules.authorization`) -* Custom response items (`spec.rules.response`) -* Callbacks (`spec.rules.callbacks`) +- Authentication (`spec.rules.authentication`) +- External auth metadata fetching (`spec.rules.metadata`) +- Authorization (`spec.rules.authorization`) +- Custom response items (`spec.rules.response`) +- Callbacks (`spec.rules.callbacks`) Each auth rule can declare specific `when` conditions for the rule to apply. @@ -67,7 +68,7 @@ spec: # Sets of common patterns of selector-operator-value triples, to be referred by name in `when` conditions # and pattern-matching rules. Often employed to avoid repetition in the policy. # Equivalent to if otherwise declared within `defaults`. - patterns: {…} + patterns: { … } # The auth rules to apply to the network traffic routed through the targeted resource. # Equivalent to if otherwise declared within `defaults`. @@ -79,7 +80,7 @@ spec: "my-authn-rule": # The authentication method of this rule. # One-of: apiKey, jwt, oauth2Introspection, kubernetesTokenReview, x509, plain, anonymous. - apiKey: {…} + apiKey: { … } # Where credentials are required to be passed in the request for authentication based on this rule. # One-of: authorizationHeader, customHeader, queryString, cookie. @@ -91,14 +92,14 @@ spec: when: […] # Configs for caching the resolved object returned out of evaluating this auth rule. - cache: {…} + cache: { … } # Rules for fetching auth metadata from external sources. metadata: "my-external-source": # The method for fetching metadata from the external source. # One-of: http: userInfo, uma. - http: {…} + http: { … } # Authorization rules to enforce. # All policies must allow access for the auth request be successful. @@ -106,15 +107,15 @@ spec: "my-authz-rule": # The authorization method of this rule. # One-of: patternMatching, opa, kubernetesSubjectAccessReview, spicedb. - opa: {…} + opa: { … } # Customizations to the authorization response. response: # Custom denial status and other HTTP attributes for unauthenticated requests. - unauthenticated: {…} + unauthenticated: { … } # Custom denial status and other HTTP attributes for unauhtorized requests. - unauthorized: {…} + unauthorized: { … } # Custom response items when access is granted. success: @@ -122,19 +123,19 @@ spec: headers: "my-custom-header": # One-of: plain, json, wristband. - plain: {…} + plain: { … } # Custom response items wrapped as envoy dynamic metadata. dynamicMetadata: # One-of: plain, json, wristband. "my-custom-dyn-metadata": - json: {…} + json: { … } # Rules for post-authorization callback requests to external services. # Triggered regardless of the result of the authorization request. callbacks: "my-webhook": - http: {…} + http: { … } # Explicit defaults. Used in policies that target a Gateway object to express default rules to be enforced on # routes that lack a more specific policy attached to. @@ -142,13 +143,13 @@ spec: # the spec. defaults: rules: - authentication: {…} - metadata: {…} - authorization: {…} - response: {…} - callbacks: {…} + authentication: { … } + metadata: { … } + authorization: { … } + response: { … } + callbacks: { … } when: […] - patterns: {…} + patterns: { … } # Overrides. Used in policies that target a Gateway object to be enforced on all routes linked to the gateway, # thus also overriding any more specific policy occasionally attached to any of those routes. @@ -156,13 +157,13 @@ spec: # the spec. overrides: rules: - authentication: {…} - metadata: {…} - authorization: {…} - response: {…} - callbacks: {…} + authentication: { … } + metadata: { … } + authorization: { … } + response: { … } + callbacks: { … } when: […] - patterns: {…} + patterns: { … } ``` Check out the [API reference](../reference/authpolicy.md) for a full specification of the AuthPolicy CRD. @@ -187,7 +188,7 @@ spec: group: gateway.networking.k8s.io kind: HTTPRoute name: - rules: {…} + rules: { … } ``` ``` @@ -216,11 +217,13 @@ If an AuthPolicy targets a route defined for `*.com` and another AuthPolicy targ E.g., a request coming for `api.com` will be protected according to the rules from the AuthPolicy that targets the route for `api.com`; while a request for `other.com` will be protected with the rules from the AuthPolicy targeting the route for `*.com`. Example with 3 AuthPolicies and 3 HTTPRoutes: + - AuthPolicy A → HTTPRoute A (`a.toystore.com`) - AuthPolicy B → HTTPRoute B (`b.toystore.com`) - AuthPolicy W → HTTPRoute W (`*.toystore.com`) Expected behavior: + - Request to `a.toystore.com` → AuthPolicy A will be enforced - Request to `b.toystore.com` → AuthPolicy B will be enforced - Request to `other.toystore.com` → AuthPolicy W will be enforced @@ -248,7 +251,7 @@ spec: kind: Gateway name: defaults: # alternatively: `overrides` - rules: {…} + rules: { … } ``` ``` @@ -277,12 +280,14 @@ Two possible semantics are to be considered here – gateway policy _defaults_ v Gateway AuthPolicies that declare _defaults_ (or alternatively neither defaults nor overrides) protect all traffic routed through the gateway except where a more specific HTTPRoute AuthPolicy exists, in which case the HTTPRoute AuthPolicy prevails. Example with 4 AuthPolicies, 3 HTTPRoutes and 1 Gateway _default_ (plus 2 HTTPRoute and 2 Gateways without AuthPolicies attached): + - AuthPolicy A → HTTPRoute A (`a.toystore.com`) → Gateway G (`*.com`) - AuthPolicy B → HTTPRoute B (`b.toystore.com`) → Gateway G (`*.com`) - AuthPolicy W → HTTPRoute W (`*.toystore.com`) → Gateway G (`*.com`) - AuthPolicy G (defaults) → Gateway G (`*.com`) Expected behavior: + - Request to `a.toystore.com` → AuthPolicy A will be enforced - Request to `b.toystore.com` → AuthPolicy B will be enforced - Request to `other.toystore.com` → AuthPolicy W will be enforced @@ -292,12 +297,14 @@ Expected behavior: Gateway AuthPolicies that declare _overrides_ protect all traffic routed through the gateway, regardless of existence of any more specific HTTPRoute AuthPolicy. Example with 4 AuthPolicies, 3 HTTPRoutes and 1 Gateway _override_ (plus 2 HTTPRoute and 2 Gateways without AuthPolicies attached): + - AuthPolicy A → HTTPRoute A (`a.toystore.com`) → Gateway G (`*.com`) - AuthPolicy B → HTTPRoute B (`b.toystore.com`) → Gateway G (`*.com`) - AuthPolicy W → HTTPRoute W (`*.toystore.com`) → Gateway G (`*.com`) - AuthPolicy G (overrides) → Gateway G (`*.com`) Expected behavior: + - Request to `a.toystore.com` → AuthPolicy G will be enforced - Request to `b.toystore.com` → AuthPolicy G will be enforced - Request to `other.toystore.com` → AuthPolicy G will be enforced @@ -319,16 +326,17 @@ Authorino [JSON path string modifiers](https://docs.kuadrant.io/latest/authorino ### Examples Check out the following user guides for examples of protecting services with Kuadrant: -* [Enforcing authentication & authorization with Kuadrant AuthPolicy, for app developers and platform engineers](../user-guides/auth/auth-for-app-devs-and-platform-engineers.md) -* [Authenticated Rate Limiting for Application Developers](../user-guides/ratelimiting/authenticated-rl-for-app.md) -* [Authenticated Rate Limiting with JWTs and Kubernetes RBAC](../user-guides/ratelimiting/authenticated-rl-with-jwt-and-k8s-authnz.md) + +- [Enforcing authentication & authorization with Kuadrant AuthPolicy, for app developers and platform engineers](../user-guides/auth/auth-for-app-devs-and-platform-engineers.md) +- [Authenticated Rate Limiting for Application Developers](../user-guides/ratelimiting/authenticated-rl-for-app-developers.md.md) +- [Authenticated Rate Limiting with JWTs and Kubernetes RBAC](../user-guides/ratelimiting/authenticated-rl-with-jwt-and-k8s-authnz.md) ### Known limitations -* One HTTPRoute can only be targeted by one AuthPolicy. -* One Gateway can only be targeted by one AuthPolicy. -* AuthPolicies can only target HTTPRoutes/Gateways defined within the same namespace of the AuthPolicy. -* 2+ AuthPolicies cannot target network resources that define/inherit the same exact hostname. +- One HTTPRoute can only be targeted by one AuthPolicy. +- One Gateway can only be targeted by one AuthPolicy. +- AuthPolicies can only target HTTPRoutes/Gateways defined within the same namespace of the AuthPolicy. +- 2+ AuthPolicies cannot target network resources that define/inherit the same exact hostname. #### Limitation: Multiple network resources with identical hostnames @@ -421,9 +429,10 @@ Authorino looks up for the auth scheme (`AuthConfig` custom resource) to enforce
Exception to the rule - Due to limitations imposed by the Istio `AuthorizationPolicy`, there are a few patterns of HTTPRouteRules that cannot be translated to filters for the external authorization request. Therefore, the following patterns used in HTTPRouteMatches of top-level route selectors of an AuthPolicy will not be included in the Istio AuthorizationPolicy rules that trigger the check request with Authorino: `PathMatchRegularExpression`, `HeaderMatchRegularExpression`, and `HTTPQueryParamMatch`. +Due to limitations imposed by the Istio `AuthorizationPolicy`, there are a few patterns of HTTPRouteRules that cannot be translated to filters for the external authorization request. Therefore, the following patterns used in HTTPRouteMatches of top-level route selectors of an AuthPolicy will not be included in the Istio AuthorizationPolicy rules that trigger the check request with Authorino: `PathMatchRegularExpression`, `HeaderMatchRegularExpression`, and `HTTPQueryParamMatch`. + +As a consequence to the above, requests that do not match these rules and otherwise would not be checked with Authorino will result in a request to the external authorization service. Authorino nonetheless will still verify those patterns and ensure the auth scheme is enforced only when it matches a selected HTTPRouteRule. Users of Kuadrant may observe an unnecessary call to the authorization service in those cases where the request is out of the scope of the AuthPolicy and therefore always authorized. - As a consequence to the above, requests that do not match these rules and otherwise would not be checked with Authorino will result in a request to the external authorization service. Authorino nonetheless will still verify those patterns and ensure the auth scheme is enforced only when it matches a selected HTTPRouteRule. Users of Kuadrant may observe an unnecessary call to the authorization service in those cases where the request is out of the scope of the AuthPolicy and therefore always authorized.
### Internal custom resources and namespaces diff --git a/doc/overviews/rate-limiting.md b/doc/overviews/rate-limiting.md index 5883757db..7c175b60e 100644 --- a/doc/overviews/rate-limiting.md +++ b/doc/overviews/rate-limiting.md @@ -250,9 +250,9 @@ The selectors within the `when` conditions of a RateLimitPolicy are a subset of Check out the following user guides for examples of rate limiting services with Kuadrant: -- [Simple Rate Limiting for Applications](../user-guides/ratelimiting/simple-rl-for-app.md) -- [Authenticated Rate Limiting for Application](../user-guides/ratelimiting/authenticated-rl-for-app.md) -- [Gateway Rate Limiting for Cluster Operators](../user-guides/ratelimiting/multi-rlp-multi-listener.md) +- [Simple Rate Limiting for Applications](../user-guides/ratelimiting/simple-rl-for-app-developers.md) +- [Authenticated Rate Limiting for Application](../user-guides/ratelimiting/authenticated-rl-for-app-developers.md.md) +- [Gateway Rate Limiting for Cluster Operators](../user-guides/ratelimiting/gateway-rl-for-cluster-operators.md) - [Authenticated Rate Limiting with JWTs and Kubernetes RBAC](../user-guides/ratelimiting/authenticated-rl-with-jwt-and-k8s-authnz.md) ### Known limitations