You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/proposals/external-auth-filter.md
+1-132Lines changed: 1 addition & 132 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -20,135 +20,4 @@ This proposal aim to provider users of the Gateway API with a native form of Aut
20
20
21
21
## Non-Goals
22
22
23
-
- Support for [GRPCAuthConfig](https://gateway-api.sigs.k8s.io/reference/spec/#grpcauthconfig)
24
-
25
-
## Introduction
26
-
27
-
This document focus on an approach to have NGF integate with the HTTPExternalAuthFilter in the Gateway API.
28
-
This filter defines a mean to communicate with an external authentication services that can be responsible for both Authenticaiton and Authroization of requests to a backend application.
29
-
30
-
> ⚠️ This filter is currently part of the Gateway API experimental channel. The API is subject to changes that may break implementations.
31
-
32
-
## API, Customer Driven Interfaces, and User Experience
33
-
34
-
### API
35
-
36
-
Below is an example of an HTTPRoute with one path configured to route request to an external auth service named `ext-authz-svc`
37
-
This service exposes the `/auth` endpoint which is responsible for authentication of any request to `/api`
38
-
The protocol field is set to `HTTP`. This defines the `ExternalAuth` filter as a [HTTPAuthConfig](https://gateway-api.sigs.k8s.io/reference/spec/#httpauthconfig)
39
-
40
-
This filter will send authentication requests to an the ExternalAuth service. This service may be an IdP such as Keycloak. This may also be or our own [NGINX External Auth Service](https://github.com/nginx/nginx-external-auth-service) deployable as a Helm chart.
41
-
42
-
```yaml
43
-
apiVersion: gateway.networking.k8s.io/v1
44
-
kind: HTTPRoute
45
-
metadata:
46
-
name: api-with-external-auth
47
-
namespace: default
48
-
spec:
49
-
parentRefs:
50
-
- name: gateway
51
-
hostnames:
52
-
- api.example.com
53
-
rules:
54
-
- matches:
55
-
- path:
56
-
type: PathPrefix
57
-
value: /api
58
-
filters:
59
-
- type: ExternalAuth
60
-
externalAuth:
61
-
protocol: HTTP
62
-
backendRef:
63
-
# BackendObjectReference: defaults to core group and kind=Service if omitted
64
-
name: ext-authz-svc
65
-
port: 8080
66
-
http:
67
-
# Prepend a prefix when forwarding the client path to the auth server
68
-
path: /auth
69
-
# Additional request headers to send to the auth server (core headers are always sent)
70
-
allowedHeaders:
71
-
- X-Request-Id
72
-
- X-User-Agent
73
-
- X-Correlation-Id
74
-
# Headers from the auth server response to copy into the backend request
75
-
allowedResponseHeaders:
76
-
- X-Authz-Trace
77
-
- WWW-Authenticate
78
-
- Set-Cookie
79
-
forwardBody:
80
-
# Buffer and forward up to 16 KiB of the client request body to the auth server
81
-
maxSize: 16384
82
-
backendRefs:
83
-
- name: backend-svc
84
-
port: 80
85
-
```
86
-
87
-
### Configuration flow
88
-
89
-
Configuration flow with one HTTPRoute with a single path rule referencing an externalAuth service. In this case the NGINX Auth Service. This service could be Keycloak and any other IdP.
- As a Cluter Administrator, I want to define specific authentication configurations for each application within the cluster so that each application developer can select the appropriate auth menchanisim for their endpoints.
96
-
- As an Application Developer, I want to secure access to my APIs and Backend Applications.
97
-
- As an Application Developer, I want to enforce authenticaiton on specific routes and matches.
| **HTTP Basic Authentication** | ✅ | ✅ | [ngx_http_auth_basic](https://nginx.org/en/docs/http/ngx_http_auth_basic_module.html) | Requires a username and password sent in an HTTP header. |
104
-
| **JWT (JSON Web Token)** | ❌ | ✅ | [ngx_http_auth_jwt_module](https://docs.nginx.com/nginx/admin-guide/security-controls/authentication/#jwt-authentication) | Tokens are used for stateless authentication between client and server. |
105
-
| **OpenID Connect** | ❌ | ✅ | [ngx_http_oidc_module](https://nginx.org/en/docs/http/ngx_http_oidc_module.html)| Allows authentication through third-party providers like Google. |
106
-
107
-
## Testing
108
-
109
-
- Unit tests
110
-
- Functional tests to validate behaviour of the external auth service.
111
-
- In cases where users choose to deploy and manage our NGINX Auth Service, we will want to ensure any configurations applied to NGINX are robust and secure.
112
-
- In cases where users choose to reference a seperate IdP such as Keycloak, we will want to ensure NGF responds accordingly to the appropriate response code returned. This will also be the case for responses returned from the NGINX Auth Service.
113
-
114
-
## Security Considerations
115
-
116
-
It's important we consider a means to secure connect from NGF to the ExternalAuth service.
117
-
A user may choose to deploy a `BackendTLSPolicy` configured with SNI/CA trust.
118
-
119
-
```yaml
120
-
apiVersion: gateway.networking.k8s.io/v1
121
-
kind: BackendTLSPolicy
122
-
metadata:
123
-
name: auth-backend-tls
124
-
namespace: security
125
-
spec:
126
-
targetRefs:
127
-
- group: ""
128
-
kind: Service
129
-
name: ext-authz-svc
130
-
validation:
131
-
caCertificateRefs:
132
-
- kind: ConfigMap
133
-
name: auth-ca
134
-
hostname: auth.internal.example
135
-
```
136
-
137
-
### Validation
138
-
139
-
As this approach also includes the option to provide users with an NGINX Auth Service to deploy and manage, it is important that all configuration fields are validated for that deployment option, and that configurations applied to NGINX are robust and secure.
140
-
141
-
## Alternatives
142
-
143
-
The [Authentication Filter](docs/proposals/authentication-filter.md) document proposes to develop our own `AuthenticationFilter` CRD to expose the various auth capabilies through NGINX. Please refer to that proposal for details on how that approach may be implemented.
0 commit comments