From 7c912b17ec61eb88ba61bbf381c860f8643e4df0 Mon Sep 17 00:00:00 2001
From: Dennis Gaida <2392217+DennisGaida@users.noreply.github.com>
Date: Wed, 5 Jan 2022 13:28:56 +0100
Subject: [PATCH] Working example & documentation for Authelia

Signed-off-by: Dennis Gaida <2392217+DennisGaida@users.noreply.github.com>
---
 docs/content/guides/auth/authelia.md | 68 ++++++++++++++++++++++++++++
 1 file changed, 68 insertions(+)
 create mode 100644 docs/content/guides/auth/authelia.md

diff --git a/docs/content/guides/auth/authelia.md b/docs/content/guides/auth/authelia.md
new file mode 100644
index 00000000..387d3fd3
--- /dev/null
+++ b/docs/content/guides/auth/authelia.md
@@ -0,0 +1,68 @@
+# OAuth with Authelia SSO (self-hosted)
+
+## Prerequisites
+
+This guide assumes you have run and configured [Authelia](https://www.authelia.com/). If you want to get Authelia running quickly, there are example docker-compose files in the [Authelia Github repository](https://github.com/authelia/authelia/tree/master/examples/compose).
+Also this guides assumes you run HedgeDoc via a [Docker container](../../setup/docker.md). Find out how the mentioned config environment variables are mapped to entries in the config file at our [configuration page](../../configuration.md).
+
+## Steps
+
+1. Set up the necessary OpenID Connect parameters in your Authelia `configuration.yml` as explained in the documentation at <https://www.authelia.com/docs/configuration/identity-providers/oidc.html>.
+2. Make sure to generate safe secrets (such as `LENGTH=64; tr -cd '[:alnum:]' < /dev/urandom | fold -w "${LENGTH}" | head -n 1 | tr -d '\n' ; echo`)
+3. A completed `identity_providers` section of the configuration may look like the following (the chosen Client ID `id` shouldn't actually be this guessable for safety reasons):
+
+```yaml
+identity_providers:
+  oidc:
+    hmac_secret: <hmac secret here> # use docker secrets for this
+    issuer_private_key: <issuer private key secret here> # use docker secrets for this
+    access_token_lifespan: 1h
+    authorize_code_lifespan: 1m
+    id_token_lifespan: 1h
+    refresh_token_lifespan: 90m
+    enable_client_debug_messages: false
+    clients:
+      - id: HedgeDoc # this should be changed to something more secure
+        description: HedgeDoc SSO
+        secret: <client secret here>
+        public: false
+        authorization_policy: two_factor
+        audience: []
+        scopes:
+          - openid
+          - email
+          - profile
+        redirect_uris:
+          - https://<your-hedgedoc-url>/auth/oauth2/callback
+        grant_types:
+          - refresh_token
+          - authorization_code
+        response_types:
+          - code
+        response_modes:
+          - form_post
+          - query
+          - fragment
+        userinfo_signing_algorithm: none
+```
+
+4. Restart Authelia to apply to new configuration and check for any errors in the log
+5. In the `docker-compose.yml` of HedgeDoc add the following environment variables (you can choose different attributes for e.g. the display name - all available attributes you can find in the [scope definitions](https://www.authelia.com/docs/configuration/identity-providers/oidc.html#scope-definitions)):
+
+```yaml
+- CMD_URL_ADDPORT=false
+- CMD_PROTOCOL_USESSL=true
+- CMD_OAUTH2_PROVIDERNAME=Authelia
+- CMD_OAUTH2_CLIENT_ID=HedgeDoc
+- CMD_OAUTH2_CLIENT_SECRET=<client secret here>
+- CMD_OAUTH2_SCOPE=openid email profile
+- CMD_OAUTH2_USER_PROFILE_USERNAME_ATTR=sub
+- CMD_OAUTH2_USER_PROFILE_DISPLAY_NAME_ATTR=name
+- CMD_OAUTH2_USER_PROFILE_EMAIL_ATTR=email
+- CMD_OAUTH2_USER_PROFILE_URL=https://<your-authelia-url>/api/oidc/userinfo
+- CMD_OAUTH2_TOKEN_URL=https://<your-authelia-url>/api/oidc/token
+- CMD_OAUTH2_AUTHORIZATION_URL=https://<your-authelia-url>/api/oidc/authorize
+```
+
+6. Run `docker-compose up -d` on HedgeDoc to apply your settings.
+7. Sign in to your HedgeDoc using your Authelia login