Create Keycloak SAML guide

Co-authored-by: Simeon Keske <git@n0emis.eu>
Signed-off-by: Simeon Keske <git@n0emis.eu>
Signed-off-by: Leo Maroni <git@em0lar.de>

2 files changed, 114 insertions, 1 deletions

diff --git a/docs/guides/auth/keycloak.md b/docs/guides/auth/keycloak.md
index cf667774..16e24bc5 100644
--- a/docs/guides/auth/keycloak.md
+++ b/docs/guides/auth/keycloak.md
@@ -1,4 +1,4 @@
-# Keycloak/Red Hat SSO (self-hosted)
+OAuth with Keycloak/Red Hat SSO (self-hosted)
 
 ## Prerequisites
 
diff --git a/docs/guides/auth/saml-keycloak.md b/docs/guides/auth/saml-keycloak.md
new file mode 100644
index 00000000..a45ea943
--- /dev/null
+++ b/docs/guides/auth/saml-keycloak.md
@@ -0,0 +1,113 @@
+# How to setup CodiMD SAML with Keycloak
+## Configuring Keycloak
+### Get the public certificate
+1. Select the Realm you want to use for your CodiMD SAML
+2. Select "Realm Settings" in left sidebar
+3. Select the "Keys" tab
+4. Click the button "Certificate" at `RS256` algorithm
+![keycloak_idp_cert](../../images/auth/keycloak_idp_cert.png)
+5. Copy this key and save it to the file specified in `saml.idpCert` property of the CodiMD configuration or `CMD_SAML_IDPCERT` environment variable
+
+### Create a new client
+1. Select "Client" in left sidebar
+![keycloak_clients_overview](https://md.em0lar.de/uploads/upload_443839d7e4929aacf17b6babe6fa77ba.png)
+2. Click on the "Create" button
+3. Set a Client ID and specify this in `saml.issuer` property of the CodiMD configuration or `CMD_SAML_ISSUER` environment variable
+4. Select `SAML` as Client Protocol
+5. Set Client SAML Endpoint to `https://codimd.example.com/auth/saml` (replace `https://codimd.example.com` with the base URL of your CodiMD installation)
+![keycloak_add_client](https://md.em0lar.de/uploads/upload_451868268f37a7c47b8bf2ab4f9d1fa9.png)
+6. Leave "Client Signature Required" enabled
+7. Set Root URL to `https://codimd.example.com` (replace it here also with the base URL of your CodiMD installation)
+8. Set Valid Redirect URIs to `https://codimd.example.com/auth/saml/callback` (you should also define all other domains of your CodiMD installtion with the suffix `/auth/saml/callback`)
+9. Set Base URL to `/`
+![keycloak_client_overview](https://md.em0lar.de/uploads/upload_fd0560a2e8e4cbd6e88bb8828d0a4fb1.png)
+10. _(optional)_ You can set which Name ID Format should be used
+
+## Configure CodiMD
+### Config file
+You have to put the following block inside your `config.json`:
+```json
+"saml": {
+  "issuer": "codimd", // Change to the "Client ID" specified in the Keycloak Client
+  "identifierFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
+  "idpSsoUrl": "https://keycloak.example.org/auth/realms/test/protocol/saml", // replace keycloak.example.org with the url of your keycloak server
+  "idpCert": "/path/to/the/cert.pem",
+  "clientCert": "/path/to/the/key.pem" // this one is optional, see below
+}
+```
+
+### Environment Variables
+- `CMD_SAML_IDPSSOURL`: `https://keycloak.example.org/auth/realms/test/protocol/saml` (replace keycloak.example.org with the url of your keycloak server)
+- `CMD_SAML_IDPCERT`: `/path/to/the/cert.pem`
+- *(optional, see below)* `CMD_SAML_CLIENTCERT`: `/path/to/the/key.pem`
+- `CMD_SAML_ISSUER`: `codimd` (Change to the "Client ID" specified in the Keycloak Client)
+- `CMD_SAML_IDENTIFIERFORMAT`: `urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified`
+
+
+## Client certificate *(optional)*
+If you want keycloak to be able to verify CodiMD, you hava to create a client certificate. There are two options for this:
+
+### Create Private Keys for Signing
+1. Generate the private key and certificate with the following commands:
+```shell
+openssl genrsa -out priv.pem 2048
+openssl req -new -x509 -key priv.pem -out cert.pem
+```
+*execute the following steps in keycloak*
+
+2. Select "Client" in left sidebar
+3. Go to your CodiMD-Client
+4. Select the "SAML Keys" tab
+![keycloak_saml_import_cert](https://md.em0lar.de/uploads/upload_85d97cc7b764a6199064342283310074.png)
+5. Click on "Import"
+6. Select `Certificate PEM` as "Archive Format"
+7. Now upload the generated cert.pem (in this case named `cert.pem`)
+![keycloak_saml_import_cert_details](https://md.em0lar.de/uploads/upload_95ad43ccb73a85e8a5dab322db6a0f12.png)
+8. Click on "Import"
+9. Move or copy this key (in this case named `key.pem`) and save it to the file specified in `saml.clientCert` property of the CodiMD configuration or in the enviroment-variable `CMD_SAML_CLIENTCERT`
+
+
+### Convert Private Certificate generated by KeyCloak
+Instead if generating you own certificate, you can also use the one generated by keycloak.
+
+1. Select "Client" in left sidebar
+2. Go to your CodiMD-Client
+3. Select the "SAML Keys" tab
+![keycloak_saml_export_cert](https://md.em0lar.de/uploads/upload_ac3343ef86dad2f10155ba9707bea042.png)
+
+5. Now click on "Export"
+6. Here you can select the output format, choose `PKCS12`. You also have to set a password. Choose your own.
+![keycloak_saml_export_cert_details](https://md.em0lar.de/uploads/upload_8eaa9082c9fb429614ecdf9ebcfc93c5.png)
+6. Click on "Download" and save the file somewhere on you computer
+7. You now have to extract the private Key. You can do this with the following command. WHen asked, enter your password.
+```shell
+openssl pkcs12 -in keystore.p12 -out key.pem -nocerts -nodes
+```
+8. Move or copy this key (in this case named `key.pem`) and save it to the file specified in `saml.idpCert` property of the CodiMD configuration or in the enviroment-variable `CMD_SAML_CLIENTCERT`
+
+## Use Persistent Identifiers
+Instead of using the username as the owner-key in the CodiMD database, you can also use a persistent identifier. This allows to change the username, without them loosing access to their notes.
+
+1. Go to the CodiMD-Client in keycloak. Now enable the option "Force Name ID Format" and select "persistent" as the "Name ID Format".
+![keycloak_force_idformat](https://md.em0lar.de/uploads/upload_dc195bbed788aa4eb7b8cf7c29141a45.png)
+2. For codimd to be able to use the username and email configured in keycloak, you have to create the following SAML protocol mappers:
+    2.1. Create a mapper with the type `User Property`. Set the Name, Property and SAML Attribute Name to `username`. Now you can specify a friendly name (for example `Username`)
+![keycloak_mapper_username](https://md.em0lar.de/uploads/upload_7c69c97213c86888ccf0d781a3ea2fc8.png)
+    2.2 Create a mapper with the type `User Property`. Set the Name, Property and SAML Attribute Name to `email`. Now you can specify a friendly name (for example `E-Mail`)
+![keycloak_mapper_email](https://md.em0lar.de/uploads/upload_a65ef8729a96e9cd02eeec173726094d.png)
+
+The configured mappers should look like this:
+![keycloak_mapper_overview](https://md.em0lar.de/uploads/upload_0cf3fcccc4d192c6575f065949b786be.png)
+
+3. You now have to add the following block to the saml-definition inside your `config.json`:
+```json
+"attribute": {
+      "username": "username"
+      "email": "email",
+}
+```
+It you configure CodiMD with enviroment variables, these are the ones you have to set:
+```bash
+CMD_SAML_ATTRIBUTE_USERNAME=username
+CMD_SAML_ATTRIBUTE_EMAIL=email
+```