Skip to content

Commit 947359c

Browse files
danehansdanehans
committed
Removes API Group and Renames API to AuthenticationFilter
Signed-off-by: danehans <[email protected]>
1 parent 8c2fde2 commit 947359c

File tree

1 file changed

+68
-62
lines changed

1 file changed

+68
-62
lines changed

‎docs/latest/design/request-authentication.md‎

Lines changed: 68 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@
44

55
[Issue 336][] specifies the need for exposing a user-facing API to configure request authentication. Request
66
authentication is defined as an authentication mechanism to be enforced by Envoy on a per-request basis. A connection
7-
will be rejected if it contains invalid authentication information, based on the `Authentication` API type proposed in
8-
this design document.
7+
will be rejected if it contains invalid authentication information, based on the `AuthenticationFilter` API type
8+
proposed in this design document.
99

1010
Envoy Gateway leverages [Gateway API][] for configuring managed Envoy proxies. Gateway API defines core, extended, and
1111
implementation-specific API [support levels][] for implementors such as Envoy Gateway to expose features. Since
@@ -37,11 +37,6 @@ As a Service Producer, I need the ability to:
3737
* Have different authentication mechanisms per route rule.
3838
* Choose from different authentication mechanisms supported by Envoy, e.g. OIDC.
3939

40-
### Security API Group
41-
42-
A new API group, `security.gateway.envoyproxy.io` is introduced to group security-related APIs. This will allow security
43-
APIs to be versioned, changed, etc. over time.
44-
4540
### Authentication API Type
4641

4742
The Authentication API type defines authentication configuration for authenticating requests through managed Envoy
@@ -55,51 +50,50 @@ import (
5550

5651
)
5752

