From ae8bb96cc61840bb50b926b837e3cac0e4c01d2f Mon Sep 17 00:00:00 2001 From: Leo Maroni Date: Fri, 1 May 2020 00:00:07 +0200 Subject: Create Keycloak SAML guide Co-authored-by: Simeon Keske Signed-off-by: Simeon Keske Signed-off-by: Leo Maroni --- docs/guides/auth/keycloak.md | 2 +- docs/guides/auth/saml-keycloak.md | 113 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 114 insertions(+), 1 deletion(-) create mode 100644 docs/guides/auth/saml-keycloak.md (limited to 'docs/guides') 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 +``` -- cgit v1.2.3