diff --git a/website/docs/enterprise/getting-started/install-enterprise.mdx b/website/docs/enterprise/getting-started/install-enterprise.mdx index 41e883682e..0102676d88 100644 --- a/website/docs/enterprise/getting-started/install-enterprise.mdx +++ b/website/docs/enterprise/getting-started/install-enterprise.mdx @@ -135,6 +135,8 @@ You may decide to give your engineering teams access to the WGE dashboard so the OIDC extends the OAuth2 authorization protocol by including an additional field (ID Token) that contains information (claims) about a user's identity. After a user successfully authenticates with the OIDC provider, Weave GitOps Enterprise uses this information to impersonate the user in any calls to the Kubernetes API. This allows cluster administrators to use RBAC rules to control access to the cluster and the dashboard. +For more specific examples of how to setup OIDC with Weave GitOps, see [this guide](../../../guides/oidc/). + diff --git a/website/docs/guides/oidc.mdx b/website/docs/guides/oidc.mdx new file mode 100644 index 0000000000..e212c46fbf --- /dev/null +++ b/website/docs/guides/oidc.mdx @@ -0,0 +1,75 @@ +--- +title: Common OIDC provider configurations +--- + +This page provides guides for configuring Weave GitOps with the most common OIDC providers. + +## Google + +Google's identity provider does not support the groups scope which Weave GitOps requests by default. That's why in +this example the `customScopes` field is set to only request the `openid` and `email` scopes. + +1. Obtain the client ID and secret by following the [official guide](https://developers.google.com/identity/openid-connect/openid-connect) + from Google. +1. Configure Weave GitOps: + + ```yaml + apiVersion: v1 + kind: Secret + metadata: + name: oidc-auth + namespace: WEAVE_GITOPS_NAMESPACE + stringData: + clientID: CLIENT_ID_FROM_STEP_1 + clientSecret: CLIENT_SECRET_FROM_STEP_1 + issuerURL: https://accounts.google.com + redirectURL: BASE_WEAVE_GITOPS_URL/oauth2/callback + customScopes: openid,email + ``` + +## Azure AD + +1. Obtain the client ID and secret by following the [official guide](https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) + from Microsoft. +1. [optional] Configure group claims by following this [official guide](https://learn.microsoft.com/en-us/security/zero-trust/develop/configure-tokens-group-claims-app-roles). +1. Configure Weave GitOps: + + ```yaml + apiVersion: v1 + kind: Secret + metadata: + name: oidc-auth + namespace: WEAVE_GITOPS_NAMESPACE + stringData: + clientID: CLIENT_ID_FROM_STEP_1 + clientSecret: CLIENT_SECRET_FROM_STEP_1 + issuerURL: https://login.microsoftonline.com/TENANT_ID/v2.0 + redirectURL: BASE_WEAVE_GITOPS_URL/oauth2/callback + customScopes: openid + claimUsername: sub + ``` + +## Keycloak + +Keycloak is highly customizable so the steps to obtain client ID and secret will vary depending on your setup. The +general steps are very similar and the following steps point to the appropriate pages in the official Keycloak +documentation: + +1. Log in to the Keycloak admin console and [create a realm](https://www.keycloak.org/docs/latest/server_admin/#configuring-realms). +1. [Create a client application](https://www.keycloak.org/docs/latest/authorization_services/index.html#_resource_server_create_client) + and choose "OpenID Connect" as the client type. +1. Make sure to set the "Client Authenticator" on the "Credentials" tab to "Client Id and Secret" and generate a secret. +1. Configure Weave GitOps: + + ```yaml + apiVersion: v1 + kind: Secret + metadata: + name: oidc-auth + namespace: WEAVE_GITOPS_NAMESPACE + stringData: + clientID: CLIENT_ID_FROM_STEP_2 + clientSecret: CLIENT_SECRET_FROM_STEP_3 + issuerURL: https://KEYCLOAK_DOMAIN/realms/KEYCLOAK_REALM + redirectURL: BASE_WEAVE_GITOPS_URL/oauth2/callback + ``` diff --git a/website/sidebars.js b/website/sidebars.js index d2872a302b..72a401dd40 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -114,6 +114,7 @@ type: 'category', label: 'Guides', items: [ + 'guides/oidc', 'guides/displaying-custom-metadata', 'guides/fluxga-upgrade', ],