diff options
Diffstat (limited to 'docs/guides/auth/saml-keycloak.md')
| -rw-r--r-- | docs/guides/auth/saml-keycloak.md | 113 |
1 files changed, 0 insertions, 113 deletions
diff --git a/docs/guides/auth/saml-keycloak.md b/docs/guides/auth/saml-keycloak.md deleted file mode 100644 index 1bc3b363..00000000 --- a/docs/guides/auth/saml-keycloak.md +++ /dev/null @@ -1,113 +0,0 @@ -# How to setup HedgeDoc SAML with Keycloak -## Configuring Keycloak -### Get the public certificate -1. Select the Realm you want to use for your HedgeDoc 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 HedgeDoc 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 HedgeDoc configuration or `CMD_SAML_ISSUER` environment variable -4. Select `SAML` as Client Protocol -5. Set Client SAML Endpoint to `https://hedgedoc.example.com/auth/saml` (replace `https://hedgedoc.example.com` with the base URL of your HedgeDoc installation) - -6. Leave "Client Signature Required" enabled -7. Set Root URL to `https://hedgedoc.example.com` (replace it here also with the base URL of your HedgeDoc installation) -8. Set Valid Redirect URIs to `https://hedgedoc.example.com/auth/saml/callback` (you should also define all other domains of your HedgeDoc 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 HedgeDoc -### Config file -You have to put the following block inside your `config.json`: -```json -"saml": { - "issuer": "hedgedoc", // 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`: `hedgedoc` (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 HedgeDoc, 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 HedgeDoc-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 HedgeDoc 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 HedgeDoc-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 HedgeDoc configuration or in the enviroment-variable `CMD_SAML_CLIENTCERT` - -## Use Persistent Identifiers -Instead of using the username as the owner-key in the HedgeDoc 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 HedgeDoc-Client in keycloak. Now enable the option "Force Name ID Format" and select "persistent" as the "Name ID Format". - -2. For HedgeDoc 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 HedgeDoc with enviroment variables, these are the ones you have to set: -```bash -CMD_SAML_ATTRIBUTE_USERNAME=username -CMD_SAML_ATTRIBUTE_EMAIL=email -``` |