diff --git a/website/docs/guides/configuring-oidc-with-keycloak.mdx b/website/docs/guides/configuring-oidc-with-keycloak.mdx new file mode 100644 index 0000000000..b3ba33f739 --- /dev/null +++ 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 `-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/` +- 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` + +
Expand to see secret definition + +```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 +``` + +
+ +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. + +
Expand to see group role bindings + +```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 +``` + +
+ +## 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 new file mode 100644 index 0000000000..a67d98ac43 Binary files /dev/null and b/website/docs/guides/img/kc_step_01.png differ diff --git a/website/docs/guides/img/kc_step_02.png b/website/docs/guides/img/kc_step_02.png new file mode 100644 index 0000000000..214aad9f9b Binary files /dev/null and b/website/docs/guides/img/kc_step_02.png differ diff --git a/website/docs/guides/img/kc_step_03.png b/website/docs/guides/img/kc_step_03.png new file mode 100644 index 0000000000..8401894721 Binary files /dev/null and b/website/docs/guides/img/kc_step_03.png differ diff --git a/website/docs/guides/img/kc_step_04.png b/website/docs/guides/img/kc_step_04.png new file mode 100644 index 0000000000..e7bdc86f35 Binary files /dev/null and b/website/docs/guides/img/kc_step_04.png differ diff --git a/website/docs/guides/img/kc_step_05.png b/website/docs/guides/img/kc_step_05.png new file mode 100644 index 0000000000..54904e538c Binary files /dev/null and b/website/docs/guides/img/kc_step_05.png differ diff --git a/website/docs/guides/img/kc_step_06.png b/website/docs/guides/img/kc_step_06.png new file mode 100644 index 0000000000..9e21952cd5 Binary files /dev/null and b/website/docs/guides/img/kc_step_06.png differ diff --git a/website/docs/guides/img/kc_step_07.png b/website/docs/guides/img/kc_step_07.png new file mode 100644 index 0000000000..ee92e71eff Binary files /dev/null and b/website/docs/guides/img/kc_step_07.png differ diff --git a/website/docs/guides/img/kc_step_08.png b/website/docs/guides/img/kc_step_08.png new file mode 100644 index 0000000000..8ba5d7764c Binary files /dev/null and b/website/docs/guides/img/kc_step_08.png differ diff --git a/website/docs/guides/img/kc_step_09.png b/website/docs/guides/img/kc_step_09.png new file mode 100644 index 0000000000..5592c26c31 Binary files /dev/null and b/website/docs/guides/img/kc_step_09.png differ diff --git a/website/docs/guides/img/kc_step_10.png b/website/docs/guides/img/kc_step_10.png new file mode 100644 index 0000000000..96709d21ef Binary files /dev/null and b/website/docs/guides/img/kc_step_10.png differ diff --git a/website/docs/guides/img/kc_step_11.png b/website/docs/guides/img/kc_step_11.png new file mode 100644 index 0000000000..854732d708 Binary files /dev/null and b/website/docs/guides/img/kc_step_11.png differ diff --git a/website/docs/guides/img/kc_step_12.png b/website/docs/guides/img/kc_step_12.png new file mode 100644 index 0000000000..5c1d666312 Binary files /dev/null and b/website/docs/guides/img/kc_step_12.png differ diff --git a/website/docs/guides/img/kc_step_13.png b/website/docs/guides/img/kc_step_13.png new file mode 100644 index 0000000000..2674d5daae Binary files /dev/null and b/website/docs/guides/img/kc_step_13.png differ diff --git a/website/docs/guides/img/kc_step_14.png b/website/docs/guides/img/kc_step_14.png new file mode 100644 index 0000000000..7aaf69f249 Binary files /dev/null and b/website/docs/guides/img/kc_step_14.png differ diff --git a/website/docs/guides/img/kc_step_15.png b/website/docs/guides/img/kc_step_15.png new file mode 100644 index 0000000000..5f7898103b Binary files /dev/null and b/website/docs/guides/img/kc_step_15.png differ diff --git a/website/docs/guides/img/kc_step_16.png b/website/docs/guides/img/kc_step_16.png new file mode 100644 index 0000000000..0637c17976 Binary files /dev/null and b/website/docs/guides/img/kc_step_16.png differ diff --git a/website/docs/guides/img/kc_step_17.png b/website/docs/guides/img/kc_step_17.png new file mode 100644 index 0000000000..42818af1ff Binary files /dev/null and b/website/docs/guides/img/kc_step_17.png differ diff --git a/website/docs/guides/img/kc_step_18.png b/website/docs/guides/img/kc_step_18.png new file mode 100644 index 0000000000..2d523feb4d Binary files /dev/null and b/website/docs/guides/img/kc_step_18.png differ diff --git a/website/docs/guides/img/kc_step_19.png b/website/docs/guides/img/kc_step_19.png new file mode 100644 index 0000000000..2ebbb13719 Binary files /dev/null and b/website/docs/guides/img/kc_step_19.png differ diff --git a/website/docs/guides/img/kc_step_20.png b/website/docs/guides/img/kc_step_20.png new file mode 100644 index 0000000000..250c3a6f31 Binary files /dev/null and b/website/docs/guides/img/kc_step_20.png differ diff --git a/website/docs/guides/img/kc_step_21.png b/website/docs/guides/img/kc_step_21.png new file mode 100644 index 0000000000..37dfa156b9 Binary files /dev/null and b/website/docs/guides/img/kc_step_21.png differ diff --git a/website/docs/guides/img/kc_step_22.png b/website/docs/guides/img/kc_step_22.png new file mode 100644 index 0000000000..795129c3a9 Binary files /dev/null and b/website/docs/guides/img/kc_step_22.png differ diff --git a/website/docs/guides/img/kc_step_23.png b/website/docs/guides/img/kc_step_23.png new file mode 100644 index 0000000000..35c5c33f52 Binary files /dev/null and b/website/docs/guides/img/kc_step_23.png differ diff --git a/website/docs/guides/img/kc_step_24.png b/website/docs/guides/img/kc_step_24.png new file mode 100644 index 0000000000..383d6a6e6b Binary files /dev/null and b/website/docs/guides/img/kc_step_24.png differ diff --git a/website/docs/guides/img/kc_step_25.png b/website/docs/guides/img/kc_step_25.png new file mode 100644 index 0000000000..b8932488b7 Binary files /dev/null and b/website/docs/guides/img/kc_step_25.png differ diff --git a/website/docs/guides/img/kc_step_26.png b/website/docs/guides/img/kc_step_26.png new file mode 100644 index 0000000000..f9530d83f3 Binary files /dev/null and b/website/docs/guides/img/kc_step_26.png differ diff --git a/website/docs/guides/img/kc_step_27.png b/website/docs/guides/img/kc_step_27.png new file mode 100644 index 0000000000..f3ead661b4 Binary files /dev/null and b/website/docs/guides/img/kc_step_27.png differ diff --git a/website/docs/guides/img/kc_step_28.png b/website/docs/guides/img/kc_step_28.png new file mode 100644 index 0000000000..2d455ef05c Binary files /dev/null and b/website/docs/guides/img/kc_step_28.png differ diff --git a/website/docs/guides/oidc.mdx b/website/docs/guides/oidc.mdx index e212c46fbf..d2805ad7c8 100644 --- 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/sidebars.js b/website/sidebars.js index 72a401dd40..7dd785db1d 100644 --- 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', ],