Docs: Keycloak OIDC Guide

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.

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).

website/sidebars.js

@@ -115,6 +115,7 @@
       label: 'Guides',
       items: [
         'guides/oidc',
+        'guides/configuring-oidc-with-keycloak',
         'guides/displaying-custom-metadata',
         'guides/fluxga-upgrade',
       ],