proposal: SecurityPolicy

[Alice-Lilith]

Relates to

#1492
#1821
#1846

What is this?

SecurityPolicy is a proposal for a new policy attachment resource that can be applied to Gateways and xRoute resources. It is meant to supplement a lot of config that Gateway API currently lacks while also providing a way to specify global defaults. It is similar to the proposal for an UpstreamTrafficPolicy with the notable difference that this tackles authentication based features and will thus support overrides and defaults.

How would I use this resource?

You can attach an SecurityPolicy to a Gateway to set global defaults that will apply to all children xRoute objects of that Gateway. You can also create an SecurityPolicy to attach to an xRoute object to configure things on a route-to-route basis and override global defaults if needed.

How will the overrides and defaults work?

If there is an SecurityPolicy X attached to a Gateway, and an SecurityPolicy Y attached to an HTTPRoute:

• overrides from policy X will win in a conflict with overrides from policy Y.
  • This is to support the use-case of a cluster admin/operator setting some global overrides that are not allowed to be changed on a route level
• defaults from policy Y will win in a conflict with defaults from policy X.
  • While cluster admins/operators might want to provide sane defaults, developers creating xRoute objects should still be able to override those defaults on a route-to-route basis (unless otherwise enforced by Gateway level overrides in the above scenario)

What if Gateway API implements a GEP that delivers the same functionality as some of the fields of this resource?

If Gateway improves any of their existing resources to deliver functionality that meets all of the needs of any of the below config,
then we will deprecate the field in this resource and use the Gateway API config instead. Ideally, a lot of this config can be
upstreamed into Gateway API in some form eventually since this resource only exists to solve areas where Gateway API is lacking for the needs of Envoy Gateway.

Can you use multiple SecurityPolicy resources at the same time?

You may use multiple AuthPolicies that target different resources, but you may not attach multiple AuthPolicies
to the same resource. For example, it is invalid to attach two AuthPolicies to the same Gateway. Merging config in this scenario would quickly become convoluted and confusing, and there are many edge-case scenarios that make supporting this undesirable.

How will this be developed/implemented?

This issue serves as a proposal for the high-level design and fields of the API, but that does not mean that every field included below will be immediately available. My plan for the implementation is to add and implement one high-level field at a time until the whole resource is implemented.

API outline

---
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: SecurityPolicy
metadata:
  name: example-policy
spec:
  # defaults and overrides will have the same configuration options.
  # If there is an SecurityPolicy A attached to a Gateway, and an SecurityPolicy B
  # attached to an xRoute, `overrides` from policy A win and `defaults` win for policy B
  # This allows for global defaults, changing those defaults on a route to route basis and enforcing
  # certain settings at a Gateway level.
  defaults:
  overrides:
    connections: # optional
      ipBlocking: # optional
        mode: Enum(allow-list/deny-list) # required
        ips: # required, minItems=1
        - type: Enum(peer/remote) # required
          value: string # required (example: 127.0.0.1 or 99.99.0.0/16)
    cors: # optional
      allowedOrigins: []string # required
      allowedMethods: []string # optional
      allowedHeaders: []string # optional
      allowCredentials: bool # optional
      exposedHeaders: []string # optional
      maxAge: string # optional
    authentication: # optional
      bypassAuth: bool # optional
      filters: # optional (allows setting default auth filter(s) or forcing them)
        # action controls how the filter is added. add will add the filter to the list of existing filters, 
        # replace will remove any existing AuthenticationFilters first.
        action: Enum (add/replace) # optional, default=add
        # priority determines the ordering of the filter if there are other filters on the resource.
        # The derfault priority of all filters is interpreted as 0 which will cause the filter to be 
        # appended to the list if other filters exist. negative values can prepend the filter(s) to any existing ones.
        priority: int # optional, default=0.
        targetRef: # required
          group: string
          kind: string # only Envoy Gateway's AuthenticationFilter will be supported for now
          name: string
  targetRef: # required
    group: string
    kind: string # must be a Gateway or xRoute object reference
    name: string

