API: authorization api for jwt claims

api/v1alpha1/authorization_types.go

@@ -36,6 +36,9 @@ type AuthorizationRule struct {
 	Action AuthorizationAction `json:"action"`
 
 	// Principal specifies the client identity of a request.
+	// If there are multiple principal types, all principals must match for the rule to match.
+	// For example, if there are two principals: one for client IP and one for JWT claim,
+	// the rule will match only if both the client IP and the JWT claim match.
 	Principal Principal `json:"principal"`
 }
 
@@ -47,17 +50,59 @@ type Principal struct {
 	// ClientCIDRs are the IP CIDR ranges of the client.
 	// Valid examples are "192.168.1.0/24" or "2001:db8::/64"
 	//
+	// If multiple CIDR ranges are specified, one of the CIDR ranges must match
+	// the client IP for the rule to match.
+	//
 	// The client IP is inferred from the X-Forwarded-For header, a custom header,
 	// or the proxy protocol.
 	// You can use the `ClientIPDetection` or the `EnableProxyProtocol` field in
 	// the `ClientTrafficPolicy` to configure how the client IP is detected.
 	// +kubebuilder:validation:MinItems=1
 	ClientCIDRs []CIDR `json:"clientCIDRs"`
 
-	// TODO: Zhaohuabing the MinItems=1 validation can be relaxed to allow empty list
-	// after other principal types are supported. However, at least one principal is required
+	// JWTClaims are the claims in a JWT token.
+	//
+	// If multiple claims are specified, all claims must match for the rule to match.
+	// For example, if there are two claims: one for the audience and one for the issuer,
+	// the rule will match only if both the audience and the issuer match.
+	// Note: in order to use JWT claims for authorization, you must configure the
+	// JWT authentication in the same `SecurityPolicy`.
+	// +optional
+	// +notImplementedHide
+	JWTClaims []JWTClaim `json:"jwtClaims"`
 }
 
+// JWTClaim specifies a claim in a JWT token.
+type JWTClaim struct {
+	// Type is the type of the claim.
+	// Valid values are "String" and "StringArray".
+	// For example, sub is a string claim, and groups is a string array claim.
+	// +kubebuilder:validation:Enum=String;StringArray
+	// +kubebuilder:default=String
+	// +unionDiscriminator
+	Type JWTClaimType `json:"type"`
+
+	// Name is the name of the claim.
+	// If it is a nested claim, use a dot (.) separated string as the name to
+	// represent the full path to the claim.
+	// For example, if the claim is in the "department" field in the "organization" field,
+	// the name should be "organization.department".
+	Name string `json:"name"`
+
+	// Values are the values that the claim must match.
+	// If the claim is a string type, the specified value must match exactly.
+	// If the claim is a string array type, the specified value must match one of the values in the array.
+	// If multiple values are specified, one of the values must match for the rule to match.
+	Values []string `json:"values"`
+}
+
+type JWTClaimType string
+
+const (
+	JWTClaimTypeString      JWTClaimType = "String"
+	JWTClaimTypeStringArray JWTClaimType = "StringArray"
+)
+
 // AuthorizationAction defines the action to be taken if a rule matches.
 // +kubebuilder:validation:Enum=Allow;Deny
 type AuthorizationAction string

charts/gateway-helm/crds/generated/gateway.envoyproxy.io_securitypolicies.yaml

@@ -86,15 +86,22 @@ spec:
                             If not specified, Envoy Gateway will generate a unique name for the rule.n
                           type: string
                         principal:
-                          description: Principal specifies the client identity of
-                            a request.
+                          description: |-
+                            Principal specifies the client identity of a request.
+                            If there are multiple principal types, all principals must match for the rule to match.
+                            For example, if there are two principals: one for client IP and one for JWT claim,
+                            the rule will match only if both the client IP and the JWT claim match.
                           properties:
                             clientCIDRs:
                               description: |-
                                 ClientCIDRs are the IP CIDR ranges of the client.
                                 Valid examples are "192.168.1.0/24" or "2001:db8::/64"
 
 
+                                If multiple CIDR ranges are specified, one of the CIDR ranges must match
+                                the client IP for the rule to match.
+
+
                                 The client IP is inferred from the X-Forwarded-For header, a custom header,
                                 or the proxy protocol.
                                 You can use the `ClientIPDetection` or the `EnableProxyProtocol` field in
@@ -107,6 +114,52 @@ spec:
                                 type: string
                               minItems: 1
                               type: array
