Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add initial draft of Auth GEP 1494 #3500

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add initial draft of Auth GEP 1494 #3500

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a9db0f1
Add initial draft of Auth GEP 1494
youngnick Dec 13, 2024
6706fbd
Fix first round of PR comments
youngnick Dec 17, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
144 changes: 144 additions & 0 deletions geps/gep-1494/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,144 @@
# 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. At the time of writing, this authentication is only for ingress traffic to the cluster.


## Goals

(Using the [Gateway API Personas](https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/))

* 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.
youngnick marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since we're saying this is exclusively for north-south traffic, I think I'd rather attach this config at the Gateway level. Maybe it would be safer to say something like this:

Suggested change
* A way for Chihiro the Cluster Admin to configure a default Authentication and/or Authorization config for some set of HTTPRoutes.
* A way for Chihiro the Cluster Admin to configure a default Authentication and/or Authorization config for some set of HTTP or GRPC matching criteria.


* 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this imply that Ana has the ability to override the cluster-admin configuration? I assume some use cases for this functionality might involve testing, but I’m curious to hear about other potential use cases. My concern is that an app developer, who may not have a strong understanding of authentication, would have the ability to override cluster-admin (or security admin) defaults.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this imply that Ana has the ability to override the cluster-admin configuration? I assume some use cases for this functionality might involve testing, but I’m curious to hear about other potential use cases. My concern is that an app developer, who may not have a strong understanding of authentication, would have the ability to override cluster-admin (or security admin) defaults.

I think some public pages, like a status page or help page, might not need authn?

It could be more flexible if the Gateway API allowed an HTTPRoute to either override or inherit settings from the Gateway under a hierarchical control model. This flexibility would be especially useful in cases where roles overlap, such as in smaller organizations where Ana and Chihiro might be the same person.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, the most likely use case here is for healthchecks, or being able to say "the whole website needs auth, except for /public" or something.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From my experience, cluster admins often lack a clear understanding of the deployed applications and their paths unless developers explicitly provide this information. In this context, the role of the cluster admin would be to enable default authentication globally for all routes. Developers, like Ana, can then override this default authentication at the httproute level or for specific routes within the httproute. WDYT?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, this is roughly what I'm thinking here. A default, not an override, although I'm not sure we'll be using Policy Attachment to do this or not yet.

Copy link

@JackMyers001 JackMyers001 Dec 17, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As I understand it, the current proposal only allows for "add auth to this website, except for this route". Could this be expanded to have some kind of rule-based authentication selection/bypass mechanism? I'd love to have the ability to choose a specific authentication mechanism (or bypass auth entirely) on a per-route basis, based on multiple factors (e.g. client IP, user agent).

This would make the Gateway API an amazing Layer 7 firewall, but I'm not sure if the project wants to support these kinds of capabilities; I saw this proposal was closed partly because the feature "operated too much like a WAF/firewall".

Proposed user stories:

  • As Ana the Application Developer, I'm maintaining a legacy application that doesn't have any existing authentication mechanisms. I wish to enforce SSO when a user accesses the application through a browser. However, I wish to bypass authentication when the user accesses the application through the mobile app (based on the user agent), as it can't handle the SSO flow.
  • As Ana the Application Developer, I wish to be able to use different authentication mechanisms for the same route based on the context of the request. I wish to use SSO when a user accesses my API through a browser, and use JWT when using my mobile app,
  • As Chihiro the Cluster Admin, I wish to block undesirable User Agents or IP ranges (spiders, scrapers etc.) from accessing any services exposed by Gateway API inside my cluster.
  • As Chihiro the Cluster Admin, I wish to be able to bypass AuthN when requests come in from a trusted, controlled IP range, so external services can access APIs running on my cluster without issue



## Non-Goals

* Handling all possible authentication and authorization schemes. Handling a (preferably large) subset of authentication and authorization is acceptable.


## Deferred Goals
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there any intend to also cover GRPCRoute?

I think it should be made clear if it's non-goal, or deferred.


* (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).
Copy link

@Ongy Ongy Dec 17, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While the "raw" passwords in basic auth have additional issues (long lived, impersonating human on login pages), JWT and afaik OAUTH/OIDC are not generally secure against "replay" attacks.

I.e. besides mTLS (which enforces confidentiality) all mechanisms are insecure in plaintext messages, because the authentication token can at least be re-used on other connections to gain the same level of privileges.

I think it's best to move the notion of requiring encryption for safe usage out of Basic Auth and potentially add a note here that basic auth has an additional issue with long-lived (potentially higher power) tokens being exchanged.


Basic auth is defined in [RFC-7617](https://datatracker.ietf.org/doc/html/rfc7617).

#### TLS Client Certificate Authentication
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

May be worth referring to https://gateway-api.sigs.k8s.io/geps/gep-91/ as this is already in progress.


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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the "also" is misplaced, since it's about the server also verifying a client, not about the client's cert being trusted by the same CA as ??.
The "trust chain" seems weird as well. Generally we have trust roots on a server, and the chain is presented by the client.
Since the client side authentication process of the server is implied prior knowledge, I think this can be condensed a bit.

I suggest:

In this case, the server also authenticates the client, based on the certificate chain presented by the client. 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).
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While not necessary, I think it's worth pointing to https://datatracker.ietf.org/doc/html/rfc8996 for why TLS 1.1 and earlier are not considered.


#### 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.
Copy link

@Ongy Ongy Dec 17, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This might leak into the "API" phase, but I think there's 2 levels to this, which are both worth an explicit mention

  • The API of the proposed implementation provides enough flexibility to integrate with an authorization mechanism and protect resources entirely in the gateway
  • The API allows to inject information about the authentication result into the requests and allows backend application to make authorization decisions based on this.

* 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!
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As Ana the Application Developer, I wish to be able to redirect users to a login page when they lack authentication, while unauthenticated API access gets the proper 40x response.

^ to make it clear that we need to handle "human" clients (browsers) slightly different to API consumers due to 30X/40X conventions.


## 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

(from https://github.com/kubernetes-sigs/gateway-api/blob/main/geps/gep-2162/index.md#standardize-features-and-conformance-tests-names)

#### Feature Names

Every feature should:

1. Start with the resource name. i.e HTTPRouteXXX
2. Follow the PascalCase convention. Note that the resource name in the string should come as is and not be converted to PascalCase, i.e HTTPRoutePortRedirect and not HttpRoutePortRedirect.
3. Not exceed 128 characters.
4. Contain only letters and numbers

### Conformance tests

Conformance tests file names should try to follow the the `pascal-case-name.go` format.
For example for `HTTPRoutePortRedirect` - the test file would be `httproute-port-redirect.go`.
Treat this guidance as "best effort" because we might have test files that check the combination of several features and can't follow the same format.
In any case, the conformance tests file names should be meaningful and easy to understand.

## Alternatives

(List other design alternatives and why we did not go in that
direction)

## References
19 changes: 19 additions & 0 deletions geps/gep-1494/metadata.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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: {}