HedgeDoc
Use Pomerium to secure access to HedgeDoc by providing identity and context.
What is HedgeDoc?
HedgeDoc 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 document with other members of your organization so you can collaborate in real time.
Integrate Pomerium with HedgeDoc
HedgeDoc is an open-source, self-hosted software that allows you to configure authentication and authorization with a reverse proxy.
You can configure Pomerium so that it authenticates and authorizes users against an Identity Provider (IdP) before users can access HedgeDoc's services.
The flow looks like this:
- User requests to access the secured app
- Pomerium identifies user
- Pomerium checks if user is authorized to access routes defined in the authorization
policy
- If authorized, Pomerium authenticates user against IdP
- After IdP establishes user's identity, Pomerium checks permissions against the secured app
- User can make authorized requests in the secured app
Set up your environment
This guide uses Docker containers to create the minimal development environment required to run Pomerium with another service. Visit the Pomerium using Docker quickstart for more information.
To complete this guide, you need:
- Docker
- Docker Compose
- A running Pomerium instance
- A pre-configured IdP
Note
This guide uses GitHub as the pre-configured IdP.
Pomerium configuration
Your Pomerium configuration file must include a Cookie Secret and a Secret Key.
To create a Cookie Secret, run the following command in your terminal:
head -c32 /dev/urandom | base64
To create a Secret Key, run the following command:
cat ec_private.pem | base64
This guide assumes you've generated self-signed wildcard certificates. Check Certificates for more information.
Place your cookie_secret
and secret_key
in your config.yaml
file:
cookie_secret: <cookie secret>
signing_key: <signing key>
Then, enable Pomerium to allow Websocket Connections:
allow_websockets: true
Lastly, define your routes:
routes:
- from: https://verify.localhost.pomerium.io
to: http://verify:8000
pass_identity_headers: true
allow_any_authenticated_user: true
- from: https://hedgedoc.localhost.pomerium.io
to: http://app:3000
pass_identity_headers: true
allow_any_authenticated_user: true
To see if Pomerium is configured correctly, run the following command in your terminal:
docker-compose up
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.
Navigate to https://authenticate.localhost.pomerium.io/.pomerium/
to see your User Details:
Congratulations! You've successfully configured and run Pomerium.
Secure HedgeDoc
In your docker-compose.yaml
file, add the following code under your Pomerium services:
# verify:
# image: pomerium/verify:latest
# expose:
# - 8000
---
database:
image: postgres:13.4-alpine
environment:
- POSTGRES_USER=hedgedoc
- POSTGRES_PASSWORD=password
- POSTGRES_DB=hedgedoc
volumes:
- database:/var/lib/postgresql/data
restart: always
app:
# Make sure to use the latest release from https://hedgedoc.org/latest-release
image: quay.io/hedgedoc/hedgedoc:1.9.4
environment:
- CMD_DB_URL=postgres://hedgedoc:password@database:5432/hedgedoc
- CMD_DOMAIN=hedgedoc.localhost.pomerium.io
- CMD_URL_ADDPORT=false
- CMD_EMAIL=true
- CMD_ALLOW_EMAIL_REGISTER=true
- CMD_SESSION_SECRET=<session secret>
volumes:
- uploads:/hedgedoc/public/uploads
ports:
- "3000:3000"
restart: always
depends_on:
- database
volumes:
database:
uploads:
Update your environment variables with the following values:
- CMD_DOMAIN=hedgedoc.localhost.pomerium.io
You must add a session secret. If you don't, HedgeDoc will randomly generate a secret, which will log out all users.
To generate a session secret, run the following command in your terminal:
head -c32 /dev/urandom | base64
Now, run docker-compose up
Navigate to https://hedgedoc.localhost.pomerium.io/
to access HedgeDoc:
Great job! You've secured HedgeDoc using Pomerium's identity-aware proxy.