From 13db4ca1a1f20ed925443a5db4663bd4ed708979 Mon Sep 17 00:00:00 2001 From: huabing zhao Date: Thu, 25 Apr 2024 15:50:17 -0700 Subject: [PATCH] update oidc docs Signed-off-by: huabing zhao --- site/content/en/latest/tasks/security/oidc.md | 130 +++++++++++++++--- 1 file changed, 114 insertions(+), 16 deletions(-) diff --git a/site/content/en/latest/tasks/security/oidc.md b/site/content/en/latest/tasks/security/oidc.md index 0360ccd496fe..4316a7dd97f5 100644 --- a/site/content/en/latest/tasks/security/oidc.md +++ b/site/content/en/latest/tasks/security/oidc.md @@ -13,20 +13,18 @@ This instantiated resource can be linked to a [Gateway][Gateway] and [HTTPRoute] ## Prerequisites -Follow the steps from the [Quickstart](../../quickstart) to install Envoy Gateway and the example manifest. +Follow the steps from the [Quickstart](../quickstart) to install Envoy Gateway and the example manifest. Before proceeding, you should be able to query the example backend using HTTP. +EG OIDC authentication requires the redirect URL to be HTTPS. Follow the [Secure Gateways](../security/secure-gateways) guide +to generate the TLS certificates and update the Gateway configuration to add an HTTPS listener. + Verify the Gateway status: ```shell kubectl get gateway/eg -o yaml ``` -OIDC can be configured at the Gateway level to authenticate all the HTTPRoutes that are associated with the Gateway with -the same OIDC configuration, or at the HTTPRoute level to authenticate each HTTPRoute with different OIDC configurations. - -This task demonstrates the configuration of OIDC at the HTTPRoute level. - Let's create an HTTPRoute that represents an application protected by OIDC. {{< tabpane text=true >}} @@ -86,16 +84,21 @@ Verify the HTTPRoute status: kubectl get httproute/myapp -o yaml ``` -## Configuration +## OIDC Authentication for a HTTPRoute -This task uses Google as the OIDC provider to demonstrate the configuration of OIDC. However, EG works with any OIDC -providers, including Auth0, Azure AD, Keycloak, Okta, OneLogin, Salesforce, UAA, etc. +OIDC can be configured at the Gateway level to authenticate all the HTTPRoutes that are associated with the Gateway with +the same OIDC configuration, or at the HTTPRoute level to authenticate each HTTPRoute with different OIDC configurations. + +This section demonstrates how to configure OIDC authentication for a specific HTTPRoute. ### Register an OIDC application +This task uses Google as the OIDC provider to demonstrate the configuration of OIDC. However, EG works with any OIDC +providers, including Auth0, Azure AD, Keycloak, Okta, OneLogin, Salesforce, UAA, etc. + Follow the steps in the [Google OIDC documentation][google-oidc] to register an OIDC application. Please make sure the redirect URL is set to the one you configured in the SecurityPolicy that you will create in the step below. In this example, -the redirect URL is `http://www.example.com:8080/myapp/oauth2/callback`. +the redirect URL is `http://www.example.com:8443/myapp/oauth2/callback`. After registering the application, you should have the following information: * Client ID: The client ID of the OIDC application. @@ -117,7 +120,7 @@ secret "my-app-client-secret" created Please notice that the `redirectURL` and `logoutPath` must match the target HTTPRoute. In this example, the target HTTPRoute is configured to match the host `www.example.com` and the path `/myapp`, so the `redirectURL` must be prefixed -with `http://www.example.com:8080/myapp`, and `logoutPath` must be prefixed with`/myapp`, otherwise the OIDC authentication +with `https://www.example.com:8443/myapp`, and `logoutPath` must be prefixed with`/myapp`, otherwise the OIDC authentication will fail because the redirect and logout requests will not match the target HTTPRoute and therefore can't be processed by the OAuth2 filter on that HTTPRoute. @@ -143,7 +146,7 @@ spec: clientID: "${CLIENT_ID}" clientSecret: name: "my-app-client-secret" - redirectURL: "http://www.example.com:8080/myapp/oauth2/callback" + redirectURL: "https://www.example.com:8443/myapp/oauth2/callback" logoutPath: "/myapp/logout" EOF ``` @@ -169,7 +172,7 @@ spec: clientID: "${CLIENT_ID}" clientSecret: name: "my-app-client-secret" - redirectURL: "http://www.example.com:8080/myapp/oauth2/callback" + redirectURL: "https://www.example.com:8443/myapp/oauth2/callback" logoutPath: "/myapp/logout" ``` @@ -182,14 +185,14 @@ Verify the SecurityPolicy configuration: kubectl get securitypolicy/oidc-example -o yaml ``` -## Testing +### Testing Port forward gateway port to localhost: ```shell export ENVOY_SERVICE=$(kubectl get svc -n envoy-gateway-system --selector=gateway.envoyproxy.io/owning-gateway-namespace=default,gateway.envoyproxy.io/owning-gateway-name=eg -o jsonpath='{.items[0].metadata.name}') -kubectl -n envoy-gateway-system port-forward service/${ENVOY_SERVICE} 8080:80 +kubectl -n envoy-gateway-system port-forward service/${ENVOY_SERVICE} 8443:443 ``` Put www.example.com in the /etc/hosts file in your test machine, so we can use this host name to access the gateway from a browser: @@ -199,9 +202,104 @@ Put www.example.com in the /etc/hosts file in your test machine, so we can use t 127.0.0.1 www.example.com ``` -Open a browser and navigate to the `http://www.example.com:8080/myapp` address. You should be redirected to the Google +Open a browser and navigate to the `https://www.example.com:8443/myapp` address. You should be redirected to the Google +login page. After you successfully login, you should see the response from the backend service. + +Clean the cookies in the browser and try to access `https://www.example.com:8443/foo` address. You should be able to see +this page since the path `/foo` is not protected by the OIDC policy. + +## OIDC Authentication for a Gateway + +OIDC can be configured at the Gateway level to authenticate all the HTTPRoutes that are associated with the Gateway with +the same OIDC configuration, or at the HTTPRoute level to authenticate each HTTPRoute with different OIDC configurations. + +This section demonstrates how to configure OIDC authentication for a Gateway. + +### Register an OIDC application + +If you haven't registered an OIDC application, follow the steps in the previous section to register an OIDC application. + +### Create a kubernetes secret + +If you haven't created a kubernetes secret, follow the steps in the previous section to create a kubernetes secret. + +### Create a SecurityPolicy + +Create or update the SecurityPolicy to target the Gateway instead of the HTTPRoute. Please notice that the `redirectURL` +and `logoutPath` must match one of the HTTPRoutes associated with the Gateway. In this example, the target Gateway has +two HTTPRoutes associated with it, one with the host `www.example.com` and the path `/myapp`, and the other with the host +`www.example.com` and the path `/`. Either one of the HTTPRoutes can be used to match the `redirectURL` and `logoutPath`. + +{{< tabpane text=true >}} +{{% tab header="Apply from stdin" %}} + +```shell +cat <}} + +Verify the SecurityPolicy configuration: + +```shell +kubectl get securitypolicy/oidc-example -o yaml +``` + +### Testing + +If you haven't done so, follow the steps in the previous section to port forward gateway port to localhost and put +www.example.com in the /etc/hosts file in your test machine. + +Open a browser and navigate to the `https://www.example.com:8443/foo` address. You should be redirected to the Google login page. After you successfully login, you should see the response from the backend service. +You can also try to access `https://www.example.com:8443/myapp` address. You should be able to see this page since the +path `/myapp` is protected by the same OIDC policy. + ## Clean-Up Follow the steps from the [Quickstart](../../quickstart) to uninstall Envoy Gateway and the example manifest.