diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 723ba779e..f884bf101 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -150,7 +150,7 @@ module.exports = { collapsable: false, sidebarDepth: 1, - children: ["", "ad-guard", "cloud-run", "vs-code-server", "kubernetes", "argo", "mtls", "local-oidc"], + children: ["", "ad-guard", "cloud-run", "vs-code-server", "kubernetes", "argo", "mtls", "local-oidc", "tiddlywiki"], }, ], "/enterprise/": [ diff --git a/docs/recipes/readme.md b/docs/recipes/readme.md index 48fad0439..ee89ccaeb 100644 --- a/docs/recipes/readme.md +++ b/docs/recipes/readme.md @@ -9,3 +9,4 @@ This section contains applications, and scenario specific guides for Pomerium. - The [argo](./argo.md) guide demonstrates how pomerium can be used to add access control to [Argo](https://argoproj.github.io/projects/argo). - The [mTLS](./mtls.md) guide demonstrates how pomerium can be used to add mutual authentication using client certificates and a custom certificate authority. - The [local OIDC](./local-oidc.md) guide demonstrates how pomerium can be used with local OIDC server for dev/testing. +- The [TiddlyWiki](./tiddlywiki.md) guide demonstrates how pomerium can be used to add authentication and authorization to web application using authenticated header. diff --git a/docs/recipes/tiddlywiki.md b/docs/recipes/tiddlywiki.md new file mode 100644 index 000000000..359a6f72b --- /dev/null +++ b/docs/recipes/tiddlywiki.md @@ -0,0 +1,59 @@ +--- +title: TiddlyWiki +lang: en-US +meta: + - name: keywords + content: pomerium identity-access-proxy wiki tiddlywiki +description: >- + This guide covers how to add authentication and authorization to a hosted, fully, online instance of TiddlyWiki. +--- + +# Securing TiddlyWiki on Node.js + +This guide covers using Pomerium to add authentication and authorization to an instance of [TiddlyWiki on NodeJS](https://tiddlywiki.com/static/TiddlyWiki%2520on%2520Node.js.html). + +## What is TiddlyWiki on Node.js + +TiddlyWiki is a personal wiki and a non-linear notebook for organising and sharing complex information. It is available in two forms: + +- a single HTML page +- [a Node.js application](https://www.npmjs.com/package/tiddlywiki) + +We are using the Node.js application in this guide. + +## Where Pomerium fits + +TiddlyWiki allows a simple form of authentication by using authenticated-user-header parameter of [listen command](https://tiddlywiki.com/static/ListenCommand.html). Pomerium provides the ability to login with well-known [identity providers](../docs/identity-providers/readme.md#identity-provider-configuration). + +## Pre-requisites + +This guide assumes you have already completed one of the [quick start] guides, and have a working instance of Pomerium up and running. For purpose of this guide, We will use docker-compose, though any other deployment method would work equally well. + +## Configure + +### Pomerium Config + +```yaml +jwt_claims_headers: email +policy: +- from: https://wiki.example.local + to: http://tiddlywiki:8080 + allowed_users: + - reader1@example.com + - writer1@example.com +``` +### Docker-compose + +<<< @/examples/tiddlywiki/docker-compose.yaml + +### That's it + +Navigate to your TiddlyWiki instance (e.g. `https://wiki.example.local`) and log in: + +* as reader1@example.com: user can read the wiki, but there is no create new tiddler button is show up. + +* as writer1@example.com: user can read the wiki and create new tiddlers. + +* as another email: pomerium displays a permission denied error. + +[quick start]: ../docs/quick-start diff --git a/examples/tiddlywiki/REAME.md b/examples/tiddlywiki/REAME.md new file mode 100644 index 000000000..13c4e8800 --- /dev/null +++ b/examples/tiddlywiki/REAME.md @@ -0,0 +1,16 @@ +# Pomerium as auth proxy for TiddlyWiki + +Run this demo locally on your docker-compose capable workstation, or replace `localhost.pomerium.io` with your own domain if running on a server. + +## Includes + +- Authentication and Authorization managed by pomerium + +## How + +- Update `config.yaml` for your e-mail address, if not using gmail/google. +- Replace secrets in `config.yaml`. +- Replace allowed_users in `config.yaml` +- Configure read-only or writer users by changing readers and writers parameter of tiddlywiki in `docker-compose.yaml`. +- Run `docker-compose up` from this directory. +- Navigate to `https://wiki.localhost.pomerium.io` diff --git a/examples/tiddlywiki/config.yaml b/examples/tiddlywiki/config.yaml new file mode 100644 index 000000000..c7660333f --- /dev/null +++ b/examples/tiddlywiki/config.yaml @@ -0,0 +1,16 @@ +authenticate_service_url: https://authenticate.localhost.pomerium.io +autocert: true +autocert_use_staging: true +idp_provider: google +idp_client_id: REPLACEME +idp_client_secret: REPLACEME + +cookie_secret: REPLACEME +jwt_claims_headers: email + +policy: + - from: https://wiki.localhost.pomerium.io + to: http://tiddlywiki:8080 + allowed_users: + - writer1@example.com + - reader1@example.com diff --git a/examples/tiddlywiki/docker-compose.yaml b/examples/tiddlywiki/docker-compose.yaml new file mode 100644 index 000000000..118313cae --- /dev/null +++ b/examples/tiddlywiki/docker-compose.yaml @@ -0,0 +1,32 @@ +version: "3" + +services: + pomerium: + image: pomerium/pomerium:latest + volumes: + # Use a volume to store ACME certificates + - ./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 + - readers=reader1@example.com + - writers=writer1@example.com + depends_on: + - tiddlywiki_init