Add initial draft of Auth GEP 1494

Signed-off-by: Nick Young <nick@isovalent.com>
Co-authored-by: Jen Gao <jie.gao.1025@gmail.com>

geps/gep-1494/index.md

@@ -0,0 +1,131 @@
+# GEP-1494: HTTP Auth in Gateway API
+
+* Issue: [#1494](https://github.com/kubernetes-sigs/gateway-api/issues/1494)
+* Status: Provisional
+
+(See status definitions [here](/geps/overview/#gep-states).)
+
+
+## TLDR
+
+Provide a method for configuring **Gateway API implementations** to add HTTP Authentication for north-south traffic. The method may also include Authorization config if practical.
+
+
+## Goals
+
+* A way to configure a Gateway Implementation to perform Authentication (at least), with optional Authorization on behalf of Ana the Application Developer.
+
+* A way for Chihiro the Cluster Admin to configure a default Authentication and/or Authorization config for some set of HTTPRoutes.
+
+* Optionally, a way for Ana to have the ability to disable Authentication and/or Authorization for specific routes when needed, allowing certain routes to not be protected.
+
+
+## Non-Goals
+
+* Handling all possible authentication and authorization schemes. Handling a (preferably large) subset of authentication and authorization is acceptable.
+
+
+## Deferred Goals
+
+* (Not performed during the Provisional Phase) Defining the API or configuration to be used.
+
+## Introduction
+
+A common request for Gateway API has been a way to direct implementations to automatically request various forms of authentication (AuthN) and authorization (AuthZ). (see the [GEP Issue](https://github.com/kubernetes-sigs/gateway-api/issues/1494) for some of the history.)
+
+**Authentication (AuthN for short)** refers to proving the requesting party's identity in some fashion.
+
+**Authorization (AuthZ for short)** refers to making decisions about what a party can access _based on their Authenticated identity_.
+
+In this document, we'll use Auth* to represent "AuthN and maybe AuthZ as well".
+
+This capability is useful for both Ana (who wants to have something for AuthN and AuthZ that ensures security without it needing to be built into her app), and Chihiro (who wants to be able to ensure that the platform as a whole conforms to some given level of security).
+
+### Common authentication methods
+
+Before discussing any proposed Auth* solution, it's important to discuss some AuthN methods that are often used in securing modern applications.
+
+#### Basic HTTP Auth
+
+In Basic HTTP Auth, a server asks for authentication as part of returning a `401` status response, and the client includes an `Authorization` header that includes a Base64-encoded username and password.
+
+Because the password is only _encoded_ and not _encrypted_, Basic Auth is totally unsafe when used outside of an encrypted session (like a HTTPS connection).
+
+Basic auth is defined in [RFC-7617](https://datatracker.ietf.org/doc/html/rfc7617).
+
+#### TLS Client Certificate Authentication
+
+TLS includes the possibility of having both the client and server present certificates for the other party to validate. (This is often called "mutual TLS", but is distinct from the use of that term in Service Mesh contexts, where it means something more like "mutual TLS with short-lifetime, automatically created and managed dynamic keypairs for both client and server").
+
+In this case, the server authenticates the client based on the client presenting a certificate that's signed by an authority that's also trusted by the server's trust chain. Some implementations also allow details about the certificate to be passed through to backend clients, to be used in authorization decisions.
+
+TLS v1.3 is defined in [RFC-8446](https://datatracker.ietf.org/doc/html/rfc8446), with v1.2 defined in [RFC-5246](https://datatracker.ietf.org/doc/html/rfc5246).
+
+#### JWT
+
+JWT is a format for representing _claims_, which are stored as fields in a JSON object. In common use, these claims represent various parameters that describe the properties of an authentication, with sample claims being `iss`, Issuer, `sub`, Subject, and `aud`, Audience.
+
+JWT also specified ways in which JWTs can be _nested_, where a JWT is encoded inside another JWT, which allows the use of encryption and signing algorithms. In the Gateway API Auth* case, this is expected to be common, in a pattern looking something like this:
+
+- a common authority issues keypairs to clients and servers
+- clients include JWTs with requests that identify themselves and their intended uses
+- servers unwrap encryption and validate signatures of these JWTs to validate the chain of trust
+- servers use the authentication details to make authorization decisions.
+
+JWT is defined in [RFC-75199](https://datatracker.ietf.org/doc/html/rfc7519).
+
+#### Oauth2 and OIDC
+
+Oauth2 is an _authorization framework_, which allows clients and servers to define ways to perform authentication and authorization in as secure a way as possible. It extensively uses TLS for encryption, and involves a third-party handling the authorization handshake with a client, which the third-party then provides to the server.
+
+Open ID Conect (OIDC) is a protocol based on the OAuth 2 framework, that allows Users to talk to Identity Providers (IDPs), on behalf of a Relying Party (RP), and have the IDP give the user an Identity Token (which the User's browser can then provide as Authentication to the Relying Party), and also allows the RP to request Claims about the User, which can be used for Authorization.
+
+
+## Auth* User Stories
+
+
+* As Ana the Application Developer, I wish to be able to configure that some or all of my service exposed via Gateway API requires Authentication, and ideally to be able to make Authorization decisions about _which_ authenticated clients are allowed to access.
+* As Chihiro the Cluster Admin, I wish to be able to configure default Authentication settings (at least), with an option to enforce Authentication settings (preferable but not required) for some set of services exposed via Gateway API inside my cluster.
+* More User Stories welcomed here!
+
+## Currently implemented Auth mechanisms in implementations
+
+Many Gateway API implementations have implemented some method of configuring Auth* that are currently Implementation Specific.
+
+This section lays out some examples (updates with extra examples we've missed are very welcome).
+
+#### HTTP Authentication
+| Name | External Authentication | Self Authentication |
+| -------- | -------- | -------- |
+| [HAProxy Ingress](https://haproxy-ingress.github.io/docs/configuration/keys/)     | [Custom](https://haproxy-ingress.github.io/docs/configuration/keys/#auth-external) , [OAuth](https://haproxy-ingress.github.io/docs/configuration/keys/#oauth)    | [Basic](https://github.com/jcmoraisjr/haproxy-ingress/tree/master/examples/auth/basic), [mTLS](https://haproxy-ingress.github.io/docs/configuration/keys/#auth-tls)     |
+|[GlooEdge](https://docs.solo.io/gloo-edge/latest/guides/security/auth/extauth/)| [Envoy](https://github.com/solo-io/gloo) ( [Basic](https://docs.solo.io/gloo-edge/latest/guides/security/auth/extauth/basic_auth/), [passthrough](https://docs.solo.io/gloo-edge/latest/guides/security/auth/extauth/passthrough_auth/), [OAuth](https://docs.solo.io/gloo-edge/latest/guides/security/auth/extauth/oauth/), [ApiKey](https://docs.solo.io/gloo-edge/latest/guides/security/auth/extauth/apikey_auth/), [LDAP](https://docs.solo.io/gloo-edge/latest/guides/security/auth/extauth/ldap/), [Plugin](https://docs.solo.io/gloo-edge/latest/guides/security/auth/extauth/plugin_auth/)), [Custom](https://docs.solo.io/gloo-edge/latest/guides/security/auth/custom_auth/) | Envoy ([JWT](https://docs.solo.io/gloo-edge/latest/guides/security/auth/jwt/))
+|[traefik](https://doc.traefik.io/traefik/middlewares/http/forwardauth/)|[Custom(ForwardAuth middleware)](https://doc.traefik.io/traefik/middlewares/http/forwardauth/)|[Basic](https://doc.traefik.io/traefik/middlewares/http/basicauth/), [Digest Auth](https://doc.traefik.io/traefik/middlewares/http/digestauth/)|
+|[Ambassador](https://www.getambassador.io/docs/edge-stack/latest/howtos/ext-filters)|[Envoy](https://github.com/emissary-ingress/emissary) ([Basic](https://www.getambassador.io/docs/edge-stack/latest/howtos/ext-filters#2-configure-aesambassador-edge-stack-authentication))|[SSO(OAuth, OIDC)](https://www.getambassador.io/docs/edge-stack/latest/howtos/oauth-oidc-auth) |
+|[ingress-nginx](https://kubernetes.github.io/ingress-nginx/examples/customization/external-auth-headers/)|[httpbin](https://httpbin.org) ([Basic](https://kubernetes.github.io/ingress-nginx/examples/auth/external-auth/), [OAuth](https://kubernetes.github.io/ingress-nginx/examples/auth/oauth-external-auth/))|[Basic](https://kubernetes.github.io/ingress-nginx/examples/auth/basic/), [Client Certificate](https://kubernetes.github.io/ingress-nginx/examples/auth/client-certs/)|
+|[Envoy](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_authz/v3/ext_authz.proto)|[External Authorization server (ext_authz filter)](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/ext_authz/v3/ext_authz.proto) |[JWT](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/jwt_authn/v3/config.proto)|
+|[Contour](https://projectcontour.io/docs/1.24/config/client-authorization/)|[Envoy](https://projectcontour.io/docs/1.24/config/client-authorization/)|[Envoy(JWT)](https://projectcontour.io/docs/1.24/config/jwt-verification/)|
+|[Istio](https://istio.io/latest/docs/tasks/security/authorization/authz-custom/)|[Envoy + istio (peer authN)](https://istio.io/latest/docs/concepts/security/#mutual-tls-authentication)|[JWT (Request authN)](https://istio.io/latest/docs/concepts/security/#authentication)|
+|[Envoy Gateway](https://gateway.envoyproxy.io/docs/tasks/security/ext-auth/)| [Envoy](https://gateway.envoyproxy.io/docs/tasks/security/ext-auth/#http-external-authorization-service) | [Envoy(JWT)](https://gateway.envoyproxy.io/docs/tasks/security/jwt-authentication/), [Basic](https://gateway.envoyproxy.io/docs/tasks/security/basic-auth/) |
+|[Consul](https://developer.hashicorp.com/consul/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s)|[Envoy](https://developer.hashicorp.com/consul/docs/connect/proxies/envoy-extensions/configuration/ext-authz)| [JWT](https://developer.hashicorp.com/consul/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-k8s#use-jwts-to-verify-requests-to-api-gateways-on-kubernetes)|
+
+
+
+## API
+
+(... details, can point to PR with changes)
+
+## Conformance Details
+
+(This section describes the names to be used for the feature or
+features in conformance tests and profiles.
+
+These should be `CamelCase` names that specify the feature as
+precisely as possible, and are particularly important for
+Extended features, since they may be surfaced to users.)
+
+## Alternatives
+
+(List other design alternatives and why we did not go in that
+direction)
+
+## References

geps/gep-1494/metadata.yaml

@@ -0,0 +1,19 @@
+apiVersion: internal.gateway.networking.k8s.io/v1alpha1
+kind: GEPDetails
+number: 1494
+name: HTTP Auth in Gateway API
+status: Provisional
+# Any authors who contribute to the GEP in any way should be listed here using
+# their Github handle.
+authors:
+  - youngnick
+  - jgao1025
+# references is a list of hyperlinks to relevant external references.
+# It's intended to be used for storing Github discussions, Google docs, etc.
+references: {}
+# featureNames is a list of the feature names introduced by the GEP, if there
+# are any. This will allow us to track which feature was introduced by which GEP.
+featureNames: {}
+# changelog is a list of hyperlinks to PRs that make changes to the GEP, in
+# ascending date order.
+changelog: {}