Skip to content

Commit ca2d80b

Browse files
zhaohuabingzhaohuabing
authored
docs: how to connect to an OIDC provider with a self-signed cert (envoyproxy#4889)
update oidc docs Signed-off-by: Huabing Zhao <[email protected]>
1 parent 4cba2e2 commit ca2d80b

File tree

3 files changed

+456
-3
lines changed

3 files changed

+456
-3
lines changed

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

Lines changed: 152 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -392,6 +392,153 @@ You can also try to access `https://foo.example.com:8443` and `https://www.examp
392392
be able to see the response from the backend service since these HTTPRoutes are also protected by the same OIDC config,
393393
and the cookies are shared across subdomains.
394394

395+
## Connect to an OIDC Provider with Self-Signed Certificate
396+
397+
In some scenarios, the OIDC provider may use a self-signed certificate. To connect to an OIDC provider 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 OIDC provider.
398+
399+
The following example demonstrates how to configure the OIDC provider with a self-signed certificate.
400+
401+
{{< tabpane text=true >}}
402+
{{% tab header="Apply from stdin" %}}
403+
404+
```shell
405+
cat <<EOF | kubectl apply -f -
406+
apiVersion: gateway.envoyproxy.io/v1alpha1
407+
kind: SecurityPolicy
408+
metadata:
409+
name: oidc-example
410+
spec:
411+
targetRefs:
412+
- group: gateway.networking.k8s.io
413+
kind: HTTPRoute
414+
name: myapp
415+
oidc:
416+
provider:
417+
backendRefs:
418+
- group: gateway.envoyproxy.io
419+
kind: Backend
420+
name: backend-keycloak
421+
port: 443
422+
backendSettings:
423+
retry:
424+
numRetries: 3
425+
perRetry:
426+
backOff:
427+
baseInterval: 1s
428+
maxInterval: 5s
429+
retryOn:
430+
triggers: ["5xx", "gateway-error", "reset"]
431+
issuer: "https://my.keycloak.com/realms/master"
432+
authorizationEndpoint: "https://my.keycloak.com/realms/master/protocol/openid-connect/auth"
433+
tokenEndpoint: "https://my.keycloak.com/realms/master/protocol/openid-connect/token"
434+
clientID: "${CLIENT_ID}"
435+
clientSecret:
436+
name: "my-app-client-secret"
437+
redirectURL: "http://www.example.com/myapp/oauth2/callback"
438+
logoutPath: "/myapp/logout"
439+
---
440+
apiVersion: gateway.envoyproxy.io/v1alpha1
441+
kind: Backend
442+
metadata:
443+
name: backend-keycloak
444+
spec:
445+
endpoints:
446+
- fqdn:
447+
hostname: 'my.keycloak.com'
448+
port: 443
449+
---
450+
apiVersion: gateway.networking.k8s.io/v1alpha3
451+
kind: BackendTLSPolicy
452+
metadata:
453+
name: policy-btls
454+
spec:
455+
targetRefs:
456+
- group: gateway.envoyproxy.io
457+
kind: Backend
458+
name: backend-keycloak
459+
sectionName: "443"
460+
validation:
461+
caCertificateRefs:
462+
- name: backend-tls-certificate
463+
group: ""
464+
kind: ConfigMap
465+
hostname: my.keycloak.com
466+
EOF
467+
```
468+
469+
{{% /tab %}}
470+
{{% tab header="Apply from file" %}}
471+
Save and apply the following resource to your cluster:
472+
473+
```yaml
474+
---
475+
apiVersion: gateway.envoyproxy.io/v1alpha1
476+
kind: SecurityPolicy
477+
metadata:
478+
name: oidc-example
479+
spec:
480+
targetRefs:
481+
- group: gateway.networking.k8s.io
482+
kind: HTTPRoute
483+
name: myapp
484+
oidc:
485+
provider:
486+
backendRefs:
487+
- group: gateway.envoyproxy.io
488+
kind: Backend
489+
name: backend-keycloak
490+
port: 443
491+
backendSettings:
492+
retry:
493+
numRetries: 3
494+
perRetry:
495+
backOff:
496+
baseInterval: 1s
497+
maxInterval: 5s
498+
retryOn:
499+
triggers: ["5xx", "gateway-error", "reset"]
500+
issuer: "https://my.keycloak.com/realms/master"
501+
authorizationEndpoint: "https://my.keycloak.com/realms/master/protocol/openid-connect/auth"
502+
tokenEndpoint: "https://my.keycloak.com/realms/master/protocol/openid-connect/token"
503+
clientID: "${CLIENT_ID}"
504+
clientSecret:
505+
name: "my-app-client-secret"
506+
redirectURL: "http://www.example.com/myapp/oauth2/callback"
507+
logoutPath: "/myapp/logout"
508+
---
509+
apiVersion: gateway.envoyproxy.io/v1alpha1
510+
kind: Backend
511+
metadata:
512+
name: backend-keycloak
513+
spec:
514+
endpoints:
515+
- fqdn:
516+
hostname: 'my.keycloak.com'
517+
port: 443
518+
---
519+
apiVersion: gateway.networking.k8s.io/v1alpha3
520+
kind: BackendTLSPolicy
521+
metadata:
522+
name: policy-btls
523+
spec:
524+
targetRefs:
525+
- group: gateway.envoyproxy.io
526+
kind: Backend
527+
name: backend-keycloak
528+
sectionName: "443"
529+
validation:
530+
caCertificateRefs:
531+
- name: backend-tls-certificate
532+
group: ""
533+
kind: ConfigMap
534+
hostname: my.keycloak.com
535+
```
536+
537+
{{% /tab %}}
538+
{{< /tabpane >}}
539+
540+
For more information about [Backend] and [BackendTLSPolicy], refer to the [Backend Routing][backend-routing] and [Backend TLS: Gateway to Backend][backend-tls] tasks.
541+
395542
## Clean-Up
396543
397544
Follow the steps from the [Quickstart](../../quickstart) to uninstall Envoy Gateway and the example manifest.
@@ -411,6 +558,10 @@ Checkout the [Developer Guide](../../../../contributions/develop) to get involve
411558

412559
[oidc]: https://openid.net/connect/
413560
[google-oidc]: https://developers.google.com/identity/protocols/oauth2/openid-connect
414-
[SecurityPolicy]: ../../../../contributions/design/security-policy
561+
[SecurityPolicy]: ../../../api/extension_types#securitypolicy
415562
[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway
416563
[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute
564+
[Backend]: ../../../api/extension_types#backend
565+
[BackendTLSPolicy]: https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/
566+
[backend-routing]: ../traffic/backend
567+
[backend-tls]: ../backend-tls

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

Lines changed: 152 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -392,6 +392,153 @@ You can also try to access `https://foo.example.com:8443` and `https://www.examp
392392
be able to see the response from the backend service since these HTTPRoutes are also protected by the same OIDC config,
393393
and the cookies are shared across subdomains.
394394

395+
## Connect to an OIDC Provider with Self-Signed Certificate
396+
397+
In some scenarios, the OIDC provider may use a self-signed certificate. To connect to an OIDC provider 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 OIDC provider.
398+
399+
The following example demonstrates how to configure the OIDC provider with a self-signed certificate.
400+
401+
{{< tabpane text=true >}}
402+
{{% tab header="Apply from stdin" %}}
403+
404+
```shell
405+
cat <<EOF | kubectl apply -f -
406+
apiVersion: gateway.envoyproxy.io/v1alpha1
407+
kind: SecurityPolicy
408+
metadata:
409+
name: oidc-example
410+
spec:
411+
targetRefs:
412+
- group: gateway.networking.k8s.io
413+
kind: HTTPRoute
414+
name: myapp
415+
oidc:
416+
provider:
417+
backendRefs:
418+
- group: gateway.envoyproxy.io
419+
kind: Backend
420+
name: backend-keycloak
421+
port: 443
422+
backendSettings:
423+
retry:
424+
numRetries: 3
425+
perRetry:
426+
backOff:
427+
baseInterval: 1s
428+
maxInterval: 5s
429+
retryOn:
430+
triggers: ["5xx", "gateway-error", "reset"]
431+
issuer: "https://my.keycloak.com/realms/master"
432+
authorizationEndpoint: "https://my.keycloak.com/realms/master/protocol/openid-connect/auth"
433+
tokenEndpoint: "https://my.keycloak.com/realms/master/protocol/openid-connect/token"
434+
clientID: "${CLIENT_ID}"
435+
clientSecret:
436+
name: "my-app-client-secret"
437+
redirectURL: "http://www.example.com/myapp/oauth2/callback"
438+
logoutPath: "/myapp/logout"
439+
---
440+
apiVersion: gateway.envoyproxy.io/v1alpha1
441+
kind: Backend
442+
metadata:
443+
name: backend-keycloak
444+
spec:
445+
endpoints:
446+
- fqdn:
447+
hostname: 'my.keycloak.com'
448+
port: 443
449+
---
450+
apiVersion: gateway.networking.k8s.io/v1alpha3
451+
kind: BackendTLSPolicy
452+
metadata:
453+
name: policy-btls
454+
spec:
455+
targetRefs:
456+
- group: gateway.envoyproxy.io
457+
kind: Backend
458+
name: backend-keycloak
459+
sectionName: "443"
460+
validation:
461+
caCertificateRefs:
462+
- name: backend-tls-certificate
463+
group: ""
464+
kind: ConfigMap
465+
hostname: my.keycloak.com
466+
EOF
467+
```
468+
469+
{{% /tab %}}
470+
{{% tab header="Apply from file" %}}
471+
Save and apply the following resource to your cluster:
472+
473+
```yaml
474+
---
475+
apiVersion: gateway.envoyproxy.io/v1alpha1
476+
kind: SecurityPolicy
477+
metadata:
478+
name: oidc-example
479+
spec:
480+
targetRefs:
481+
- group: gateway.networking.k8s.io
482+
kind: HTTPRoute
483+
name: myapp
484+
oidc:
485+
provider:
486+
backendRefs:
487+
- group: gateway.envoyproxy.io
488+
kind: Backend
489+
name: backend-keycloak
490+
port: 443
491+
backendSettings:
492+
retry:
493+
numRetries: 3
494+
perRetry:
495+
backOff:
496+
baseInterval: 1s
497+
maxInterval: 5s
498+
retryOn:
499+
triggers: ["5xx", "gateway-error", "reset"]
500+
issuer: "https://my.keycloak.com/realms/master"
501+
authorizationEndpoint: "https://my.keycloak.com/realms/master/protocol/openid-connect/auth"
502+
tokenEndpoint: "https://my.keycloak.com/realms/master/protocol/openid-connect/token"
503+
clientID: "${CLIENT_ID}"
504+
clientSecret:
505+
name: "my-app-client-secret"
506+
redirectURL: "http://www.example.com/myapp/oauth2/callback"
507+
logoutPath: "/myapp/logout"
508+
---
509+
apiVersion: gateway.envoyproxy.io/v1alpha1
510+
kind: Backend
511+
metadata:
512+
name: backend-keycloak
513+
spec:
514+
endpoints:
515+
- fqdn:
516+
hostname: 'my.keycloak.com'
517+
port: 443
518+
---
519+
apiVersion: gateway.networking.k8s.io/v1alpha3
520+
kind: BackendTLSPolicy
521+
metadata:
522+
name: policy-btls
523+
spec:
524+
targetRefs:
525+
- group: gateway.envoyproxy.io
526+
kind: Backend
527+
name: backend-keycloak
528+
sectionName: "443"
529+
validation:
530+
caCertificateRefs:
531+
- name: backend-tls-certificate
532+
group: ""
533+
kind: ConfigMap
534+
hostname: my.keycloak.com
535+
```
536+
537+
{{% /tab %}}
538+
{{< /tabpane >}}
539+
540+
For more information about [Backend] and [BackendTLSPolicy], refer to the [Backend Routing][backend-routing] and [Backend TLS: Gateway to Backend][backend-tls] tasks.
541+
395542
## Clean-Up
396543
397544
Follow the steps from the [Quickstart](../../quickstart) to uninstall Envoy Gateway and the example manifest.
@@ -411,6 +558,10 @@ Checkout the [Developer Guide](../../../../contributions/develop) to get involve
411558

412559
[oidc]: https://openid.net/connect/
413560
[google-oidc]: https://developers.google.com/identity/protocols/oauth2/openid-connect
414-
[SecurityPolicy]: ../../../../contributions/design/security-policy
561+
[SecurityPolicy]: ../../../api/extension_types#securitypolicy
415562
[Gateway]: https://gateway-api.sigs.k8s.io/api-types/gateway
416563
[HTTPRoute]: https://gateway-api.sigs.k8s.io/api-types/httproute
564+
[Backend]: ../../../api/extension_types#backend
565+
[BackendTLSPolicy]: https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/
566+
[backend-routing]: ../traffic/backend
567+
[backend-tls]: ../backend-tls

0 commit comments

Comments
 (0)