58-
type Authentication struct {
53+
type AuthenticationFilter struct {
5954
metav1.TypeMeta
6055
metav1.ObjectMeta
6156

6257
// Spec defines the desired state of the Authentication type.
63-
Spec AuthenticationSpec
58+
Spec AuthenticationFilterSpec
6459

6560
// Note: The status sub-resource has been excluded but may be added in the future.
6661
}
6762

68-
// AuthenticationSpec defines the desired state of the Authentication type.
63+
// AuthenticationFilterSpec defines the desired state of the AuthenticationFilter type.
6964
// +union
70-
type AuthenticationSpec struct {
71-
// Type defines the type of authentication provider to use. Supported provider
72-
// types are:
65+
type AuthenticationFilterSpec struct {
66+
// Type defines the type of authentication provider to use. Supported provider types are:
7367
//
7468
// * JWT: A provider that uses JSON Web Token (JWT) for authenticating requests.
7569
//
7670
// +unionDiscriminator
77-
Type AuthenticationType
71+
Type AuthenticationFilterType
7872

7973
// JWT defines the JSON Web Token (JWT) authentication provider type. When multiple
8074
// jwtProviders are specified, the JWT is considered valid if any of the providers
8175
// successfully validate the JWT.
82-
JwtProviders []JwtAuthenticationProvider
76+
JwtProviders []JwtAuthenticationFilterProvider
8377
}
8478

8579
...
8680
```
8781

88-
Refer to [PR 773][] for the detailed Authentication API spec.
82+
Refer to [PR 773][] for the detailed AuthenticationFilter API spec.
8983

90-
The status subresource is not included in the Authentication API. Status will be surfaced by an HTTPRoute that
91-
references an Authentication. For example, an HTTPRoute will surface the `ResolvedRefs=False` status condition if it
92-
references an Authentication that does not exist. It may be beneficial to add Authentication status fields in the future
84+
The status subresource is not included in the AuthenticationFilter API. Status will be surfaced by an HTTPRoute that
85+
references an AuthenticationFilter. For example, an HTTPRoute will surface the `ResolvedRefs=False` status condition if it
86+
references an AuthenticationFilter that does not exist. It may be beneficial to add AuthenticationFilter status fields in the future
9387
based on defined use-cases. For example, a remote JWKS can be validated based on the specified URI and have an
9488
appropriate status condition surfaced.
9589

96-
#### Authentication Example
90+
#### AuthenticationFilter Example
9791

98-
The following is an Authentication example with one JWT authentication provider:
92+
The following is an AuthenticationFilter example with one JWT authentication provider:
9993

10094
```yaml
101-
apiVersion: security.gateway.envoyproxy.io/v1alpha1
102-
kind: Authentication
95+
apiVersion: gateway.envoyproxy.io/v1alpha1
96+
kind: AuthenticationFilter
10397
metadata:
10498
name: example
10599
spec:
@@ -137,8 +131,8 @@ spec:
137131
filters:
138132
- type: ExtensionRef
139133
extensionRef:
140-
group: security.gateway.envoyproxy.io
141-
kind: Authentication
134+
group: gateway.envoyproxy.io
135+
kind: AuthenticationFilter
142136
name: example
143137
backendRefs:
144138
- name: backend
@@ -151,12 +145,12 @@ backend service named "backend".
151145
## Implementation Details
152146

153147
The JWT authentication type is translated to an Envoy [JWT authentication filter][] and a cluster is created for each
154-
remote JWKS. The following examples provide additional details on how Gateway API and Authentication resources are
148+
remote JWKS. The following examples provide additional details on how Gateway API and AuthenticationFilter resources are
155149
translated into Envoy configuration.
156150

157151
### Example 1: One Route with One JWT Provider
158152

159-
The following cluster is created from the above HTTPRoute and Authentication:
153+
The following cluster is created from the above HTTPRoute and AuthenticationFilter:
160154

161155
```yaml
162156
dynamic_clusters:
@@ -202,16 +196,16 @@ dynamic_resources:
202196
"@type": type.googleapis.com/envoy.config.filter.http.jwt_authn.v2alpha.JwtAuthentication
203197
```
204198

205-
This JWT authentication filter contains two fields:
199+
This JWT authentication HTTP filter contains two fields:
206200
* The `providers` field specifies how a JWT should be verified, such as where to extract the token, where to fetch the
207201
public key (JWKS) and where to output its payload. This field is built from the source resource `namespace-name`, and
208-
the JWT provider name of an Authentication.
202+
the JWT provider name of an AuthenticationFilter.
209203
* The `rules` field specifies matching rules and their requirements. If a request matches a rule, its requirement
210204
applies. The requirement specifies which JWT providers should be used. This field is built from a HTTPRoute
211-
`matches` rule that references the Authentication extended filter. When a referenced Authentication specifies
212-
multiple `jwtProviders`, the JWT is considered valid if __any__ of the providers successfully validate the JWT.
205+
`matches` rule that references the AuthenticationFilter. When a referenced Authentication specifies multiple
206+
`jwtProviders`, the JWT is considered valid if __any__ of the providers successfully validate the JWT.
213207

214-
The following JWT Authentication filter `providers` configuration is created from the above Authentication.
208+
The following JWT authentication HTTP filter `providers` configuration is created from the above AuthenticationFilter.
215209

216210
```yaml
217211
providers:
@@ -226,7 +220,7 @@ providers:
226220
timeout: 1s
227221
```
228222

229-
The following JWT Authentication filter `rules` configuration is created from the above HTTPRoute.
223+
The following JWT authentication HTTP filter `rules` configuration is created from the above HTTPRoute.
230224

231225
```yaml
232226
rules:
@@ -236,16 +230,16 @@ rules:
236230
provider_name: default-example-example
237231
```
238232

239-
### Example 2: Two HTTPRoutes with Different Authentications
233+
### Example 2: Two HTTPRoutes with Different AuthenticationFilters
240234

241235
The following example contains:
242236
* Two HTTPRoutes with different hostnames.
243-
* Each HTTPRoute references a different Authentication
244-
* Each Authentication contains a different JWT provider.
237+
* Each HTTPRoute references a different AuthenticationFilter.
238+
* Each AuthenticationFilter contains a different JWT provider.
245239

246240
```yaml
247-
apiVersion: security.gateway.envoyproxy.io/v1alpha1
248-
kind: Authentication
241+
apiVersion: gateway.envoyproxy.io/v1alpha1
242+
kind: AuthenticationFilter
249243
metadata:
250244
name: example1
251245
spec:
@@ -258,8 +252,8 @@ spec:
258252
remoteJwks:
259253
uri: https://foo.com/jwt/public-key/jwks.json
260254
---
261-
apiVersion: security.gateway.envoyproxy.io/v1alpha1
262-
kind: Authentication
255+
apiVersion: gateway.envoyproxy.io/v1alpha1
256+
kind: AuthenticationFilter
263257
metadata:
264258
name: example2
265259
spec:
@@ -291,8 +285,8 @@ spec:
291285
filters:
292286
- type: ExtensionRef
293287
extensionRef:
294-
group: security.gateway.envoyproxy.io
295-
kind: Authentication
288+
group: gateway.envoyproxy.io
289+
kind: AuthenticationFilter
296290
name: example1
297291
backendRefs:
298292
- name: backend
@@ -317,8 +311,8 @@ spec:
317311
filters:
318312
- type: ExtensionRef
319313
extensionRef:
320-
group: security.gateway.envoyproxy.io
321-
kind: Authentication
314+
group: gateway.envoyproxy.io
315+
kind: AuthenticationFilter
322316
name: example2
323317
backendRefs:
324318
- name: backend2
@@ -435,40 +429,39 @@ __Note:__ The JWT provider cluster and route is omitted from the above example f
435429

436430
### Implementation Outline
437431

438-
* Create a `security` API group and add the Authentication API type to this group.
439-
* Update the Kubernetes provider to get/watch Authentication resources that are referenced by managed HTTPRoutes. Add
440-
the referenced Authentication object to the resource map and publish it.
441-
* Update the resource translator to include the Authentication API in HTTPRoute processing.
442-
* Update the xDS translator to translate an Authentication into xDS resources. The translator should perform the
432+
* Update the Kubernetes provider to get/watch AuthenticationFilter resources that are referenced by managed HTTPRoutes.
433+
Add the referenced AuthenticationFilter object to the resource map and publish it.
434+
* Update the resource translator to include the AuthenticationFilter API in HTTPRoute processing.
435+
* Update the xDS translator to translate an AuthenticationFilter into xDS resources. The translator should perform the
443436
following:
444437
* Convert a list of JWT rules from the xds IR into an Envoy JWT filter config.
445-
* Create a JWT authentication filter.
438+
* Create a JWT authentication HTTP filter.
446439
* Build the HTTP Connection Manager (HCM) HTTP filters.
447440
* Build the HCM.
448441
* When building the Listener, create an HCM for each filter-chain.
449442

450-
## Adding Authentication Provider Types
443+
## Adding Authentication Types
451444

452-
Additional authentication provider types can be added in the future through the `ProviderType` API. For example, to add
453-
the `Foo` authentication provider type:
445+
Additional authentication types can be added in the future through the `AuthenticationFilterType` API. For
446+
example, to add the `Foo` authentication type:
454447

455-
Define the `FooProvider` type:
448+
Define the `Foo` authentication provider:
456449

457450
```go
458451
package v1alpha1
459452
460-
// FooProvider defines the "Foo" authentication provider type.
461-
type FooProvider struct {
462-
// TODO: Define fields of the Foo authentication provider type.
453+
// FooAuthenticationFilterProvider defines the "Foo" authentication filter provider type.
454+
type FooAuthenticationFilterProvider struct {
455+
// TODO: Define fields of the Foo authentication filter provider type.
463456
}
464457
```
465458

466-
Add the `FooProvider` type to `AuthenticationSpec`:
459+
Add the `FooAuthenticationFilterProvider` type to `AuthenticationFilterSpec`:
467460

468461
```go
469462
package v1alpha1
470463
471-
type AuthenticationSpec struct {
464+
type AuthenticationFilterSpec struct {
472465
...
473466
474467
// Foo defines the Foo authentication type. For additional
@@ -477,17 +470,30 @@ type AuthenticationSpec struct {
477470
// <INSERT_LINK>
478471
//
479472
// +optional
480-
Foo *FooAuthentication `json:"foo"`
473+
Foo *FooAuthenticationFilterProvider
481474
}
482475
```
483476

484-
Authentication should support additional authentication types in the future, for example:
477+
Lastly, add the type to the `AuthenticationType` enum:
478+
479+
```go
480+
// AuthenticationType is a type of authentication provider.
481+
// +kubebuilder:validation:Enum=JWT,FOO
482+
type AuthenticationFilterType string
483+
484+
const (
485+
// JwtAuthenticationProviderType is the JWT authentication provider type.
486+
FooAuthenticationFilterProviderType AuthenticationFilterType = "FOO"
487+
)
488+
```
489+
490+
The AuthenticationFilter API should support additional authentication types in the future, for example:
485491
- OAuth2
486492
- OIDC
487493

488494
## Outstanding Questions
489495

490-
- If Envoy Gateway owns the Authentication API, is an xDS IR equivalent needed?
496+
- If Envoy Gateway owns the AuthenticationFilter API, is an xDS IR equivalent needed?
491497
- Should local JWKS be implemented before remote JWKS?
492498
- How should Envoy obtain the trusted CA for a remote JWKS?
493499
- Should HTTPS be the only supported scheme for remote JWKS?

0 commit comments

Comments
 (0)