diff --git a/content/docs/guides/img/tiddlywiki/enterprise-tiddlywiki-jwt-headers.png b/content/docs/guides/img/tiddlywiki/enterprise-tiddlywiki-jwt-headers.png new file mode 100644 index 000000000..0faeb1d1a Binary files /dev/null and b/content/docs/guides/img/tiddlywiki/enterprise-tiddlywiki-jwt-headers.png differ diff --git a/content/docs/guides/img/tiddlywiki/tiddlywiki-enterprise-policy.png b/content/docs/guides/img/tiddlywiki/tiddlywiki-enterprise-policy.png new file mode 100644 index 000000000..0831b180e Binary files /dev/null and b/content/docs/guides/img/tiddlywiki/tiddlywiki-enterprise-policy.png differ diff --git a/content/docs/guides/img/tiddlywiki/tiddlywiki-enterprise-route.png b/content/docs/guides/img/tiddlywiki/tiddlywiki-enterprise-route.png new file mode 100644 index 000000000..abe6244f6 Binary files /dev/null and b/content/docs/guides/img/tiddlywiki/tiddlywiki-enterprise-route.png differ diff --git a/content/docs/guides/img/tiddlywiki/tiddlywiki-first-note.png b/content/docs/guides/img/tiddlywiki/tiddlywiki-first-note.png new file mode 100644 index 000000000..a9423d6fc Binary files /dev/null and b/content/docs/guides/img/tiddlywiki/tiddlywiki-first-note.png differ diff --git a/content/docs/guides/img/tiddlywiki/tiddlywiki-policy-builder.png b/content/docs/guides/img/tiddlywiki/tiddlywiki-policy-builder.png deleted file mode 100644 index a3cdfdbe1..000000000 Binary files a/content/docs/guides/img/tiddlywiki/tiddlywiki-policy-builder.png and /dev/null differ diff --git a/content/docs/guides/img/tiddlywiki/tiddlywiki-route.png b/content/docs/guides/img/tiddlywiki/tiddlywiki-route.png deleted file mode 100644 index 9d2ce8b1b..000000000 Binary files a/content/docs/guides/img/tiddlywiki/tiddlywiki-route.png and /dev/null differ diff --git a/content/docs/guides/img/tiddlywiki/tiddlywiki-settings.png b/content/docs/guides/img/tiddlywiki/tiddlywiki-settings.png deleted file mode 100644 index e11506bce..000000000 Binary files a/content/docs/guides/img/tiddlywiki/tiddlywiki-settings.png and /dev/null differ diff --git a/content/docs/guides/tiddlywiki.mdx b/content/docs/guides/tiddlywiki.mdx index 218e3fb77..422ca72df 100644 --- a/content/docs/guides/tiddlywiki.mdx +++ b/content/docs/guides/tiddlywiki.mdx @@ -3,10 +3,9 @@ title: Securing TiddlyWiki on Node.js sidebar_label: TiddlyWiki lang: en-US keywords: [pomerium, identity access proxy, wiki, tiddlywiki] -description: This guide covers how to add authentication and authorization to a hosted online instance of TiddlyWiki. +description: This guide shows you how to configure an authorization policy and SSO to control access to an online instance of Tiddlywiki with Pomerium. --- -import DockerCompose from '../../examples/tiddlywiki/docker-compose.yaml.md'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; @@ -16,117 +15,197 @@ Learn how to add authentication and authorization to an instance of [TiddlyWiki ## What is TiddlyWiki on Node.js -TiddlyWiki is a personal wiki and a non-linear notebook for organizing and sharing complex information. It is available in two forms: +TiddlyWiki is a personal wiki and a non-linear web notebook for organizing and sharing information. -- a single HTML page -- [a Node.js application](https://www.npmjs.com/package/tiddlywiki) +It is available in two forms: -You will use the Node.js application in this guide. +- As a single HTML page +- As a [Node.js application](https://www.npmjs.com/package/tiddlywiki) -## Authentication with Pomerium +In this guide, you will run Pomerium and your TiddlyWiki Node.js application in Docker containers. -TiddlyWiki allows you to authenticate users with the 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#identity-provider-configuration) (IdP). +## How you will secure TiddlyWiki -Pomerium can forward specific user session data to upstream applications. In the case of this guide, Pomerium will forward the email associated with your IdP to TiddlyWiki. +Securing access to TiddlyWiki involves two steps: -## Set up your environment +- 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](https://tiddlywiki.com/static/ListenCommand.html) 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](/docs/quickstart), you should have a working Pomerium project with the following YAML files: -To complete this guide, you need: +- `config.yaml` +- `docker-compose.yaml` -- [Docker](https://www.docker.com/) -- [Docker Compose](https://docs.docker.com/compose/install/) +If you haven't completed the Quickstart: -Refer to the [quick-start] guide for more information on how to run Pomerium Core with Docker and Docker Compose. +- Install [Docker](https://www.docker.com/) and [Docker Compose](https://docs.docker.com/compose/install/) +- Create a `config.yaml` file for your Pomerium configuration +- Create a `docker-compose.yaml` file for your Docker configuration -### Configure Pomerium +### Set up Pomerium Add the following code in your `config.yaml` file: ```yaml title="config.yaml" -jwt_claims_headers: email +authenticate_service_url: https://authenticate.pomerium.app + +jwt_claims_headers: + X-Pomerium-Claim-Email: email + routes: - - from: https://wiki.example.local + - from: https://wiki.localhost.pomerium.io to: http://tiddlywiki:8080 + pass_identity_headers: true policy: - allow: - or: - - email: - is: reader@example.com + and: - email: - is: writer@example.com + # Replace with your email address + is: user@example.com ``` -The [`jwt_claims_header`](/docs/reference/jwt-claim-headers) forwards the email associated with your IdP in the HTTP request header to TiddlyWiki. +Let's review the configuration file: -In the policy above, the emails specified (`reader@example.com` and `writer@example.com`) will be forwarded to TiddlyWiki. +- The [`jwt_claims_headers`](/docs/reference/jwt-claim-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`](/docs/reference/routes/pass-identity-headers-per-route) 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. -### Configure Docker-Compose +### Set up Docker Compose services Add the following code in your `docker-compose.yaml` file: - +```yaml title="docker-compose.yaml" +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 +``` -Here is what the code is doing: +Before you test your services, make sure the value of `authenticated-user-header` matches the value of the custom header defined in `config.yaml`. -- `mywiki --listen host=0.0.0.0` starts the TiddlyWiki server, and maps ports `0.0.0.0` and `8080` -- `authenticated-user-header=x-pomerium-claim-email` enables Tiddlywiki to receive the user's email address from Pomerium -- `readers` and `writers` authorizes users to read and/or write to the TiddlyWiki server -- `username` and `password` specify which user can access TiddlyWiki in a session; excluding these variables will result in a `401` error +**Run Docker Compose:** -Run `docker-compose up`. +```bash +docker compose up +``` - + + +The Enterprise path to this guide requires a **Pomerium Enterprise** account and administrator access to an Enterprise Console instance. + +It also assumes you are using [Docker](https://www.docker.com/) and [Docker Compose](https://docs.docker.com/compose/install/) to run your services. + +## Set up TiddlyWiki -In your Console, create a policy: +:::enterprise -1. Enter a **Name** (e.g. 'Allow Authenticated Users') -2. Select **Builder**, **ADD ALLOW BLOCK** -3. Select **+** and add an **OR** operator -4. Under the **Criteria** dropdown, select **Email** -5. In the **Value** field, enter **reader@example.com** -6. Select **+** and repeat step 5, but enter **writer@example.com** instead. +The Docker Compose example below contains the minimal configuration required to run TiddlyWiki. It does not include the configuration for Pomerium Enterprise. + +For an example Pomerium Enterprise configuration using Docker Compose, see the [**Enterprise Quickstart**](/docs/deploy/enterprise/quickstart) guide. + +::: + +In your `docker-compose.yaml` file, add the TiddlyWiki configuration: + +```yaml title="docker-compose.yaml" +services: + 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 +``` + +## Create a policy + +1. In the **Builder** tab, select **ADD ALLOW BLOCK** +1. Select the **AND** operator +1. Select **Email** as the criteria and **Is** as the operator +1. Enter the email address you will authenticate with as the value Save your policy. -![Build TiddlyWiki policy](img/tiddlywiki/tiddlywiki-policy-builder.png) +![Building a policy for TiddlyWiki in the Enterprise Console](./img/tiddlywiki/tiddlywiki-enterprise-policy.png) -Create a route: +## Create a route -1. Enter a **Name** (e.g. 'TiddlyWiki') -2. In the **From** field, enter the externally accessible URL (e.g. `https://wiki.localhost.pomerium.io`) -3. In the **To** field, enter the host name (e.g. `http://tiddlywiki:8080`) -4. Under **Policies**, select **Add Authenticated Users** -5. Select **Pass Identity Headers** +1. Add a new route and enter a **Name** +1. In **From**, enter the externally accessible URL +1. In **To**, enter the internally accessible URL +1. Add the policy for this route (for example, `TiddlyWiki`) +1. Enable **Pass Identity Headers** Save your route. -![Create TiddlyWiki route](img/tiddlywiki/tiddlywiki-route.png) +![Adding the TiddlyWiki route and attaching its policy in the Enterprise Console](./img/tiddlywiki/tiddlywiki-enterprise-route.png) -Configure your settings to send JWT claims headers to the upstream application: +## Set identity headers -1. Under **Settings**, select **Proxy** -2. In the **Header Key** field, enter **X-Pomerium-Claim** -3. In the **JWT Claim** field, enter **Email** +1. In the sidebar under **CONFIGURE**, select **Settings** +1. Select the **Proxy** tab +1. In **JWT Claim Headers**, enter the header and expected claim Save your settings. -![Configure settings](img/tiddlywiki/tiddlywiki-settings.png) +![Configuring JWT Claim Headers to forward the email claim as an identity header in the Enterprise Console](./img/tiddlywiki/enterprise-tiddlywiki-jwt-headers.png) - -### Test your routes +## Test TiddlyWiki + +In your browser, navigate to your TiddlyWiki instance. Pomerium will prompt you to authenticate against its hosted identity provider. -Navigate to your TiddlyWiki instance (e.g. `https://wiki.example.local`) and log in using the following usernames: +After successful authentication, Pomerium will redirect you to your TiddlyWiki instance: -- If you log in as `reader@example.com`, you can only read tiddlers -- If you log in as `writer@example.com`, you can read and write tiddlers -- If you log in as `user@example.com`, you will receive a 401 error +![Adding a note in the TiddlyWiki dashboard](./img/tiddlywiki/tiddlywiki-first-note.png) -[quick-start]: /docs/quickstart +Great job! You successfully secured TiddlyWiki behind Pomerium. diff --git a/content/examples/tiddlywiki/README.md b/content/examples/tiddlywiki/README.md deleted file mode 100644 index d6fcdd332..000000000 --- a/content/examples/tiddlywiki/README.md +++ /dev/null @@ -1,16 +0,0 @@ -# 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 `email.is` 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/content/examples/tiddlywiki/config.yaml b/content/examples/tiddlywiki/config.yaml deleted file mode 100644 index 542c8742d..000000000 --- a/content/examples/tiddlywiki/config.yaml +++ /dev/null @@ -1,20 +0,0 @@ -authenticate_service_url: https://authenticate.localhost.pomerium.io -autocert: true -autocert_use_staging: true -idp_provider: google -idp_client_id: REPLACE_ME -idp_client_secret: REPLACE_ME - -cookie_secret: REPLACE_ME -jwt_claims_headers: email - -policy: - - from: https://wiki.localhost.pomerium.io - to: http://tiddlywiki:8080 - policy: - - allow: - or: - - email: - is: reader@example.com - - email: - is: writer@example.com diff --git a/content/examples/tiddlywiki/docker-compose.yaml.md b/content/examples/tiddlywiki/docker-compose.yaml.md deleted file mode 100644 index af5233187..000000000 --- a/content/examples/tiddlywiki/docker-compose.yaml.md +++ /dev/null @@ -1,36 +0,0 @@ -```yaml title="docker-compose.yaml" -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=reader@example.com - - writers=writer@example.com - - username= - - password=password - depends_on: - - tiddlywiki_init -```