api: Authorization API design (#2652)

* add authorisation api spec Signed-off-by: Jesse Haka <haka.jesse@gmail.com> * add comments Signed-off-by: huabing zhao <zhaohuabing@gmail.com> * Remove permission in the first run Signed-off-by: huabing zhao <zhaohuabing@gmail.com> * Move subject and permission to Rule Signed-off-by: huabing zhao <zhaohuabing@gmail.com> * remove log action Signed-off-by: huabing zhao <zhaohuabing@gmail.com> * add default action Signed-off-by: huabing zhao <zhaohuabing@gmail.com> * add excluded client CIDR Signed-off-by: huabing zhao <zhaohuabing@gmail.com> * hide api Signed-off-by: huabing zhao <zhaohuabing@gmail.com> * minor wording Signed-off-by: huabing zhao <zhaohuabing@gmail.com> * remove exclude ip range in the first run Signed-off-by: huabing zhao <zhaohuabing@gmail.com> * change subject to principal: align with Envoy and the AWS RBAC term Signed-off-by: huabing zhao <zhaohuabing@gmail.com> * add Name field to a Rule Signed-off-by: huabing zhao <zhaohuabing@gmail.com> * remove name field for now Signed-off-by: huabing zhao <zhaohuabing@gmail.com> * Update api/v1alpha1/authorization_types.go Co-authored-by: Arko Dasgupta <arkodg@users.noreply.github.com> Signed-off-by: Huabing Zhao <zhaohuabing@gmail.com> * fix docs Signed-off-by: huabing zhao <zhaohuabing@gmail.com> * minor wording Signed-off-by: huabing zhao <zhaohuabing@gmail.com> * fix lint Signed-off-by: huabing zhao <zhaohuabing@gmail.com> --------- Signed-off-by: Jesse Haka <haka.jesse@gmail.com> Signed-off-by: huabing zhao <zhaohuabing@gmail.com> Signed-off-by: Huabing Zhao <zhaohuabing@gmail.com> Co-authored-by: huabing zhao <zhaohuabing@gmail.com> Co-authored-by: Arko Dasgupta <arkodg@users.noreply.github.com>
envoyproxy · May 12, 2024 · 3bc7cf1 · 3bc7cf1
1 parent c30d09f
commit 3bc7cf1
Show file tree

Hide file tree

Showing 7 changed files with 255 additions and 3 deletions.
diff --git a/api/v1alpha1/authorization_types.go b/api/v1alpha1/authorization_types.go
@@ -0,0 +1,65 @@
+// Copyright Envoy Gateway Authors
+// SPDX-License-Identifier: Apache-2.0
+// The full text of the Apache license is available in the LICENSE file at
+// the root of the repo.
+
+package v1alpha1
+
+// Authorization defines the authorization configuration.
+// +notImplementedHide
+type Authorization struct {
+	// Rules defines a list of authorization rules.
+	// These rules are evaluated in order, the first matching rule will be applied,
+	// and the rest will be skipped.
+	//
+	// For example, if there are two rules: the first rule allows the request
+	// and the second rule denies it, when a request matches both rules, it will be allowed.
+	//
+	// +optional
+	Rules []Rule `json:"rules,omitempty"`
+
+	// DefaultAction defines the default action to be taken if no rules match.
+	// If not specified, the default action is Deny.
+	// +optional
+	DefaultAction *RuleActionType `json:"defaultAction"`
+}
+
+// Rule defines the single authorization rule.
+// +notImplementedHide
+type Rule struct {
+	// Action defines the action to be taken if the rule matches.
+	Action RuleActionType `json:"action"`
+
+	// Principal specifies the client identity of a request.
+	Principal Principal `json:"principal"`
+
+	// Permissions contains allowed HTTP methods.
+	// If empty, all methods are matching.
+	//
+	// +optional
+	// Permissions []string `json:"permissions,omitempty"`
+}
+
+// Principal specifies the client identity of a request.
+// +notImplementedHide
+type Principal struct {
+	// ClientCIDR is the IP CIDR range of the client.
+	// Valid examples are "192.168.1.0/24" or "2001:db8::/64"
+	//
+	// By default, the client IP is inferred from the x-forwarder-for header and proxy protocol.
+	// You can use the `EnableProxyProtocol` and `ClientIPDetection` options in
+	// the `ClientTrafficPolicy` to configure how the client IP is detected.
+	ClientCIDR []string `json:"clientCIDR,omitempty"`
+}
+
+// RuleActionType specifies the types of authorization rule action.
+// +kubebuilder:validation:Enum=Allow;Deny
+// +notImplementedHide
+type RuleActionType string
+
+const (
+	// Allow is the action to allow the request.
+	Allow RuleActionType = "Allow"
+	// Deny is the action to deny the request.
+	Deny RuleActionType = "Deny"
+)
diff --git a/api/v1alpha1/clienttrafficpolicy_types.go b/api/v1alpha1/clienttrafficpolicy_types.go
@@ -136,7 +136,7 @@ type ClientIPDetectionSettings struct {
 	// +optional
 	XForwardedFor *XForwardedForSettings `json:"xForwardedFor,omitempty"`
 	// CustomHeader provides configuration for determining the client IP address for a request based on
-	// a trusted custom HTTP header. This uses the the custom_header original IP detection extension.
+	// a trusted custom HTTP header. This uses the custom_header original IP detection extension.
 	// Refer to https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/http/original_ip_detection/custom_header/v3/custom_header.proto
 	// for more details.
 	//

diff --git a/api/v1alpha1/securitypolicy_types.go b/api/v1alpha1/securitypolicy_types.go
@@ -69,6 +69,12 @@ type SecurityPolicySpec struct {
 	//
 	// +optional
 	ExtAuth *ExtAuth `json:"extAuth,omitempty"`
+
+	// Authorization defines the authorization configuration.
+	//
+	// +optional
+	// +notImplementedHide
+	Authorization *Authorization `json:"authorization,omitempty"`
 }
 
 //+kubebuilder:object:root=true

diff --git a/api/v1alpha1/zz_generated.deepcopy.go b/api/v1alpha1/zz_generated.deepcopy.go
diff --git a/charts/gateway-helm/crds/generated/gateway.envoyproxy.io_clienttrafficpolicies.yaml b/charts/gateway-helm/crds/generated/gateway.envoyproxy.io_clienttrafficpolicies.yaml
@@ -56,7 +56,7 @@ spec:
                   customHeader:
                     description: |-
                       CustomHeader provides configuration for determining the client IP address for a request based on
-                      a trusted custom HTTP header. This uses the the custom_header original IP detection extension.
+                      a trusted custom HTTP header. This uses the custom_header original IP detection extension.
                       Refer to https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/http/original_ip_detection/custom_header/v3/custom_header.proto
                       for more details.
                     properties:

diff --git a/charts/gateway-helm/crds/generated/gateway.envoyproxy.io_securitypolicies.yaml b/charts/gateway-helm/crds/generated/gateway.envoyproxy.io_securitypolicies.yaml
@@ -49,6 +49,59 @@ spec:
           spec:
             description: Spec defines the desired state of SecurityPolicy.
             properties:
+              authorization:
+                description: Authorization defines the authorization configuration.
+                properties:
+                  defaultAction:
+                    description: |-
+                      DefaultAction defines the default action to be taken if no rules match.
+                      If not specified, the default action is Deny.
+                    enum:
+                    - Allow
+                    - Deny
+                    type: string
+                  rules:
+                    description: |-
+                      Rules defines a list of authorization rules.
+                      These rules are evaluated in order, the first matching rule will be applied,
+                      and the rest will be skipped.
+
+
+                      For example, if there are two rules: the first rule allows the request
+                      and the second rule denies it, when a request matches both rules, it will be allowed.
+                    items:
+                      description: Rule defines the single authorization rule.
+                      properties:
+                        action:
+                          description: Action defines the action to be taken if the
+                            rule matches.
+                          enum:
+                          - Allow
+                          - Deny
+                          type: string
+                        principal:
+                          description: Principal specifies the client identity of
+                            a request.
+                          properties:
+                            clientCIDR:
+                              description: |-
+                                ClientCIDR is the IP CIDR range of the client.
+                                Valid examples are "192.168.1.0/24" or "2001:db8::/64"
+
+
+                                By default, the client IP is inferred from the x-forwarder-for header and proxy protocol.
+                                You can use the `EnableProxyProtocol` and `ClientIPDetection` options in
+                                the `ClientTrafficPolicy` to configure how the client IP is detected.
+                              items:
+                                type: string
+                              type: array
+                          type: object
+                      required:
+                      - action
+                      - principal
+                      type: object
+                    type: array
+                type: object
               basicAuth:
                 description: BasicAuth defines the configuration for the HTTP Basic
                   Authentication.

diff --git a/site/content/en/latest/api/extension_types.md b/site/content/en/latest/api/extension_types.md
@@ -171,6 +171,21 @@ _Appears in:_
 | `TCP` | ActiveHealthCheckerTypeTCP defines the TCP type of health checking.<br /> | 
 
 
+#### Authorization
+
+
+
+Authorization defines the authorization configuration.
+
+_Appears in:_
+- [SecurityPolicySpec](#securitypolicyspec)
+
+| Field | Type | Required | Description |
+| ---   | ---  | ---      | ---         |
+| `rules` | _[Rule](#rule) array_ |  false  | Rules defines a list of authorization rules.<br />These rules are evaluated in order, the first matching rule will be applied,<br />and the rest will be skipped.<br /><br />For example, if there are two rules: the first rule allows the request<br />and the second rule denies it, when a request matches both rules, it will be allowed. |
+| `defaultAction` | _[RuleActionType](#ruleactiontype)_ |  false  | DefaultAction defines the default action to be taken if no rules match.<br />If not specified, the default action is Deny. |
+
+
 #### BackOffPolicy
 
 
@@ -379,7 +394,7 @@ _Appears in:_
 | Field | Type | Required | Description |
 | ---   | ---  | ---      | ---         |
 | `xForwardedFor` | _[XForwardedForSettings](#xforwardedforsettings)_ |  false  | XForwardedForSettings provides configuration for using X-Forwarded-For headers for determining the client IP address. |
-| `customHeader` | _[CustomHeaderExtensionSettings](#customheaderextensionsettings)_ |  false  | CustomHeader provides configuration for determining the client IP address for a request based on<br />a trusted custom HTTP header. This uses the the custom_header original IP detection extension.<br />Refer to https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/http/original_ip_detection/custom_header/v3/custom_header.proto<br />for more details. |
+| `customHeader` | _[CustomHeaderExtensionSettings](#customheaderextensionsettings)_ |  false  | CustomHeader provides configuration for determining the client IP address for a request based on<br />a trusted custom HTTP header. This uses the custom_header original IP detection extension.<br />Refer to https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/http/original_ip_detection/custom_header/v3/custom_header.proto<br />for more details. |
 
 
 #### ClientTLSSettings
@@ -2253,6 +2268,20 @@ _Appears in:_
 | `backOff` | _[BackOffPolicy](#backoffpolicy)_ |  false  | Backoff is the backoff policy to be applied per retry attempt. gateway uses a fully jittered exponential<br />back-off algorithm for retries. For additional details,<br />see https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/router_filter#config-http-filters-router-x-envoy-max-retries |
 
 
+#### Principal
+
+
+
+Principal specifies the client identity of a request.
+
+_Appears in:_
+- [Rule](#rule)
+
+| Field | Type | Required | Description |
+| ---   | ---  | ---      | ---         |
+| `clientCIDR` | _string array_ |  true  | ClientCIDR is the IP CIDR range of the client.<br />Valid examples are "192.168.1.0/24" or "2001:db8::/64"<br /><br />By default, the client IP is inferred from the x-forwarder-for header and proxy protocol.<br />You can use the `EnableProxyProtocol` and `ClientIPDetection` options in<br />the `ClientTrafficPolicy` to configure how the client IP is detected. |
+
+
 #### ProcessingModeOptions
 
 
@@ -2884,6 +2913,37 @@ _Appears in:_
 | `httpStatusCodes` | _[HTTPStatus](#httpstatus) array_ |  false  | HttpStatusCodes specifies the http status codes to be retried.<br />The retriable-status-codes trigger must also be configured for these status codes to trigger a retry. |
 
 
+#### Rule
+
+
+
+Rule defines the single authorization rule.
+
+_Appears in:_
+- [Authorization](#authorization)
+
+| Field | Type | Required | Description |
+| ---   | ---  | ---      | ---         |
+| `action` | _[RuleActionType](#ruleactiontype)_ |  true  | Action defines the action to be taken if the rule matches. |
+| `principal` | _[Principal](#principal)_ |  true  | Principal specifies the client identity of a request. |
+
+
+#### RuleActionType
+
+_Underlying type:_ _string_
+
+RuleActionType specifies the types of authorization rule action.
+
+_Appears in:_
+- [Authorization](#authorization)
+- [Rule](#rule)
+
+| Value | Description |
+| ----- | ----------- |
+| `Allow` | Allow is the action to allow the request.<br /> | 
+| `Deny` | Deny is the action to deny the request.<br /> | 
+
+
 #### SecurityPolicy