Open questions

• This resource can be attached to a Gateway, but you can configure multiple listeners on a single Gateway. Realistically, this resource makes the most sense targeting listeners instead of forcing this to apply to the entire gateway. There should be a way to specify which listeners it applies to so that you can have different config for each listener.
  • After discussion with @arkodg in the Gateway meeting today, we agree that the best approach is likely to start with making this apply to the entire Gateway and then adding in support for @zhaohuabing's SectionName to PolicyTargetReference enhancement when it lands and becomes available.

Edits

• Changed name from AuthPolicy to SecurityPolicy

[zhaohuabing]

@AliceProxy this looks overall good. I have a few questions:

• EG will also need to support Authorization, for example, define which identify can access which Gateway/Listener/Route/Path. Do you plan to incorporate authorization in the AuthPolicy API, or propose a separate Authorization Policy?
• I don't understand the filters part inside the authentication. Is it a Envoy filter reference, or a Gateway API resource, or an EG resource? Could you please elaborate on that?

Thanks.

[arkodg]

wanted to highlight that the usage of overrides & defaults here and not in UpstreamTrafficPolicy feels weird and adds cognitive load on user to remember that some Inherited Policy Attachments APIs use overrides and defaults and some dont.
I would vote to just introduce overrides and defaults in the UpstreamTrafficPolicy and combine the 2 APIs

[Alice-Lilith]

@zhaohuabing

EG will also need to support Authorization, for example, define which identify can access which Gateway/Listener/Route/Path. Do you plan to incorporate authorization in the AuthPolicy API, or propose a separate Authorization Policy?

I'm sure this policy isn't exhaustive, but yes, I would like to use this resource for any authorization/authentication features and config knobs we would like to support in the future adding any additional top-level fields or expanding existing fields.

I don't understand the filters part inside the authentication. Is it a Envoy filter reference, or a Gateway API resource, or an EG resource? Could you please elaborate on that?

The filters is currently meant to reference our AuthenticationFilter resource so that you could specify default filters that you want to run on all children xRoutes of a Gateway unless otherwise overridden, or even to configure Gateway level filters that must be enforced on all routes and cannot be removed by any other config.

@arkodg was mentioning that if this resource is implemented and is successful, we might even deprecate the AuthenticaitonFilter and only use this policy resource to in-line the same configuration so that we reduce the total number of CRDs we are adding on top of Gateway API.

[zhaohuabing]

I'm sure this policy isn't exhaustive, but yes, I would like to use this resource for any authorization/authentication features and config knobs we would like to support in the future adding any additional top-level fields or expanding existing fields.

I incline to have a separate authorization policy, as Authn and Authz repsent two different facets of security considerations. In most systems, such as Kubernetes and Istio, these two aspects are managed separately.

The filters is currently meant to reference our AuthenticationFilter resource so that you could specify default filters that you want to run on all children xRoutes of a Gateway unless otherwise overridden, or even to configure Gateway level filters that must be enforced on all routes and cannot be removed by any other config.

IMO, it's a bit weird to put all other auth-related configurations in the AuthPolicy and only leave JWT authentication to a standalone resource. We should do it one way or another. It looks to me that the preference of this proposal is to keep all auth-related configurations within the AuthPolicy, so I suggest merging the specs of AuthenticationFilter into it and phasing out the original AuthenticationFilter API.

[arkodg]

thinking about this again, it makes sense to have a separate API for authn & authz instead of collapsing this into UpstreamTrafficPolicy to provide flexibility in authorship, allowing the platform admin persona to be split up into net admin and sec admin .

Reg naming, prefer SecurityPolicy over AuthPolicy

[zhaohuabing]

After discussion with @AliceProxy at this week's EG meeting, we agreed that the OIDCAuthenticationPolicy should be merged with this one to provide users a more unified auth AP. I would also like to suggest incorporating the JwtAuthenticationFilter in this Policy so that all authentication configurations can be found in just one CRD.

