Merge branch 'main' into add-back-anonymous-access

weaveworks · Nov 22, 2023 · 8a4045f · 8a4045f
2 parents f203708 + 6f7980b
commit 8a4045f
Show file tree

Hide file tree

Showing 33 changed files with 269 additions and 22 deletions.
diff --git a/website/docs/enterprise/getting-started/install-enterprise.mdx b/website/docs/enterprise/getting-started/install-enterprise.mdx
@@ -169,6 +169,10 @@ kubectl create secret generic oidc-auth \
 
 Once the HTTP server starts, unauthenticated users will have to click 'Login With OIDC Provider' to log in or use the cluster account (if configured). Upon successful authentication, the users' identities will be impersonated in any calls made to the Kubernetes API, as part of any action they take in the dashboard. By default the Helm chart will configure RBAC correctly, but we recommend reading the [service account](#gitops-dashboard-service-account-permissions) and [user permissions](#user-permissions) pages to understand which actions are needed for Weave GitOps to function correctly.
 
+:::warning
+Currently, we do not have a persistent session storage, this means that if you scale to multiple replicas, logins will not be persisted.
+:::
+
 #### Customization
 
 For some OIDC configurations, you may need to customise the requested [scopes](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) or [claims](https://openid.net/specs/openid-connect-core-1_0.html#Claims).

diff --git a/website/docs/guides/configuring-oidc-with-keycloak.mdx b/website/docs/guides/configuring-oidc-with-keycloak.mdx
@@ -0,0 +1,258 @@
+---
+title: Configuring OIDC with Keycloak
+---
+
+In this guide we will show you how to enable users to login to the Weave GitOps dashboard by authenticating them against a Keycloak instance.
+
+This example uses [Keycloak](https://www.keycloak.org/) and assumes Weave GitOps has already been installed on the Kubernetes Cluster.
+
+## Pre-requisites
+
+- A Kubernetes cluster
+- Weave GitOps is [installed](../../intro-weave-gitops/#getting-started) and [TLS has been enabled](../../enterprise/getting-started/install-enterprise/#tls-configuration)
+- Access to a running Keycloak installation
+
+## Configuring a new Keycloak Realm
+
+The first step is to create a new realm in Keycloak for our applications.
+
+![Creating a new Realm in Keycloak step 1](img/kc_step_01.png)
+
+To do that, navigate to your keycloak admin console and:
+
+1. In the top left menu, select the realm dropdown
+2. Click on the `Create Realm` button
+
+
+![Creating a new Realm in Keycloak step 2](img/kc_step_02.png)
+
+In the new window, fill in a name for your realm and then click on `Create`. In this guide, the realm will be named `demo`.
+
+### Creating a new Keycloak Client
+
+You should now have a new realm created. Now onto creating the client.
+
+![Keycloak realm homepage](img/kc_step_03.png)
+
+From the Keycloak admin console, make sure the new realm is selected in the top-left dropdown, and click on the `Clients` tab in the left menu.
+
+![Keycloak realm clients list](img/kc_step_04.png)
+
+Click on the `Create client` button at the top of the clients list.
+
+![Keycloak create client step 1](img/kc_step_05.png)
+
+In the `General Settings` pane:
+
+1. Make sure that the client type is set to `OpenID Connect`
+1. Set the `clientID` for your client to `weave-gitops`
+1. Give your client a suggestive name
+1. Click on the `Next` button.
+
+![Keycloak create client step 2](img/kc_step_06.png)
+
+In the `Capability config` pane:
+
+1. Make sure `Client authentication` is turned on
+1. Make sure `Standard flow` is turned on
+1. Make sure `Direct access grants` is turned on
+1. Click on the `Next` button.
+
+![Keycloak create client step 3](img/kc_step_07.png)
+
+Finally, in the `Login settings` pane:
+
+1. Set the `Home URL` for your client to the URL of your Weave GitOps instance. For this demo, that's `https://WEAVE_GITOPS_URL`
+1. Set the `Valid redirect URIs` to the URL of your Weave GitOps instance followed by `/oauth2/callback`. For this demo, that's `https://WEAVE_GITOPS_URL/oauth2/callback`
+1. Click on `Save`
+
+### Creating the Groups Mapper for the Keycloak Client
+
+You should now have an OIDC client created in your realm.
+
+![Keycloak new client page](img/kc_step_08.png)
+
+From the `Clients` page, click on your newly created client.
+
+![Keycloak client scopes](img/kc_step_09.png)
+
+1. In the top menu, select the `Client scopes` tab
+1. From the list of client scopes, select the `<client-name>-dedicated` scope. For this demo, that's `weave-gitops-dedicated`
+
+![Keycloak create new mapper step 1](img/kc_step_10.png)
+
+In the new window, you should see that there are no mappers configured. Click on the `Configure a new mapper` button.
+
+![Keycloak create new mapper step 2](img/kc_step_11.png)
+
+In the dialog that pops up, scroll down until you see `User Client Role` and select it.
+
+![Keycloak create new mapper step 3](img/kc_step_12.png)
+
+In the new window that opens up:
+
+1. Set the `Name` of your mapper to `groups`
+1. Select your client in the `Client ID` drop-down
+1. Set the `Token Claim Name` to groups
+1. Make sure the other settings match the ones in the screenshot above and click on `Save`
+
+![Keycloak new mapper in list](img/kc_step_13.png)
+
+You should now be able to see your new mapper in the list.
+
+### Creating the Client Roles
+
+Once your client and your mapper are created, it's time to create some roles.
+
+![Keycloak create client role step 1](img/kc_step_14.png)
+
+Navigate back to your client page and select the `Roles` tab in the top menu. It should say that there are currently no roles configured for this client. Click on `Create role`
+
+![Keycloak create client role step 2](img/kc_step_15.png)
+
+In the new window that is opened:
+
+1. Fill in your role name to `wego-admin`
+2. Click on `Save`
+
+![Keycloak create client role step 3](img/kc_step_16.png)
+
+You should now be able to see your new role configured.
+
+### Obtaining the client secret
+
+Now that everything is configured, we need to grab the client secret from Keycloak in order to configure OIDC for Weave GitOps.
+
+![Keycloak new mapper in list](img/kc_step_17.png)
+
+Navigate back to your client page and select the `Credentials` tab in the top menu. Copy the `Client secret` value and save it for later.
+
+### Creating a demo user
+
+Since this demo does not cover setting up the LDAP or AD integration for Keycloak, we need to create a demo user to validate our config.
+
+![Keycloak create user step 1](img/kc_step_18.png)
+
+Navigate back to the realm homepage in your Keycloak Admin console, and:
+
+1. Select the `Users` tab in the left menu
+2. Click on the `Add user` button
+
+![Keycloak create user step 2](img/kc_step_19.png)
+
+In the new page that opens up, fill in the details of a demo user and click on `Create`.
+
+![Keycloak create user step 3](img/kc_step_20.png)
+
+Once the user is created, we need to set a password. To do that:
+
+1. Navigate to the `Credentials` tab in the top menu
+2. Click on the `Set password` button
+
+![Keycloak create user step 4](img/kc_step_21.png)
+
+In the dialog that opens up, set a password for your user, confirm it, optionally mark it as not-temporary and click on `Save`.
+
+![Keycloak create user step 5](img/kc_step_22.png)
+
+You should now see a password configured for your user.
+
+![Keycloak create user step 6](img/kc_step_23.png)
+
+Now we need to assign the `wego-admin` role we created earlier to our user. To do that:
+
+1. Navigate to the `Role mapping` tab in the top menu
+2. Click on the `Assign role` button
+
+![Keycloak create user step 7](img/kc_step_24.png)
+
+In the dialog that opens up:
+
+1. Select the `Filter by clients` option in the dropdown
+2. Type in your client name in the search bar
+3. Tick the checkbox next to the role
+4. Click on `Assign`
+
+![Keycloak create user step 8](img/kc_step_25.png)
+
+The role should now appear in the `Role mapping` section and our user should be fully configured.
+
+## Configuring Weave GitOps to use our new Keycloak Client
+
+Now that our Keycloak configuration is done, it's time to link our Weave GitOps deployment to it.
+
+### Creating the `oidc-auth` secret
+
+To configure Weave GitOps for OIDC authentication via Keycloak, we need to configure the `oidc-auth` secret. We need to set:
+
+- the `issuerURL` to the URL of our keycloak instance, followed by `/realms/<realm_name>`
+- the `redirectURL` to the URL of our Weave GitOps instance, followed by `/oauth2/callback`
+- the `clientID` to the id of the client we created in the previous steps
+- the `clientSecret` to the secret we copied a few steps ago
+- the `customScopes` to `email`
+- the `claimGroups` to `groups` to work with our mapper, mapping from roles->groups
+- the `claimUsername` to `sub`
+
+<details><summary>Expand to see secret definition </summary>
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+    name: oidc-auth
+stringData:
+    issuerURL: https://auth.mydomain.com/keycloak/realms/demo
+    redirectURL: https://gitops.mydomain.com/oauth2/callback
+    clientID: weave-gitops
+    clientSecret: N8jDkMdghg38jiw52VHeTH1V7WUmM1tv
+    customScopes: email
+    claimGroups: groups
+    claimUsername: sub
+```
+
+</details>
+
+After this secret is created, you may need to delete the Weave GitOps pods in order to restart the app and load the new config.
+
+### Setting up RBAC
+
+Once Weave GitOps is configured for OIDC, we need a way to map permissions to the groups. To do that, we need to create role bindings for our `wego-admin` group.
+The following example assumes that the ClusterRole `wego-admin-cluster-role` and the namespaced Role `wego-admin-role` already exist. It will grant everyone
+in the `wego-admin` group within Keycloak admin access. See the [recommendations on setting up RBAC](../../enterprise/getting-started/install-enterprise/#recommended-rbac-configuration)
+for details.
+
+<details><summary>Expand to see group role bindings</summary>
+
+```yaml
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: keycloak-wego-admin
+subjects:
+  - kind: Group
+    name: wego-admin
+    apiGroup: rbac.authorization.k8s.io
+roleRef:
+  kind: ClusterRole
+  name: wego-admin-cluster-role
+  apiGroup: rbac.authorization.k8s.io
+```
+
+</details>
+
+## Testing the configuration
+
+Now that everything is set up, let's test our configuration.
+
+![Test config step 1](img/kc_step_26.png)
+
+Navigate to your Weave GitOps dashboard URL and click on the `Login With Keycloak` button. You should be redirected to a Keycloak Login page.
+
+![Test config step 2](img/kc_step_27.png)
+
+In the page that opens up, input your demo user credentials and click on `Sign In`.
+
+![Test config step 3](img/kc_step_28.png)
+
+You should now be redirected back to Weave GitOps and, thanks to the RBAC configuration, you should now see all of the configured applications.
diff --git a/website/docs/guides/img/kc_step_01.png b/website/docs/guides/img/kc_step_01.png
diff --git a/website/docs/guides/img/kc_step_02.png b/website/docs/guides/img/kc_step_02.png
diff --git a/website/docs/guides/img/kc_step_03.png b/website/docs/guides/img/kc_step_03.png
diff --git a/website/docs/guides/img/kc_step_04.png b/website/docs/guides/img/kc_step_04.png
diff --git a/website/docs/guides/img/kc_step_05.png b/website/docs/guides/img/kc_step_05.png
diff --git a/website/docs/guides/img/kc_step_06.png b/website/docs/guides/img/kc_step_06.png
diff --git a/website/docs/guides/img/kc_step_07.png b/website/docs/guides/img/kc_step_07.png
diff --git a/website/docs/guides/img/kc_step_08.png b/website/docs/guides/img/kc_step_08.png
diff --git a/website/docs/guides/img/kc_step_09.png b/website/docs/guides/img/kc_step_09.png
diff --git a/website/docs/guides/img/kc_step_10.png b/website/docs/guides/img/kc_step_10.png
diff --git a/website/docs/guides/img/kc_step_11.png b/website/docs/guides/img/kc_step_11.png
diff --git a/website/docs/guides/img/kc_step_12.png b/website/docs/guides/img/kc_step_12.png
diff --git a/website/docs/guides/img/kc_step_13.png b/website/docs/guides/img/kc_step_13.png
diff --git a/website/docs/guides/img/kc_step_14.png b/website/docs/guides/img/kc_step_14.png
diff --git a/website/docs/guides/img/kc_step_15.png b/website/docs/guides/img/kc_step_15.png
diff --git a/website/docs/guides/img/kc_step_16.png b/website/docs/guides/img/kc_step_16.png
diff --git a/website/docs/guides/img/kc_step_17.png b/website/docs/guides/img/kc_step_17.png
diff --git a/website/docs/guides/img/kc_step_18.png b/website/docs/guides/img/kc_step_18.png
diff --git a/website/docs/guides/img/kc_step_19.png b/website/docs/guides/img/kc_step_19.png
diff --git a/website/docs/guides/img/kc_step_20.png b/website/docs/guides/img/kc_step_20.png
diff --git a/website/docs/guides/img/kc_step_21.png b/website/docs/guides/img/kc_step_21.png
diff --git a/website/docs/guides/img/kc_step_22.png b/website/docs/guides/img/kc_step_22.png
diff --git a/website/docs/guides/img/kc_step_23.png b/website/docs/guides/img/kc_step_23.png
diff --git a/website/docs/guides/img/kc_step_24.png b/website/docs/guides/img/kc_step_24.png
diff --git a/website/docs/guides/img/kc_step_25.png b/website/docs/guides/img/kc_step_25.png
diff --git a/website/docs/guides/img/kc_step_26.png b/website/docs/guides/img/kc_step_26.png
diff --git a/website/docs/guides/img/kc_step_27.png b/website/docs/guides/img/kc_step_27.png
diff --git a/website/docs/guides/img/kc_step_28.png b/website/docs/guides/img/kc_step_28.png
diff --git a/website/docs/guides/oidc.mdx b/website/docs/guides/oidc.mdx
@@ -51,25 +51,5 @@ this example the `customScopes` field is set to only request the `openid` and `e
 
 ## 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
-   ```
+Keycloak is highly customizable so the steps to obtain client ID and secret will vary depending on your setup. That's why
+there is a [dedicated guide on setting up Keycloak and Weave GitOps to work together](./configuring-oidc-with-keycloak.mdx).
diff --git a/website/docs/open-source/getting-started/install-OSS.mdx b/website/docs/open-source/getting-started/install-OSS.mdx
@@ -181,6 +181,10 @@ Our docs on [securing access to the dashboard](../../enterprise/getting-started/
 
 You will use the password you've just created when you've finished Weave GitOps Open Source installation and are ready to login to the dashboard UI.
 
+:::warning
+Currently, we do not have a persistent session storage, this means that if you scale to multiple replicas, logins will not be persisted.
+:::
+
 :::tip
 If you need to customize the Weave GitOps Helm release, you can use the `--values` CLI flag to supply one or more values files.
 

diff --git a/website/sidebars.js b/website/sidebars.js
@@ -115,6 +115,7 @@
       label: 'Guides',
       items: [
         'guides/oidc',
+        'guides/configuring-oidc-with-keycloak',
         'guides/displaying-custom-metadata',
         'guides/fluxga-upgrade',
         'guides/anonymous-access',