Add support for HTTP Basic Authentication

[zhaohuabing]

What would you like to be added:
The ability to configure HTTP Basic Authentication on a Gateway or an HTTPRoute.

Why this is needed:
HTTP Basic Authentication is a simple authentication scheme that uses a username and password pair in the HTTP request header. It's widely used in web applications and APIs and supported by Gateway implementations.

Existing Implementations:
Some existing data planes that support Basic Authentication

• Envoy - https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/basic_auth_filter
• NGINX - https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-http-basic-authentication/

Some existing control planes that support Basic Authentication

• Emissary - https://www.getambassador.io/docs/emissary/latest/howtos/basic-auth
• Envoy Gateway - feat: basic auth API envoyproxy/gateway#2199
• Ingress Nginx - https://kubernetes.github.io/ingress-nginx/examples/auth/basic/

Relates to envoyproxy/gateway#1660

[guicassolato]

Here's how Kuadrant supports this use case using policies: https://docs.kuadrant.io/kuadrant-operator/doc/user-guides/auth-for-app-devs-and-platform-engineers/#3-protect-the-toy-store-application-persona-app-developer.

The example covers authentication and authorization. The latter you can ignore, but the former can easily shapeshift from API key to HTTP Basic Auth (RFC 7235) by simply replacing prefix: APIKEY for prefix: Basic.

The username:passwd pairs are stored base64-encoded in Kubernetes secrets. Like here: https://docs.kuadrant.io/authorino/docs/user-guides/http-basic-authentication/#create-user-credentials.

[tao12345666333]

I expected them to be separable. Because there are many different configuration methods for these authentication methods for various gateways/KICs, forcibly coupling them in one policy will make it difficult to validate.

[zhaohuabing]

I recommend consolidating multiple configurations into a single policy whenever we can, and optioning for a standalone policy when necessary.

The primary rationale behind this approach is that it‘s much easier to manage those configurations in a single place. If lots of security-related configurations are scattered in a system, it would become a nightmare for the admin. Centralizing configurations within a unified policy not only streamlines the management process but also contributes to a more efficient and organized system administration.

[youngnick]

I think there's a tradeoff in policy size to consider.

Large Policy objects with lots of settings have the advantage that they're easier to manage, in that less CRDs is easier to manage, but the disadvantage that they're harder to control and have a larger blast radius. Harder to control because the object is larger, so access to the object is access to all the settings it controls, and larger blast radius because a serious mistake can affect more settings (if we don't design the Policy carefully to ensure that it's only used for one type at a time)

Smaller Policy objects are harder to implement (because you have to reconcile them individually), and have the higher cognitive cost of having more things to think about. Also, and most importantly, it's easier to make progress on the objects when you don't have as many use cases - this is what we found with BackendTLSPolicy.

[zhaohuabing]

Each approach comes with its own set of benefits and tradeoffs.

Auth/Security policy is a bit different than traffic-related policy. While the definition of the CRD can be large and have multiple configurations in it, the actual policy instances are likely to be small. This is due to the typical scenario where only one or a limited number of authn/authz method is employed in an application.

Overall, I agree that we can follow BackendTLSPolicy pattern as it's already used in Gateway API and proved to work. It's also easier to add new policies incrementally.

[youngnick]

As I said below, I actually think we should add Filter fields for each of these instead.

[robscott]

Thanks for raising this @zhaohuabing! x-ref #1494 which has some overlap

[zhaohuabing]

This is how Envoy Gateway supports Basic Auth:

Envoy Gateway uses .htpasswd format to store the username-password pairs for authentication. The file is stored in a kubernetes secret and referenced in the SecurityPolicy configuration. The secret is an Opaque secret, and the username-password pairs must be stored in the key ".htpasswd".

https://github.com/envoyproxy/gateway/blob/main/site/content/en/latest/user/basic-auth.md

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: SecurityPolicy
metadata:
  name: basic-auth-example
spec:
  targetRef:
    group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: backend
  basicAuth:
    users:
      name: "basic-auth"

Secret:

apiVersion: v1
data:
  .htpasswd: Zm9vOntTSEF9WXMyM0FnLzVJT1dxWkN3OVFHYVZEZEh3SDAwPQpmb28xOntTSEF9ZGpaMTFxSFkwS09pamV5bUs3YUt2WXV2aHZNPQo=
kind: Secret
metadata:
  name: basic-auth
  namespace: default
type: Opaque

The username-password pairs:

$ cat .htpasswd 
foo:{SHA}Ys23Ag/5IOWqZCw9QGaVDdHwH00=
foo1:{SHA}djZ11qHY0KOijeymK7aKvYuvhvM=

[youngnick]

The more I think about this and other auth concepts, the more that I think I'd like to see these as standard Filters. We don't have to use Policy for this, and these operations feel similar to me to Extended Filters like Request Redirect or URL Rewrite (at least to begin with). Each of them manipulates the HTTP request to add additional behavior, which feels to me like the definition of a Filter.

The existing Envoy Gateway prior art (which is really neat, btw), is actually an example of a Policy that's actually an Inherited Policy, not a Direct one - since it can be applied at the Gateway level and affect config on HTTPRoute objects.

I think that behavior is desirable, but we should make it more explicit.

First, we introduce the Filters for whatever auth methods we want (Basic, JWT, and Oauth2 seem pretty reasonable to target, with others left for ExtensionRef). This can be done as a discreet set of changes.