+                            jwtClaims:
+                              description: |-
+                                JWTClaims are the claims in a JWT token.
+
+
+                                If multiple claims are specified, all claims must match for the rule to match.
+                                For example, if there are two claims: one for the audience and one for the issuer,
+                                the rule will match only if both the audience and the issuer match.
+                                Note: in order to use JWT claims for authorization, you must configure the
+                                JWT authentication in the same `SecurityPolicy`.
+                              items:
+                                description: JWTClaim specifies a claim in a JWT token.
+                                properties:
+                                  name:
+                                    description: |-
+                                      Name is the name of the claim.
+                                      If it is a nested claim, use a dot (.) separated string as the name to
+                                      represent the full path to the claim.
+                                      For example, if the claim is in the "department" field in the "organization" field,
+                                      the name should be "organization.department".
+                                    type: string
+                                  type:
+                                    default: String
+                                    description: |-
+                                      Type is the type of the claim.
+                                      Valid values are "String" and "StringArray".
+                                      For example, sub is a string claim, and groups is a string array claim.
+                                    enum:
+                                    - String
+                                    - StringArray
+                                    type: string
+                                  values:
+                                    description: |-
+                                      Values are the values that the claim must match.
+                                      If the claim is a string type, the specified value must match exactly.
+                                      If the claim is a string array type, the specified value must match one of the values in the array.
+                                      If multiple values are specified, one of the values must match for the rule to match.
+                                    items:
+                                      type: string
+                                    type: array
+                                required:
+                                - name
+                                - type
+                                - values
+                                type: object
+                              type: array
                           required:
                           - clientCIDRs
                           type: object

internal/gatewayapi/testdata/securitypolicy-with-authoriztion.out.yaml

@@ -187,12 +187,14 @@ securityPolicies:
           clientCIDRs:
           - 192.168.1.0/24
           - 192.168.2.0/24
+          jwtClaims: null
       - action: Deny
         name: deny-location-2
         principal:
           clientCIDRs:
           - 10.75.1.0/24
           - 10.75.2.0/24
+          jwtClaims: null
     targetRef:
       group: gateway.networking.k8s.io
       kind: HTTPRoute
@@ -255,6 +257,7 @@ securityPolicies:
           clientCIDRs:
           - 10.0.1.0/24
           - 10.0.2.0/24
+          jwtClaims: null
     targetRef:
       group: gateway.networking.k8s.io
       kind: Gateway

site/content/en/latest/api/extension_types.md

