From a8e991158030154731381a19390bed308fbba230 Mon Sep 17 00:00:00 2001 From: Ingar Helgesen Date: Wed, 15 Sep 2021 10:13:59 +0200 Subject: [PATCH 1/2] docs: create auth/keycloak --- auth/keycloak.md | 57 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 auth/keycloak.md diff --git a/auth/keycloak.md b/auth/keycloak.md new file mode 100644 index 000000000..5fc54aa87 --- /dev/null +++ b/auth/keycloak.md @@ -0,0 +1,57 @@ +--- +title: Keycloak +description: Authentication Module +published: true +date: 2021-09-15T07:49:57.150Z +tags: auth, module +--- + +# Keycloak +[Keycloak](https://keycloak.org) is an Open Source Identity and Access Management solution for modern Applications and Services. + +## Relevant information +- [Keycloak OIDC Endpoints](https://www.keycloak.org/docs/latest/server_admin/#keycloak-server-oidc-uri-endpoints) +- [Keycloak OIDC Clients](https://www.keycloak.org/docs/latest/server_admin/#_clients) + +## Setup +### Create Keycloak strategy instance on WikiJS +1. In the Administration area of your wiki, click on `Authentication` in the left navigation menu +2. Click on `+ ADD STRATEGY`, scroll down and select `Keycloak` +3. Click `Apply` (Just to make sure the instance ID will not be regenerated if the page is reloaded. This produces an error in the logs, so it might display an error on the frontend too in the future. If so just skip this step and double check the ID when setting it up) +4. Go to the bottom of the page and copy/note the `Callback URL / Redirect URI` +5. We will fill out the rest after setting up the Keycloak client + +### Creating a Keycloak client +1. At the Keycloak administration page, go to the `Clients` menu, and click `Create` button on the right +2. Enter a **Client ID**, for example `wikijs` (You wil need the `Client ID` later) +3. Select **openid-connect** as `Client Protocol` +4. And **Root URL** is the base URL to Wikijs (for example `https://wiki.example.com`) +5. Click **Save** +6. Change **Access Type** to `confidential` +7. Enter the **Valid Redirect URIs**, which is the `Callback URL / Redirect URI` from WikiJS (ex. `https://wiki.example.com/login/d03f689b-0dd0-44d6-90ca-6386ec41d799/callback`, or just the path `/login/{GUID}/callback`) +8. Set **Base URL** to the same as `Root URL` +9. Set **Web Origins** to `+`, which means to use the URIs in the `Valid Redirect URIs` entry. +10. Now click **Save** at the bottom of the page +11. Go to the **Credentials** tab and copy the `Secret` (You will need this one later too) + +### Configure the Keycloak strategy in Wiki.js +1. If you're not already there. Go to the Administration area of your wiki, click on `Authentication` in the left navigation menu +2. Click on **Keycloak** +3. Enter the **Host**, which is the domain (incl. the scheme) of your Keycloak server (Example: `https://keycloak.example.com`) +4. Enter the **Realm**, which is the realm you are using in Keycloak (Default is: `master`) +5. Enter the **Client Id**, which is the `Client ID` from Keycloak +6. Enter the **Client Secret**, which is the `Secret` from Keycloak +7. Enter the **Authorization Endpoint URL**, which is `https://keycloak.example.com/auth/realms/master/protocol/openid-connect/auth` +8. Enter the **Token URL**, which is `https://keycloak.example.com/auth/realms/master/protocol/openid-connect/token` +9. Enter the **User Info URL**, which is `https://keycloak.example.com/auth/realms/master/protocol/openid-connect/userinfo` +10. If you want the user to be logged out of Keycloak when logging out of WikiJS, enable `Logout from Keycloak on Logout` +11. Enter the `Logout Endpoint URL`, which is `https://keycloak.example.com/auth/realms/master/protocol/openid-connect/logout` +12. Check **Allow self-registration** to enable the Keycloak login button, and auto create users as they login for the first time. +13. Remember to add a group with at least read permissions in the **Assign to group** list +14. Click `Apply` in the top-left corner and try to login + +### Seamless login +If the login worked, you can enable `Bypass Login Screen` under the `Security` tab in the left navigation menu. +Make sure the Keycloak provider is at the top of the list in the `Authentication` tab. + +![](https://static.requarks.io/logo/keycloak.svg =x50){.align-abstopright} \ No newline at end of file From 7c9e345b9132b181e83b2ba6c02e54f44d07d9b1 Mon Sep 17 00:00:00 2001 From: Ingar Helgesen Date: Thu, 16 Sep 2021 11:29:29 +0200 Subject: [PATCH 2/2] docs: update auth/keycloak --- auth.md | 1 + auth/keycloak.md | 13 ++++++------- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/auth.md b/auth.md index f0cec5caf..1e71470e3 100644 --- a/auth.md +++ b/auth.md @@ -27,6 +27,7 @@ Most strategies require some configuration. Check out the links below for module - Firebase - [GitHub](/auth/github) - [Google](/auth/google) +- [Keycloak OpenID Connect](/auth/keycloak) - [LDAP / Active Directory](/auth/ldap) - [Local](/auth/local) - Microsoft diff --git a/auth/keycloak.md b/auth/keycloak.md index 5fc54aa87..7cc90973b 100644 --- a/auth/keycloak.md +++ b/auth/keycloak.md @@ -14,12 +14,11 @@ tags: auth, module - [Keycloak OIDC Clients](https://www.keycloak.org/docs/latest/server_admin/#_clients) ## Setup -### Create Keycloak strategy instance on WikiJS +### Create Keycloak strategy instance on Wiki.js 1. In the Administration area of your wiki, click on `Authentication` in the left navigation menu 2. Click on `+ ADD STRATEGY`, scroll down and select `Keycloak` -3. Click `Apply` (Just to make sure the instance ID will not be regenerated if the page is reloaded. This produces an error in the logs, so it might display an error on the frontend too in the future. If so just skip this step and double check the ID when setting it up) -4. Go to the bottom of the page and copy/note the `Callback URL / Redirect URI` -5. We will fill out the rest after setting up the Keycloak client +3. Go to the bottom of the page and copy/note the `Callback URL / Redirect URI` +4. Keep this page/tab open. We will fill out the rest after setting up the Keycloak client ### Creating a Keycloak client 1. At the Keycloak administration page, go to the `Clients` menu, and click `Create` button on the right @@ -28,7 +27,7 @@ tags: auth, module 4. And **Root URL** is the base URL to Wikijs (for example `https://wiki.example.com`) 5. Click **Save** 6. Change **Access Type** to `confidential` -7. Enter the **Valid Redirect URIs**, which is the `Callback URL / Redirect URI` from WikiJS (ex. `https://wiki.example.com/login/d03f689b-0dd0-44d6-90ca-6386ec41d799/callback`, or just the path `/login/{GUID}/callback`) +7. Enter the **Valid Redirect URIs**, which is the `Callback URL / Redirect URI` from Wiki.js (ex. `https://wiki.example.com/login/d03f689b-0dd0-44d6-90ca-6386ec41d799/callback`, or just the path `/login/{GUID}/callback`) 8. Set **Base URL** to the same as `Root URL` 9. Set **Web Origins** to `+`, which means to use the URIs in the `Valid Redirect URIs` entry. 10. Now click **Save** at the bottom of the page @@ -44,11 +43,11 @@ tags: auth, module 7. Enter the **Authorization Endpoint URL**, which is `https://keycloak.example.com/auth/realms/master/protocol/openid-connect/auth` 8. Enter the **Token URL**, which is `https://keycloak.example.com/auth/realms/master/protocol/openid-connect/token` 9. Enter the **User Info URL**, which is `https://keycloak.example.com/auth/realms/master/protocol/openid-connect/userinfo` -10. If you want the user to be logged out of Keycloak when logging out of WikiJS, enable `Logout from Keycloak on Logout` +10. If you want the user to be logged out of Keycloak when logging out of Wiki.js, enable `Logout from Keycloak on Logout` 11. Enter the `Logout Endpoint URL`, which is `https://keycloak.example.com/auth/realms/master/protocol/openid-connect/logout` 12. Check **Allow self-registration** to enable the Keycloak login button, and auto create users as they login for the first time. 13. Remember to add a group with at least read permissions in the **Assign to group** list -14. Click `Apply` in the top-left corner and try to login +14. Click `Apply` in the top-right corner and try to login ### Seamless login If the login worked, you can enable `Bypass Login Screen` under the `Security` tab in the left navigation menu.