You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: Learn how to control access to your HedgeDoc web application behind Pomerium.
19
9
---
20
10
21
11
# HedgeDoc
22
12
23
-
Use Pomerium to secure access to HedgeDoc by providing identity and context.
13
+
In this guide, you'll learn how to run a HedgeDoc web application behind Pomerium. You'll also add an authorization policy that enables Pomerium to grant or deny access based on policy criteria.
24
14
25
15
## What is HedgeDoc?
26
16
27
-
[HedgeDoc](https://hedgedoc.org/) is a collaborative, web-based Markdown editor that allows you to create notes, graphs, and diagrams in your browser.
17
+
[HedgeDoc](https://hedgedoc.org/) is a collaborative, web-based Markdown editor that allows you to create notes, graphs, and diagrams in your browser. You can share a link to your documents with other members of your organization so you can collaborate in real time.
28
18
29
-
You can share a link to your document with other members of your organization so you can collaborate in real time.
19
+
## How to secure HedgeDoc with Pomerium
30
20
31
-
## Integrate Pomerium with HedgeDoc
21
+
HedgeDoc is an open-source project that you can serve behind a [reverse proxy](https://docs.hedgedoc.org/guides/reverse-proxy/).
32
22
33
-
HedgeDoc is an open-source, self-hosted software that allows you to configure authentication and authorization with a [reverse proxy](https://docs.hedgedoc.org/guides/reverse-proxy/).
23
+
In this guide, you'll configure Pomerium to authenticate and authorize users. To do this, you'll add an authorization policy that grants or denies access based on the policy criteria.
34
24
35
-
You can configure Pomerium so that it authenticates and authorizes users against an Identity Provider (IdP) before users can access HedgeDoc's services.
36
-
37
-
The flow looks like this:
38
-
39
-
1. User requests to access the secured app
40
-
2. Pomerium identifies user
41
-
3. Pomerium checks if user is authorized to access routes defined in the authorization [`policy`](https://www.pomerium.com/docs/reference/routes/policy)
42
-
4. If authorized, Pomerium authenticates user against IdP
43
-
5. After IdP establishes user's identity, Pomerium checks permissions against the secured app
44
-
6. User can make authorized requests in the secured app
This guide uses Docker containers to create the minimal development environment required to run Pomerium with another service. Visit the [Pomerium using Docker](https://www.pomerium.com/docs/quickstart) quickstart for more information.
This guide uses [GitHub](https://www.pomerium.com/docs/identity-providers/github) as the pre-configured IdP.
35
+
If you completed our [**Quickstart guide**](/docs/quickstart), you should have a working Pomerium project with the following YAML files:
64
36
65
-
:::
66
-
67
-
### Pomerium configuration
68
-
69
-
Your Pomerium configuration file must include a [Cookie Secret](https://www.pomerium.com/docs/reference/cookie-secret) and a [Secret Key](https://www.pomerium.com/docs/reference/signing-key).
37
+
-`config.yaml`
38
+
-`docker-compose.yaml`
70
39
71
-
To create a Cookie Secret, run the following command in your terminal:
72
-
73
-
```bash
74
-
head -c32 /dev/urandom | base64
75
-
```
40
+
If you haven't completed the Quickstart:
76
41
77
-
To create a Secret Key, run the following command:
78
-
79
-
```bash
80
-
cat ec_private.pem | base64
81
-
```
82
-
83
-
:::tip **Note**
84
-
85
-
This guide assumes you've generated self-signed wildcard certificates. Check [Certificates](https://www.pomerium.com/docs/topics/certificates#self-signed-wildcard-certificate) for more information.
42
+
- Create a `config.yaml` file for your Pomerium configuration
43
+
- Create a `docker-compose.yaml` file for your Docker configuration
86
44
87
45
:::
88
46
89
-
Place your `cookie_secret` and `secret_key` in your `config.yaml` file:
47
+
### Set up Pomerium
90
48
91
-
```yaml
92
-
cookie_secret: <cookie secret>
93
-
signing_key: <signing key>
94
-
```
95
-
96
-
Then, enable Pomerium to allow [Websocket Connections](https://www.pomerium.com/docs/reference/routes/timeouts#websocket-connections):
To see if Pomerium is configured correctly, run the following command in your terminal:
69
+
#### Create a wildcard TLS certificate
70
+
71
+
HedgeDoc requires an encrypted TLS connection to add and manage users. For the purposes of this guide, you will use `mkcert` to generate local development certificates:
72
+
73
+
1. Install `mkcert` with these [instructions](https://github.com/FiloSottile/mkcert#installation)
74
+
1. Create a trusted **rootCA**:
118
75
119
76
```bash
120
-
docker-compose up
77
+
mkcert -install
121
78
```
122
79
123
-
Navigate to `https://authenticate.localhost.pomerium.io`. Pomerium will redirect you to your GitHub OAuth app, where you can authorize the OAuth app to access your GitHub account.
80
+
1. Create a wildcard certificate for `*.localhost.pomerium.io`:
Update your environment variables with the following values:
143
+
> See the [HedgeDoc - Configuration](https://docs.hedgedoc.org/configuration/#configuration) page for more information on configuration keys and environment variables.
144
+
145
+
#### Generate a session secret
146
+
147
+
HedgeDoc requires a session secret to sign session cookies. If you don't add a session secret, HedgeDoc generates a random one for you upon startup, which will end any active sessions and sign out your users.
148
+
149
+
Adding a session secret will allow you to resume a session even if you stop your Docker services.
150
+
151
+
To generate a secret, run:
152
+
153
+
```shell-session
154
+
$ head -c32 /dev/urandom | base64
155
+
MPGHgArlo81ohUoMtDtv8qCBLJu0lwXDCPcrml0wF2Q=
156
+
```
157
+
158
+
Replace the value of `CMD_SESSION_SECRET` with the output:
0 commit comments