3pp-mirror/pomerium
1
0
Fork 0
mirror of https://github.com/pomerium/pomerium.git synced 2025-04-29 18:36:30 +02:00
Code Issues Projects Releases Packages Wiki Activity

Docs backporting (#2351)

Browse source 
* fix Transmission sorting in sidebar

* rename VSCode Server for alphabetizing and clarity

* Transmission BitTorrent Client Guide (#2281)

* init transmission guide

* Update docs/guides/transmission.md

Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>

* Update docs/guides/transmission.md

Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>

* Update docs/guides/transmission.md

Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>

Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>

* update installation source for mkcert (#2340)

* Docs sorting (#2346)

* fix Transmission sorting in sidebar

* rename VSCode Server for alphabetizing and clarity

* capitalize Pomerium

* Update docs/guides/code-server.md

Co-authored-by: Joe Previte <jjprevite@gmail.com>

* fix naming and sorting for coder-server, add description

Co-authored-by: Joe Previte <jjprevite@gmail.com>

* Docs sorting (#2346)

* fix Transmission sorting in sidebar

* rename VSCode Server for alphabetizing and clarity

* capitalize Pomerium

* Update docs/guides/code-server.md

Co-authored-by: Joe Previte <jjprevite@gmail.com>

* fix naming and sorting for coder-server, add description

Co-authored-by: Joe Previte <jjprevite@gmail.com>

* fix code-server title

Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>
Co-authored-by: Joe Previte <jjprevite@gmail.com>
This commit is contained in:
Alex Fornuto 2021-07-12 10:51:08 -05:00 • committed by GitHub
parent 52ec748836
commit 7e55f51738
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 124 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
docs/.vuepress/config.js
View file

@ -157,6 +157,7 @@ module.exports = {
"ad-guard",
"argo",
"cloud-run",
"code-server",
"istio",
"jwt-verification",
"kubernetes",
@ -167,7 +168,7 @@ module.exports = {
"tcp",
"tiddlywiki",
"traefik-ingress",
"code-server",
"transmission",
],
},
],

2
docs/docs/topics/certificates.md
View file

@ -52,7 +52,7 @@ In production, we'd use a public certificate authority such as LetsEncrypt. But
```bash
# Install mkcert.
go get -u github.com/FiloSottile/mkcert
go get -u filippo.io/mkcert
# Bootstrap mkcert's root certificate into your operating system's trust store.
mkcert -install
# Create your wildcard domain.

BIN
docs/guides/img/transmission-demo.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 45 KiB

17
docs/guides/readme.md
View file

@ -2,13 +2,14 @@
This section contains applications, and scenario specific guides for Pomerium.
- The [ad-guard](./ad-guard.md) recipe demonstrates how pomerium can be used to augment web applications that only support simplistic authorization mechanisms like basic-auth with single-sign-on driven access policy.
- The [argo](./argo.md) guide demonstrates how pomerium can be used to add access control to [Argo](https://argoproj.github.io/projects/argo).
- The [Cloud Run](./cloud-run.md) recipe demonstrates deploying pomerium to Google Cloud Run as well as using it to Authorize users to protected Cloud Run endpoints.
- The [ad-guard](./ad-guard.md) recipe demonstrates how Pomerium can be used to augment web applications that only support simplistic authorization mechanisms like basic-auth with single-sign-on driven access policy.
- The [argo](./argo.md) guide demonstrates how Pomerium can be used to add access control to [Argo](https://argoproj.github.io/projects/argo).
- The [Cloud Run](./cloud-run.md) recipe demonstrates deploying Pomerium to Google Cloud Run as well as using it to Authorize users to protected Cloud Run endpoints.
- The [code-server](./code-server.md) guide demonstrates how Pomerium can be used to add access control to third-party applications that don't ship with [fine-grained access control](https://github.com/cdr/code-server/issues/905). code-server is a tool to run Visual Studio code as a web application.
- The [JWT Verification](./jwt-verification.md) guide demonstrates how to verify the Pomerium JWT assertion header using Envoy.
- The [Kubernetes Dashboard](./kubernetes-dashboard.md) guide covers how to secure Kubernetes dashboard using Pomerium.
- The [kubernetes](./kubernetes.md) guide covers how to add authentication and authorization to kubernetes dashboard using helm, and letsencrypt certificates. This guide also shows how third party reverse-proxies like nginx/traefik can be used in conjunction with pomerium using forward-auth.
- The [local OIDC](./local-oidc.md) guide demonstrates how pomerium can be used with local OIDC server for dev/testing.
- The [mTLS](./mtls.md) guide demonstrates how pomerium can be used to add mutual authentication using client certificates and a custom certificate authority.
- The [TiddlyWiki](./tiddlywiki.md) guide demonstrates how pomerium can be used to add authentication and authorization to web application using authenticated header.
- The [visual studio code](./vs-code-server.md) guide demonstrates how pomerium can be used to add access control to third-party applications that don't ship with [fine-grained access control](https://github.com/cdr/code-server/issues/905).
- The [kubernetes](./kubernetes.md) guide covers how to add authentication and authorization to kubernetes dashboard using helm, and letsencrypt certificates. This guide also shows how third party reverse-proxies like nginx/traefik can be used in conjunction with Pomerium using forward-auth.
- The [local OIDC](./local-oidc.md) guide demonstrates how Pomerium can be used with local OIDC server for dev/testing.
- The [mTLS](./mtls.md) guide demonstrates how Pomerium can be used to add mutual authentication using client certificates and a custom certificate authority.
- The [TiddlyWiki](./tiddlywiki.md) guide demonstrates how Pomerium can be used to add authentication and authorization to web application using authenticated header.
- The [Transmission](./transmission.md) guide demonstrates how Pomerium can act as an authentication and authorization proxy for your Transmission daemon's RPC interface, which only provides unencrypted HTTP auth out of the box.

112
docs/guides/transmission.md Normal file
View file

@ -0,0 +1,112 @@
---
title: Transmission
lang: en-US
meta:
- name: keywords
content: >-
pomerium bittorrent torrent pomerium identity-access-proxy transmission-daemon transmission authentication authorization
description: >-
Learn how to use Pomerium as an authentication and authorization proxy for a Transmission torrent daemon.
---
# Securing Transmission's RPC interface.
This guide demonstrates how Pomerium can secure a [Transmission] daemon. Pomerium is an identity-aware access proxy that can add single-sign-on / access control to any service.
## Transmission
[Transmission] is a powerful BitTorrent client that's highly customizable. It's often run remotely as a system daemon, and interacted with through a remote client using a [Remote Procedure Call](https://en.wikipedia.org/wiki/Remote_procedure_call) (**RPC**) interface.
The BitTorrent protocol is widely used in the distribution of large open-source softwares, like Linux distribution images and source code. Using Transmission as a system daemon, you can monitor and automatically download the latest versions to a local distribution server.
While there are software clients available to interact with the daemon over RPC, the easiest option is often to use the web interface built into the Transmission daemon package. Unfortunately, the service is only built to communicate over unencrypted HTTP, using basic [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication). Using Pomerium, we can encrypt traffic from anywhere in the world to the local network hosting the Transmission service, and restrict access to authenticated users.
::: warning
Because RPC traffic to and from a Transmission daemon is unencrypted, we strongly suggest you only communicate from Pomerium to Transmission on a trusted private network. Note that some cloud hosting providers differentiate "private networking" (which is visible to all hosts in a data center) from "VLANS" which are only visible to your hosts. While you can configure a local proxy on your Transmission host to provide TLS encryption, that configuration is outside of the scope of this guide.
Running Pomerium and Transmission on the same host, using [docker](../docs/quick-start) for example, negates this concern.
:::
## Before You Begin
This guide assumes you've completed one of the [quick start] guides, and have a running instance of Pomerium configured. This guide also assumes that Pomerium and Transmission will both run on separate hosts (physical or virtual machines) on the same private network (LAN or VLAN), but the configuration could be easily adjusted to fit your setup.
In addition to a working instance of Pomerium, have ready the [private IP addresses](https://en.wikipedia.org/wiki/Private_network#Private_IPv4_addresses) for the Pomerium and Transmission hosts. If you're running both on the same host, you can substitute `localhost` for both.
## Configuration
### Pomerium Config
Edit your `config.yaml` file to add the following policy. Note that `<>` denotes placeholder values that must be replaced if copying this config directly:
```yml
policy:
- from: https://<transmission.mydomain.com> # Replace with the domain you want to use to access Transmission
to: http://<private.ip.address>:9091 # Replace with the private network address of the Transmission host, or `localhost` if running on the same host.
allowed_users:
- myUser@mydomain.com # Replace with authorized user(s), or remove if using group permissions only.
allowed_groups:
- <transmission-users> # Replace with authorized user group(s), or remove if using user permissions only.
```
Remember to restart the Pomerium instance after saving your changes.
### Transmission Config
:::tip
Don't forget to switch your terminal prompt to the Transmission host before continuing.
:::
1. If you don't already have the Transmission daemon installed, install it through your distro's package manager. The commands to install and configure Transmission below assume a Debian-based Linux distribution, but can be adapted for any Linux distro:
```bash
sudo apt update && sudo apt install transmission-daemon
```
1. Because Transmission writes over its configuration file when running, stop the service before continuing:
```bash
sudo systemctl stop transmission-daemon.service
```
1. In your preferred text editor, open `/etc/transmission-daemon/settings.json` with `sudo` or as the root user. Look for the following key/value pairs, and edit appropriately.
- Because we are using Pomerium to authenticate, disable HTTP auth:
```json
"rpc-authentication-required": false,
```
- Confirm that RPC is enabled:
```json
"rpc-enabled": true,
```
- Enable and configure the RPC Host whitelist. This ensures that the service will only work when accessed from the domain defined in Pomerium's `config.yaml` file (the `policy.from` key). This helps to mitigate DNS hijacking attack vectors:
```json
"rpc-host-whitelist": "<transmission.mydomain.com>",
"rpc-host-whitelist-enabled": true,
```
- Enable and configure the RPC whitelist to only allow access from the Pomerium gateway. The value should be the private IP address of the Pomerium host, or `localhost` if running on the same host:
```json
"rpc-whitelist": "<pomerium.host.address>",
"rpc-whitelist-enabled": true,
```
1. After saving and closing `settings.json`, restart the service:
```bash
sudo systemctl start transmission-daemon.service
```
You should now be able to authenticate and access your Transmission daemon remotely in the web browser, with TLS encryption!
![The Transmission web interface, secured with Pomerium](./img/transmission-demo.png)
In addition to the lock symbol in your browser's address bar, you can go to `<transmission.mydomain.com>/.pomerium` to view and confirm your session details.
[Transmission]: https://transmissionbt.com/
[quick start]: ../docs/quick-start