diff options
| author | Leo Maroni | 2020-05-01 00:00:07 +0200 |
|---|---|---|
| committer | Leo Maroni | 2020-07-11 21:20:53 +0200 |
| commit | ae8bb96cc61840bb50b926b837e3cac0e4c01d2f (patch) | |
| tree | be5abc2f4f8b178acceffaaf30bc5d9057f0e4ae | |
| parent | 17f0067ab2553fdfd4c7b4043440c9a3e325929c (diff) | |
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>
| -rw-r--r-- | docs/guides/auth/keycloak.md | 2 | ||||
| -rw-r--r-- | docs/guides/auth/saml-keycloak.md | 113 | ||||
| -rw-r--r-- | docs/images/auth/keycloak_add_client.png | bin | 0 -> 54087 bytes | |||
| -rw-r--r-- | docs/images/auth/keycloak_client_overview.png | bin | 0 -> 207910 bytes | |||
| -rw-r--r-- | docs/images/auth/keycloak_clients_overview.png | bin | 0 -> 78485 bytes | |||
| -rw-r--r-- | docs/images/auth/keycloak_force_idformat.png | bin | 0 -> 6092 bytes | |||
| -rw-r--r-- | docs/images/auth/keycloak_idp_cert.png | bin | 0 -> 75137 bytes | |||
| -rw-r--r-- | docs/images/auth/keycloak_mapper_email.png | bin | 0 -> 52782 bytes | |||
| -rw-r--r-- | docs/images/auth/keycloak_mapper_overview.png | bin | 0 -> 30320 bytes | |||
| -rw-r--r-- | docs/images/auth/keycloak_mapper_username.png | bin | 0 -> 55010 bytes | |||
| -rw-r--r-- | docs/images/auth/keycloak_saml_export_cert.png | bin | 0 -> 181200 bytes | |||
| -rw-r--r-- | docs/images/auth/keycloak_saml_export_cert_details.png | bin | 0 -> 23261 bytes | |||
| -rw-r--r-- | docs/images/auth/keycloak_saml_import_cert.png | bin | 0 -> 181214 bytes | |||
| -rw-r--r-- | docs/images/auth/keycloak_saml_import_cert_details.png | bin | 0 -> 48727 bytes |
14 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 + +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 + +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) + +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 `/` + +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 + +5. Click on "Import" +6. Select `Certificate PEM` as "Archive Format" +7. Now upload the generated cert.pem (in this case named `cert.pem`) + +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 + + +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. + +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". + +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`) + + 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`) + + +The configured mappers should look like this: + + +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 +``` diff --git a/docs/images/auth/keycloak_add_client.png b/docs/images/auth/keycloak_add_client.png Binary files differnew file mode 100644 index 00000000..79121b15 --- /dev/null +++ b/docs/images/auth/keycloak_add_client.png diff --git a/docs/images/auth/keycloak_client_overview.png b/docs/images/auth/keycloak_client_overview.png Binary files differnew file mode 100644 index 00000000..1ff9d986 --- /dev/null +++ b/docs/images/auth/keycloak_client_overview.png diff --git a/docs/images/auth/keycloak_clients_overview.png b/docs/images/auth/keycloak_clients_overview.png Binary files differnew file mode 100644 index 00000000..388b3e00 --- /dev/null +++ b/docs/images/auth/keycloak_clients_overview.png diff --git a/docs/images/auth/keycloak_force_idformat.png b/docs/images/auth/keycloak_force_idformat.png Binary files differnew file mode 100644 index 00000000..1b1bf302 --- /dev/null +++ b/docs/images/auth/keycloak_force_idformat.png diff --git a/docs/images/auth/keycloak_idp_cert.png b/docs/images/auth/keycloak_idp_cert.png Binary files differnew file mode 100644 index 00000000..1b899283 --- /dev/null +++ b/docs/images/auth/keycloak_idp_cert.png diff --git a/docs/images/auth/keycloak_mapper_email.png b/docs/images/auth/keycloak_mapper_email.png Binary files differnew file mode 100644 index 00000000..b0ad667a --- /dev/null +++ b/docs/images/auth/keycloak_mapper_email.png diff --git a/docs/images/auth/keycloak_mapper_overview.png b/docs/images/auth/keycloak_mapper_overview.png Binary files differnew file mode 100644 index 00000000..8402a0bc --- /dev/null +++ b/docs/images/auth/keycloak_mapper_overview.png diff --git a/docs/images/auth/keycloak_mapper_username.png b/docs/images/auth/keycloak_mapper_username.png Binary files differnew file mode 100644 index 00000000..ccaa8954 --- /dev/null +++ b/docs/images/auth/keycloak_mapper_username.png diff --git a/docs/images/auth/keycloak_saml_export_cert.png b/docs/images/auth/keycloak_saml_export_cert.png Binary files differnew file mode 100644 index 00000000..e9fa5722 --- /dev/null +++ b/docs/images/auth/keycloak_saml_export_cert.png diff --git a/docs/images/auth/keycloak_saml_export_cert_details.png b/docs/images/auth/keycloak_saml_export_cert_details.png Binary files differnew file mode 100644 index 00000000..7f4c9e0c --- /dev/null +++ b/docs/images/auth/keycloak_saml_export_cert_details.png diff --git a/docs/images/auth/keycloak_saml_import_cert.png b/docs/images/auth/keycloak_saml_import_cert.png Binary files differnew file mode 100644 index 00000000..9295edab --- /dev/null +++ b/docs/images/auth/keycloak_saml_import_cert.png diff --git a/docs/images/auth/keycloak_saml_import_cert_details.png b/docs/images/auth/keycloak_saml_import_cert_details.png Binary files differnew file mode 100644 index 00000000..bb9d1d6c --- /dev/null +++ b/docs/images/auth/keycloak_saml_import_cert_details.png |