@@ -240,7 +240,7 @@ _Appears in:_
 | ---   | ---  | ---      | ---         |
 | `name` | _string_ |  false  | Name is a user-friendly name for the rule.<br />If not specified, Envoy Gateway will generate a unique name for the rule.n |
 | `action` | _[AuthorizationAction](#authorizationaction)_ |  true  | Action defines the action to be taken if the rule matches. |
-| `principal` | _[Principal](#principal)_ |  true  | Principal specifies the client identity of a request. |
+| `principal` | _[Principal](#principal)_ |  true  | Principal specifies the client identity of a request.<br />If there are multiple principal types, all principals must match for the rule to match.<br />For example, if there are two principals: one for client IP and one for JWT claim,<br />the rule will match only if both the client IP and the JWT claim match. |
 
 
 #### BackOffPolicy
@@ -2119,6 +2119,37 @@ _Appears in:_
 | `providers` | _[JWTProvider](#jwtprovider) array_ |  true  | Providers defines the JSON Web Token (JWT) authentication provider type.<br />When multiple JWT providers are specified, the JWT is considered valid if<br />any of the providers successfully validate the JWT. For additional details,<br />see https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/jwt_authn_filter.html. |
 
 
+#### JWTClaim
+
+
+
+JWTClaim specifies a claim in a JWT token.
+
+_Appears in:_
+- [Principal](#principal)
+
+| Field | Type | Required | Description |
+| ---   | ---  | ---      | ---         |
+| `type` | _[JWTClaimType](#jwtclaimtype)_ |  true  | Type is the type of the claim.<br />Valid values are "String" and "StringArray".<br />For example, sub is a string claim, and groups is a string array claim. |
+| `name` | _string_ |  true  | Name is the name of the claim.<br />If it is a nested claim, use a dot (.) separated string as the name to<br />represent the full path to the claim.<br />For example, if the claim is in the "department" field in the "organization" field,<br />the name should be "organization.department". |
+| `values` | _string array_ |  true  | Values are the values that the claim must match.<br />If the claim is a string type, the specified value must match exactly.<br />If the claim is a string array type, the specified value must match one of the values in the array.<br />If multiple values are specified, one of the values must match for the rule to match. |
+
+
+#### JWTClaimType
+
+_Underlying type:_ _string_
+
+
+
+_Appears in:_
+- [JWTClaim](#jwtclaim)
+
+| Value | Description |
+| ----- | ----------- |
+| `String` |  | 
+| `StringArray` |  | 
+
+
 #### JWTExtractor
 
 
@@ -2665,7 +2696,7 @@ _Appears in:_
 
 | Field | Type | Required | Description |
 | ---   | ---  | ---      | ---         |
-| `clientCIDRs` | _[CIDR](#cidr) array_ |  true  | ClientCIDRs are the IP CIDR ranges of the client.<br />Valid examples are "192.168.1.0/24" or "2001:db8::/64"<br /><br />The client IP is inferred from the X-Forwarded-For header, a custom header,<br />or the proxy protocol.<br />You can use the `ClientIPDetection` or the `EnableProxyProtocol` field in<br />the `ClientTrafficPolicy` to configure how the client IP is detected. |
+| `clientCIDRs` | _[CIDR](#cidr) array_ |  true  | ClientCIDRs are the IP CIDR ranges of the client.<br />Valid examples are "192.168.1.0/24" or "2001:db8::/64"<br /><br />If multiple CIDR ranges are specified, one of the CIDR ranges must match<br />the client IP for the rule to match.<br /><br />The client IP is inferred from the X-Forwarded-For header, a custom header,<br />or the proxy protocol.<br />You can use the `ClientIPDetection` or the `EnableProxyProtocol` field in<br />the `ClientTrafficPolicy` to configure how the client IP is detected. |
 
 
 #### ProcessingModeOptions

site/content/zh/latest/api/extension_types.md

@@ -240,7 +240,7 @@ _Appears in:_
 | ---   | ---  | ---      | ---         |
 | `name` | _string_ |  false  | Name is a user-friendly name for the rule.<br />If not specified, Envoy Gateway will generate a unique name for the rule.n |
 | `action` | _[AuthorizationAction](#authorizationaction)_ |  true  | Action defines the action to be taken if the rule matches. |
-| `principal` | _[Principal](#principal)_ |  true  | Principal specifies the client identity of a request. |
+| `principal` | _[Principal](#principal)_ |  true  | Principal specifies the client identity of a request.<br />If there are multiple principal types, all principals must match for the rule to match.<br />For example, if there are two principals: one for client IP and one for JWT claim,<br />the rule will match only if both the client IP and the JWT claim match. |
 
 
 #### BackOffPolicy
@@ -2119,6 +2119,37 @@ _Appears in:_
 | `providers` | _[JWTProvider](#jwtprovider) array_ |  true  | Providers defines the JSON Web Token (JWT) authentication provider type.<br />When multiple JWT providers are specified, the JWT is considered valid if<br />any of the providers successfully validate the JWT. For additional details,<br />see https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/jwt_authn_filter.html. |
 
 
+#### JWTClaim
+
+
+
+JWTClaim specifies a claim in a JWT token.
+
+_Appears in:_
+- [Principal](#principal)
+
+| Field | Type | Required | Description |
+| ---   | ---  | ---      | ---         |
+| `type` | _[JWTClaimType](#jwtclaimtype)_ |  true  | Type is the type of the claim.<br />Valid values are "String" and "StringArray".<br />For example, sub is a string claim, and groups is a string array claim. |
+| `name` | _string_ |  true  | Name is the name of the claim.<br />If it is a nested claim, use a dot (.) separated string as the name to<br />represent the full path to the claim.<br />For example, if the claim is in the "department" field in the "organization" field,<br />the name should be "organization.department". |
+| `values` | _string array_ |  true  | Values are the values that the claim must match.<br />If the claim is a string type, the specified value must match exactly.<br />If the claim is a string array type, the specified value must match one of the values in the array.<br />If multiple values are specified, one of the values must match for the rule to match. |
+
+
+#### JWTClaimType
+
+_Underlying type:_ _string_
+
+
+
+_Appears in:_
+- [JWTClaim](#jwtclaim)
+
+| Value | Description |
+| ----- | ----------- |
+| `String` |  | 
+| `StringArray` |  | 
+
+
 #### JWTExtractor
 
 
@@ -2665,7 +2696,7 @@ _Appears in:_
 
 | Field | Type | Required | Description |
 | ---   | ---  | ---      | ---         |
-| `clientCIDRs` | _[CIDR](#cidr) array_ |  true  | ClientCIDRs are the IP CIDR ranges of the client.<br />Valid examples are "192.168.1.0/24" or "2001:db8::/64"<br /><br />The client IP is inferred from the X-Forwarded-For header, a custom header,<br />or the proxy protocol.<br />You can use the `ClientIPDetection` or the `EnableProxyProtocol` field in<br />the `ClientTrafficPolicy` to configure how the client IP is detected. |
+| `clientCIDRs` | _[CIDR](#cidr) array_ |  true  | ClientCIDRs are the IP CIDR ranges of the client.<br />Valid examples are "192.168.1.0/24" or "2001:db8::/64"<br /><br />If multiple CIDR ranges are specified, one of the CIDR ranges must match<br />the client IP for the rule to match.<br /><br />The client IP is inferred from the X-Forwarded-For header, a custom header,<br />or the proxy protocol.<br />You can use the `ClientIPDetection` or the `EnableProxyProtocol` field in<br />the `ClientTrafficPolicy` to configure how the client IP is detected. |
 
 
 #### ProcessingModeOptions