Then, we add an AuthenticationPolicy that allows configuring of defaults or overrides for each of these filters at the Gateway or GatewayClass level. That's a full Inherited Policy that's included in Gateway API.

My reason for suggesting this is that I think that the main reason that EG went with a Policy is that the additional overhead of managing an Policy vs an ExtensionRef Filter CRD is not too big, and can also be used at the Gateway level.

But because we're doing this upstream now, we can add new fields to HTTPRoute itself and make them experimental fields that will probably end up in Extended support once they move to the Standard channel. (That is, they'll be optional but have conformance tests).

Then, we can add defaulting or overriding at a Gateway or above level at a later date if we need it. I'm pretty confident at least some users will want that, but this way we're getting something useful into the spec as quickly as possible.

[zhaohuabing]

My reason for suggesting this is that I think that the main reason that EG went with a Policy is that the additional overhead of managing a Policy vs an ExtensionRef Filter CRD is not too big, and can also be used at the Gateway level.

I believe EG went with a Policy vs a filter because Policy is more flexible: Policy can target at different levels in the Gateway API resource tree: GatewayClass, Gateway, Listener, Route, etc. The overhead of managing a Policy vs an ExtensionRef Filter is very small and can be ignored.

IMO, the below factors need to be considered when we decide which way to go in the Gateway API.

• Are these settings more likely to be required at the Gateway or the HTTPRoute?
  • If, in most cases, these settings only need to be specified at the HTTPRoute, they should be defined as Filters.
  • If, in most cases, these settings only need to be specified at the Gateway globally, they should be defined as Policies.
  • If there is uncertainty about whether these settings will be needed at the HTTPRoute or Gateway, they should be defined as Policies.

I presume that the majority of auth settings should be specified at the HTTPRoute level, considering each HTTPRoute points to a distinct application behind the Gateway proxy. If this assumption holds, I agree with @youngnick 's HTTPFilter + Policy suggestion. Otherwise, there is a risk of duplications between the global Policy CRD and the HTTPFilter CRD. Maintaining similar/identical structures in both Policy and Filter CRD could become challenging for the Gateway API.

An additional concern with this approach is that an extra policy needs to be defined to override a custom HTTPFilter, which means for each auth extension, two new custom CRDs must be defined - seems too much overheads on the implementations side.

[guicassolato]

Personally, I can cope with extensionRef, even though by default it locks down legit efforts of extending the functionalities of the gateway by agnostic policy providers, such as Kuadrant. However, adding filters for authentication methods such as JWT and OAuth2 is a very bad decision IMO.

With all due respect, the complexity that comes together with configuring for those methods of authentication should not underestimated. E.g.:

• Will it have a field to specify a JWKS URL only or optionally an issuer URL as well, to extend support for OIDC discovery maybe?
• Will it allow restricting the accepted encryption algorithms or selecting specific signing keys?
• Will it include support for enabling/disabling individual JWT claim checks, like on iss, exp, nbf or will those require an additional authorization step afterwards?
• Will it have have support for all OAuth2 grants?
• Will it include a field to reference an OAuth client secret object?
• Will it allow configuring the details of TLS for the requests that need to be implemented by the gateway to the auth servers?

My point is the filter would have to be very basic, and all the configs would end up going in an external policy anyway.

[guicassolato]

@youngnick, separate discussion about this sentence:

The existing Envoy Gateway prior art (which is really neat, btw), is actually an example of a Policy that's actually an Inherited Policy, not a Direct one - since it can be applied at the Gateway level and affect config on HTTPRoute objects. #2626 (comment)

I thought Inherited Policy Attachment was "all about the defaults and overrides."

If I simply attach an AuthPolicy A to a Gateway object, I would expect that policy to apply to all routes accepted through that gateway. At least until a more specific AuthPolicy B is attached to a particular HTTPRoute; in which case, without defaults and overrides, AuthPolicy B would fully replace the behavior previously imposed by AuthPolicy A, but only for the particular HTTPRoute AuthPolicy B is attached to. For all other HTTPRoutes, AuthPolicy A remains.

Wouldn't this be a typical description of Direct Policy Attachment?

[youngnick]

Well, my argument is that in that case you're applying a default at the Gateway level, that you're then overriding with config at the Route level. In effect, the Policy is both a Direct one (when attached to a HTTPRoute), and an Inherited one (when attached to a Gateway). I think I didn't really think enough about this possibility in the beginning, and I don't think it's well explained, sigh - but I think that an important part of Direct Policy attachment is that not only does it attach to the thing it's modifying, any modifications are confined to that thing, and only that thing.

The reason for this is that, once the Policy's impact spreads beyond a single object, you end up with a similar status/information retrieval problem to a more traditional Inherited Policy - which Policy objects are affecting your HTTPRoute is not visible from your HTTPRoute.

In Kuadrant, how does a HTTPRoute owner know what Policy objects are affecting theirs? Presumably, it's not reflected in the spec of the HTTPRoute, and unless status updates are carefully designed, at scale they run the risk of creating big fanout problems for the apiserver (in that updating a single Policy may require status updates on many HTTPRoutes). I'm not trying to be mean here, I legitimately have not spent nearly as much time as I should parsing the great work you all are doing there.

[maleck13]

This particular discoverability problem is not one that we a great answer for right now and needs a fair bit more thought. I do however see the value in a CLI tool for this or possibly an API like SubjectAccessReview IE a point in time review of the policies effecting a resource (just a thought at this point though).