Skip to content

Commit 25c3b55

Browse files
zhaohuabingguydc
zhaohuabing
authored and
guydc
committed
docs: how to specify a self-signed ca for the remote jwks host in the SP JWT settings. (envoyproxy#5085)
* docs for jwt self-signed ca Signed-off-by: Huabing Zhao <[email protected]> * fix gen Signed-off-by: Huabing Zhao <[email protected]> * update docs Signed-off-by: Huabing Zhao <[email protected]> --------- Signed-off-by: Huabing Zhao <[email protected]>
1 parent 13b9cdf commit 25c3b55

File tree

2 files changed

+153
-2
lines changed

2 files changed

+153
-2
lines changed

‎site/content/en/latest/tasks/security/jwt-authentication.md

+148-2
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ This task provides instructions for configuring [JSON Web Token (JWT)][jwt] auth
66
if an incoming request has a valid JWT before routing the request to a backend service. Currently, Envoy Gateway only
77
supports validating a JWT from an HTTP header, e.g. `Authorization: Bearer <token>`.
88

9-
Envoy Gateway introduces a new CRD called [SecurityPolicy][SecurityPolicy] that allows the user to configure JWT authentication.
9+
Envoy Gateway introduces a new CRD called [SecurityPolicy][SecurityPolicy] that allows the user to configure JWT authentication.
1010
This instantiated resource can be linked to a [Gateway][Gateway], [HTTPRoute][HTTPRoute] or [GRPCRoute][GRPCRoute] resource.
1111

1212
## Prerequisites
@@ -27,7 +27,7 @@ kubectl apply -f https://raw.githubusercontent.com/envoyproxy/gateway/latest/exa
2727
```
2828

2929
Two HTTPRoute has been created, one for `/foo` and another for `/bar`. A SecurityPolicy has been created and targeted
30-
HTTPRoute foo to authenticate requests for `/foo`. The HTTPRoute bar is not targeted by the SecurityPolicy and will allow
30+
HTTPRoute foo to authenticate requests for `/foo`. The HTTPRoute bar is not targeted by the SecurityPolicy and will allow
3131
unauthenticated requests to `/bar`.
3232

3333
Verify the HTTPRoute configuration and status:
@@ -148,6 +148,147 @@ You should see the below response
148148
}
149149
```
150150

151+
## Connect to a remote JWKS with Self-Signed Certificate
152+
153+
To connect to a remote JWKS with a self-signed certificate, you need to configure it using the [Backend] resource within the [SecurityPolicy]. Additionally, use the [BackendTLSPolicy] to specify the CA certificate required to authenticate the JWKS host.
154+
155+
The following example demonstrates how to configure the remote JWKS with a self-signed certificate.
156+
157+
{{< tabpane text=true >}}
158+
{{% tab header="Apply from stdin" %}}
159+
160+
```shell
161+
cat <<EOF | kubectl apply -f -
162+
apiVersion: gateway.envoyproxy.io/v1alpha1
163+
kind: SecurityPolicy
164+
metadata:
165+
name: jwt-example
166+
spec:
167+
targetRef:
168+
group: gateway.networking.k8s.io
169+
kind: HTTPRoute
170+
name: foo
171+
jwt:
172+
providers:
173+
- name: example
174+
remoteJWKS:
175+
backendRefs:
176+
- group: gateway.envoyproxy.io
177+
kind: Backend
178+
name: remote-jwks
179+
port: 443
180+
backendSettings:
181+
retry:
182+
numRetries: 3
183+
perRetry:
184+
backOff:
185+
baseInterval: 1s
186+
maxInterval: 5s
187+
retryOn:
188+
triggers: ["5xx", "gateway-error", "reset"]
189+
uri: https://foo.bar.com/jwks.json
190+
---
191+
apiVersion: gateway.envoyproxy.io/v1alpha1
192+
kind: Backend
193+
metadata:
194+
name: remote-jwks
195+
spec:
196+
endpoints:
197+
- fqdn:
198+
hostname: foo.bar.com
199+
port: 443
200+
---
201+
apiVersion: gateway.networking.k8s.io/v1alpha3
202+
kind: BackendTLSPolicy
203+
metadata:
204+
name: remote-jwks-btls
205+
spec:
206+
targetRefs:
207+
- group: gateway.envoyproxy.io
208+
kind: Backend
209+
name: remote-jwks
210+
sectionName: "443"
211+
validation:
212+
caCertificateRefs:
213+
- name: remote-jwks-server-ca
214+
group: ""
215+
kind: ConfigMap
216+
hostname: foo.bar.com
217+
EOF
218+
```
219+
220+
{{% /tab %}}
221+
{{% tab header="Apply from file" %}}
222+
Save and apply the following resource to your cluster:
223+
224+
```yaml
225+
---
226+
apiVersion: gateway.envoyproxy.io/v1alpha1
227+
kind: SecurityPolicy
228+
metadata:
229+
name: jwt-example
230+
spec:
231+
targetRef:
232+
group: gateway.networking.k8s.io
233+
kind: HTTPRoute
234+
name: foo
235+
jwt:
236+
providers:
237+
- name: example
238+
remoteJWKS:
239+
backendRefs:
240+
- group: gateway.envoyproxy.io
241+
kind: Backend
242+
name: remote-jwks
243+
port: 443
244+
backendSettings:
245+
retry:
246+
numRetries: 3
247+
perRetry:
248+
backOff:
249+
baseInterval: 1s
250+
maxInterval: 5s
251+
retryOn:
252+
triggers: ["5xx", "gateway-error", "reset"]
253+
uri: https://foo.bar.com/jwks.json
254+
---
255+
apiVersion: gateway.envoyproxy.io/v1alpha1
256+
kind: Backend
257+
metadata:
258+
name: remote-jwks
259+
spec:
260+
endpoints:
261+
- fqdn:
262+
hostname: foo.bar.com
263+
port: 443
264+
---
265+
apiVersion: gateway.networking.k8s.io/v1alpha3
266+
kind: BackendTLSPolicy
267+
metadata:
268+
name: remote-jwks-btls
269+
spec:
270+
targetRefs:
271+
- group: gateway.envoyproxy.io
272+
kind: Backend
273+
name: remote-jwks
274+
sectionName: "443"
275+
validation:
276+
caCertificateRefs:
277+
- name: remote-jwks-server-ca
278+
group: ""
279+
kind: ConfigMap
280+
hostname: foo.bar.com
281+
```
282+
283+
{{% /tab %}}
284+
{{< /tabpane >}}
285+
286+
As shown in the example above, the [SecurityPolicy] resource is configured with a remote JWKS within its JWT settings. The `backendRefs` field references the [Backend] resource that defines the JWKS host. The [BackendTLSPolicy] resource specifies the CA certificate required to authenticate the JWKS host.
287+
288+
Additional connection settings for the remote JWKS host can be configured in the [backendSettings]. Currently, only the retry policy is supported.
289+
290+
For more information about [Backend] and [BackendTLSPolicy], refer to the [Backend Routing][backend-routing] and [Backend TLS: Gateway to Backend][backend-tls] tasks.
291+
151292
## Clean-Up
152293

153294
Follow the steps from the [Quickstart](../../quickstart) to uninstall Envoy Gateway and the example manifest.
@@ -168,3 +309,8 @@ Checkout the [Developer Guide](../../../contributions/develop) to get involved i
168309
[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway
169310
[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute
170311
[GRPCRoute]: https://gateway-api.sigs.k8s.io/api-types/grpcroute
312+
[Backend]: ../../../api/extension_types#backend
313+
[BackendTLSPolicy]: https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/
314+
[backend-routing]: ../traffic/backend
315+
[backend-tls]: ../backend-tls
316+
[BackendSettings]: ../../../api/extension_types/#clustersettings

‎site/content/en/latest/tasks/security/oidc.md

+5
Original file line numberDiff line numberDiff line change
@@ -537,6 +537,10 @@ spec:
537537
{{% /tab %}}
538538
{{< /tabpane >}}
539539
540+
As shown in the example above, the [SecurityPolicy] resource is configured with an OIDC provider in its OIDC settings. The `backendRefs` field references the [Backend] resource that defines the OIDC provider. The [BackendTLSPolicy] resource specifies the CA certificate required to authenticate the OIDC provider.
541+
542+
Additional connection settings for the OIDC provider can be configured in the [backendSettings]. Currently, only the retry policy is supported.
543+
540544
For more information about [Backend] and [BackendTLSPolicy], refer to the [Backend Routing][backend-routing] and [Backend TLS: Gateway to Backend][backend-tls] tasks.
541545

542546
## Clean-Up
@@ -565,3 +569,4 @@ Checkout the [Developer Guide](../../../../contributions/develop) to get involve
565569
[BackendTLSPolicy]: https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/
566570
[backend-routing]: ../traffic/backend
567571
[backend-tls]: ../backend-tls
572+
[BackendSettings]: ../../../api/extension_types/#clustersettings

0 commit comments

Comments
 (0)