diff --git a/site/content/en/latest/user/oidc.md b/site/content/en/latest/user/oidc.md new file mode 100644 index 00000000000..3983d1530fa --- /dev/null +++ b/site/content/en/latest/user/oidc.md @@ -0,0 +1,124 @@ +--- +title: "OIDC Authentication" +--- + +This guide provides instructions for configuring [OpenID Connect (OIDC)][oidc] authentication. +OpenID Connect (OIDC) is an authentication standard built on top of OAuth 2.0. +It enables client applications to rely on authentication that is performed by an OpenID Connect Provider (OP) +to verify the identity of a user. + +Envoy Gateway introduces a new CRD called [SecurityPolicy][SecurityPolicy] that allows the user to configure OIDC +authentication. +This instantiated resource can be linked to a [Gateway][Gateway] and [HTTPRoute][HTTPRoute] resource. + +## Prerequisites + +Follow the steps from the [Quickstart](../quickstart) guide to install Envoy Gateway and the example manifest. +Before proceeding, you should be able to query the example backend using HTTP. + +OIDC authentication requires the redirect URL to be HTTPS. Follow the [Secure Gateways](../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/teg -o yaml +``` + +## Configuration + +This guide 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. + +### Register an OIDC application + +Follow the steps in the [Google OIDC documentation][google-oidc] to register an OIDC application. Please use +`https://www.example.com/oauth2/callback` as the redirect URL when registering the application. `oauth2/callback` is the +default callback path used by Envoy Gateway. + +After registering the application, you should have the following information: +* Client ID: The client ID of the OIDC application. +* Client Secret: The client secret of the OIDC application. + +### Create a kubernetes secret + +Next, create a kubernetes secret with the Client Secret created in the previous step. The secret is an Opaque secret, +and the Client Secret must be stored in the key "client-secret". + +Note: please replace the ${CLIENT_SECRET} with the actual Client Secret that you got from the previous step. + +```shell +$ kubectl create secret generic my-app-client-secret --from-literal=client-secret=${CLIENT_SECRET} +secret "my-app-client-secret" created +``` + +### Create a SecurityPolicy + +Note: please replace the ${CLIENT_ID} with the actual Client ID that you got from the previous step. + +```shell +cat <