Securing TiddlyWiki with Pomerium

This guide will show you how to add authentication and authorization to an instance of TiddlyWiki on NodeJS with Pomerium. Note that Pomerium can secure any web application, so the steps within can be easily replicated for your web app of choice.

What is TiddlyWiki on Node.js

TiddlyWiki is a personal wiki and a non-linear web notebook for organizing and sharing information.

It is available in two forms:

• As a single HTML page
• As a Node.js application

In this guide, you will run Pomerium and your TiddlyWiki Node.js application in Docker containers.

How you will secure TiddlyWiki

Securing access to TiddlyWiki involves two steps:

• Configuring Pomerium to forward specific user session data in an unsigned header to TiddlyWiki
• Configuring TiddlyWiki to accept a special request header for trusted authentication

In this way, you can implement single sign-on (SSO) for your TiddlyWiki instance, which means an authorized user only needs to authenticate once to access the application.

To configure TiddlyWiki, you'll set its ListenCommand to use the authenticated-user-header parameter. You'll configure Pomerium to forward the user's email claim in an unsigned header to TiddlyWiki.

Before you start

If you completed our Quickstart guide, you should have a working Pomerium project with the following YAML files:

• config.yaml
• docker-compose.yaml

If you haven't completed the Quickstart:

• Install Docker and Docker Compose
• Create a config.yaml file for your Pomerium configuration
• Create a docker-compose.yaml file for your Docker configuration

Set up Pomerium

Add the following code in your config.yaml file:

authenticate_service_url: https://authenticate.pomerium.app

jwt_claims_headers:
  X-Pomerium-Claim-Email: email

routes:
  - from: https://wiki.localhost.pomerium.io
    to: http://tiddlywiki:8080
    pass_identity_headers: true
    policy:
      - allow:
          and:
            - email:
                # Replace with your email address
                is: user@example.com

Let's review the configuration file:

• The jwt_claims_headers setting will forward the user's email address in an unsigned, HTTP request header. The header follows the custom format specified in the file (in this case, X-Pomerium-Claim-Email).
• The pass_identity_headers setting tells Pomerium to forward all identity headers to the upstream application
• The attached policy authorizes users with a matching email address to access TiddlyWiki. Pomerium will forward the address specified in the policy to TiddlyWiki as an unsigned identity header.

Set up Docker Compose services

Add the following code in your docker-compose.yaml file:

version: '3'
services:
  pomerium:
    image: cr.pomerium.com/pomerium/pomerium:latest
    volumes:
      - ./config.yaml:/pomerium/config.yaml:ro
    ports:
      - 443:443

  tiddlywiki_init:
    image: elasticdog/tiddlywiki:latest
    volumes:
      - ./wiki:/tiddlywiki
    command: ['mywiki', '--init', 'server']

  tiddlywiki:
    image: elasticdog/tiddlywiki:latest
    ports:
      - 8080:8080
    volumes:
      - ./wiki:/tiddlywiki
    command:
      - mywiki
      - --listen
      - host=0.0.0.0
      - authenticated-user-header=X-Pomerium-Claim-Email
    depends_on:
      - tiddlywiki_init

Before you test your services, make sure the value of authenticated-user-header matches the value of the custom header defined in config.yaml.

Run Docker Compose:

docker compose up

Test TiddlyWiki

In your browser, navigate to your TiddlyWiki instance. Pomerium will prompt you to authenticate against its hosted identity provider.

After successful authentication, Pomerium will redirect you to your TiddlyWiki instance:

Great job! You successfully secured TiddlyWiki behind Pomerium.

Want to secure something else instead? Check out our guides, or if it's not there, reach out on our forums!