kind: SecurityPolicy
metadata:
  name: example-policy
spec:
  # defaults and overrides will have the same configuration options.
  # If there is an SecurityPolicy A attached to a Gateway, and an SecurityPolicy B
  # attached to an xRoute, `overrides` from policy A win and `defaults` win for policy B
  # This allows for global defaults, changing those defaults on a route to route basis and enforcing
  # certain settings at a Gateway level.
  defaults:
  overrides:
    connections: # optional
      ipBlocking: # optional
        mode: Enum(allow-list/deny-list) # required
        ips: # required, minItems=1
        - type: Enum(peer/remote) # required
          value: string # required (example: 127.0.0.1 or 99.99.0.0/16)
    cors: # optional
      allowedOrigins: []string # required
      allowedMethods: []string # optional
      allowedHeaders: []string # optional
      allowCredentials: bool # optional
      exposedHeaders: []string # optional
      maxAge: string # optional
    authentication: # optional
      bypassAuth: bool # optional
      oidc: # oidc authentication configuration
        provider: # the information of the OIDC identity provider
          issuer: string # The OIDC identity provider's issuer identifier. It’s also an URL which can be used by EG to discover the provider’s AuthorizationEndpoint and TokenEndpoint. An example: "https://accounts.google.com" 
          AuthorizationEndpoint: string # optional The URL to which users are redirected in the authentication flow. If not provided,TEG will obtain it from the provider's Well-Known Configuration Endpoint through the OIDC discovery mechanism.
          TokenEndpoint: The URL where your application exchanges the authorization code for an access token. It’s an optional field.  If not provided,EG will obtain it from the provider's Well-Known Configuration Endpoint through the OIDC discovery mechanism.
        clientID: string # This is an unique identifier assigned to your application by the OIDC identity provider. An Example "xxx.apps.googleusercontent.com"
        clientSecret: The Kubernetes secret which contains the OIDC client secret, which is a confidential token shared between your application and the OIDC identity provider to authenticate your application.
          name: "oidc-client-secret"
          namespace:  string # optional
        scopes: []string # optional, if not specified, "openid" is used.
      jwt: # jwt authentication configuration
        issuer: # optional Issuer is the principal that issued the JWT and takes the form of a URL or email address.If not provided, the JWT issuer is not checked.
        audiences: # optinal Audiences is a list of JWT audiences allowed access. If not provided, JWT audiences are not checked.
        remoteJWKS: # RemoteJWKS defines how to fetch and cache JSON Web Key Sets (JWKS) from a remote HTTP/HTTPS endpoint.
          uri: https://raw.githubusercontent.com/envoyproxy/gateway/main/examples/kubernetes/authn/jwks.json
        claimToHeaders: # optinal A list of JWT claims that must be extracted into HTTP request headers  
  targetRef: # required
    group: string
    kind: string # must be a Gateway or xRoute object reference
    name: string

A few other things I'd like to bring up:

• Regarding the override/default: I'm not sure that we should support override/default though. The final policy would be a combination of the policy attached to the gateway and the policy attached to the route. It would become very hard to figure out which configuration form which policy and why it is applied when some thing goes wrong. We probably need different traffic policy, such as timeout, connection pool size, retries, for different routes, but we normally don't need disctinct security configurations at route level. I think we should keep it simple and only support one policy per gateway (very likely another level at listener when this API Gateway proposal is accepted) and one policy per route. When there're multiple policies at different levels, all settings from policy with the most specific wins.
• Should Authn and Authz be in one CRD or two? I'm leaning slightly towards creating two CRDs, as Authn and Authz repsent two distinct facets of security considerations. In most systems, such as Kubernetes and Istio, these two aspects are managed separately. However, I don't have a very strong preference for this option. My main objective is to provide rational for choosing either one CRD or two.