Provide documentation for configuration with Keycloak

Signed-off-by: Simon Fish <si@mon.fish>

1 files changed, 39 insertions, 0 deletions

diff --git a/docs/guides/auth/keycloak.md b/docs/guides/auth/keycloak.md
new file mode 100644
index 00000000..58db33f6
--- /dev/null
+++ b/docs/guides/auth/keycloak.md
@@ -0,0 +1,39 @@
+Keycloak/Red Hat SSO (self-hosted)
+===
+
+1. Sign in to your Keycloak instance at https://keycloak.example.com/auth/admin/master/console
+2. Navigate to the client management page at `https://keycloak.example.com/auth/admin/master/console/#/realms/your-realm/clients` (admin permissions required)
+3. Click **Create** to create a new client and fill out the registration form. You should set the Root URL to the fully qualified public URL of your CodiMD instance.
+4. Click **Save**
+5. Set the **Access Type** of the client to `confidential`. This will make your client require a client secret upon authentication.
+
+---
+
+### Additional steps to circumvent generic OAuth2 issue:
+
+1. Select Client Scopes from the sidebar, and create a new one.
+2. Ensure that the **Name** is set to `id`.
+3. Create a new mapper under the Mappers tab. This should reference the User Property `id`. `Claim JSON Type` should be String and all switches below should be enabled. Save the mapper.
+4. Go to your client, then choose the Client Scopes tab. Apply the scope you've created. This should mitigate errors as seen in [codimd/server#56](https://github.com/codimd/server/issues/56).
+
+---
+
+6. In the `docker-compose.yml` add the following environment variables to `app:` `environment:`
+
+```
+- CMD_OAUTH2_USER_PROFILE_URL=https://keycloak.example.com/auth/realms/your-realm/protocol/openid-connect/userinfo
+- CMD_OAUTH2_USER_PROFILE_USERNAME_ATTR=preferred_username
+- CMD_OAUTH2_USER_PROFILE_DISPLAY_NAME_ATTR=name
+- CMD_OAUTH2_USER_PROFILE_EMAIL_ATTR=email
+- CMD_OAUTH2_TOKEN_URL=https://keycloak.example.com/auth/realms/your-realm/protocol/openid-connect/token
+- CMD_OAUTH2_AUTHORIZATION_URL=https://keycloak.example.com/auth/realms/your-realm/protocol/openid-connect/auth
+- CMD_OAUTH2_CLIENT_ID=<your client ID>
+- CMD_OAUTH2_CLIENT_SECRET=<your client secret, which you can find under the Credentials tab for your client>
+- CMD_OAUTH2_PROVIDERNAME=Keycloak
+- CMD_DOMAIN=<codimd.example.com>
+- CMD_PROTOCOL_USESSL=true 
+- CMD_URL_ADDPORT=false
+```
+
+7. Run `docker-compose up -d` to apply your settings.
+8. Sign in to your CodiMD using your Keycloak ID