docs: add certificate section (#96)

Closes #88

docs/.vuepress/config.js

@@ -7,8 +7,8 @@ module.exports = {
 			hostname: 'https://www.pomerium.io'
 		},
 		'@vuepress/google-analytics': {
-            ga: 'UA-129872447-2'
-        }
+			ga: 'UA-129872447-2'
+		}
 	},
 	themeConfig: {
 		repo: "pomerium/pomerium",
@@ -17,12 +17,15 @@ module.exports = {
 		editLinkText: "Edit this page on GitHub",
 		lastUpdated: "Last Updated",
 		nav: [
+			{ text: "Documentation", link: "/docs/" },
 			{ text: "Quick Start", link: "/guide/" },
-			{ text: "Documentation", link: "/docs/" }
+			{ text: "Config Reference", link: "/reference/" }
+
 		],
 		sidebar: {
 			"/guide/": guideSidebar("Quick Start"),
 			"/docs/": docsSidebar("Documentation")
+
 		}
 	}
 };
@@ -42,7 +45,7 @@ function docsSidebar(title) {
 		{
 			title,
 			collapsable: false,
-			children: ["", "identity-providers", "signed-headers", "examples", "config-reference"]
+			children: ["", "identity-providers", "signed-headers", "certificates", "examples"]
 		}
 	];
 }

docs/docs/certificates.md

@@ -0,0 +1,131 @@
+---
+title: Certificates
+lang: en-US
+meta:
+  - name: keywords
+    content: x509 certificates tls mtls letsencrypt lets encrypt
+---
+
+# Certificates
+
+[Certificates](https://en.wikipedia.org/wiki/X.509) and [TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security) play a vital role in [zero-trust][principles] networks, and in Pomerium. This document covers how to generate and set up wild-card certificates suitable for working with pomerium.
+
+This guide uses the following tools and resources:
+
+- [LetsEncrypt](https://letsencrypt.org/about/) is a _public_ certificate authority that issues free certificates trusted by the major browsers. Other [private](https://blog.cloudflare.com/how-to-build-your-own-public-key-infrastructure/) or [public](https://scotthelme.co.uk/are-ev-certificates-worth-the-paper-theyre-written-on/) CAs would also be fine.
+- [Google Domains](https://domains.google.com/) registrar will be used to set up our wildcard domain and certificate validation. But any registrar would do and some providers support [automatic renewal](https://github.com/Neilpang/acme.sh/wiki/dnsapi).
+- [acme.sh](https://github.com/Neilpang/acme.sh) will be used to retrieve the wild-card domain certificate. Any [LetsEncrypt client](https://letsencrypt.org/docs/client-options/) that supports wildcard domains would work.
+
+It should be noted that there are countless ways of building and managing [public-key infrastructure](https://en.wikipedia.org/wiki/Public_key_infrastructure). And although we hope this guide serves as a helpful baseline for generating and securing pomerium with certificates, these instructions should be modified to meet your own organization's tools, needs, and constraints.
+
+::: warning
+
+LetsEncrypt certificates certificates must be renewed [every 90 days](https://letsencrypt.org/2015/11/09/why-90-days.html).
+
+:::
+
+## Why
+
+Since one of Pomerium's core [principles] is to treat internal and external traffic impartially, Pomerium uses [mutually authenticated TLS](https://en.wikipedia.org/wiki/Mutual_authentication) ubiquitously. For example, Pomerium uses mTLS between:
+
+- end-user and Pomerium
+- Pomerium's services **regardless** of if the network is "trusted"
+- Pomerium and the destination application
+
+## How
+
+First, you'll want to set a [CNAME](https://en.wikipedia.org/wiki/CNAME_record) record for wild-card domain name you will be using with Pomerium.
+
+![pomerium add a text entry to your dns records](./certificates/certificate-wildcard-domain.png)
+
+Once you've setup your wildcard domain, we can use acme.sh to create a certificate-signing request with LetsEncrypt.
+
+```bash
+# Requires acme.sh @ https://github.com/Neilpang/acme.sh
+# Install (after reviewing, obviously) by running : 
+# $ curl https://get.acme.sh | sh
+$HOME/.acme.sh/acme.sh \
+    --issue \
+    -k ec-256 \
+    -d '*.corp.example.com' \
+    --dns \
+    --yes-I-know-dns-manual-mode-enough-go-ahead-please
+
+Creating domain key
+The domain key is here: $HOME/.acme.sh/*.corp.example.com_ecc/*.corp.example.com.key
+Single domain='*.corp.example.com'
+Getting domain auth token for each domain
+Getting webroot for domain='*.corp.example.com'
+Add the following TXT record:
+Domain: '_acme-challenge.corp.example.com'
+TXT value: 'Yz0B1Uf2xjyUI7Cr9-k96P2PQnw3RIK32dMViuvT58s'
+Please be aware that you prepend _acme-challenge. before your domain
+so the resulting subdomain will be: _acme-challenge.corp.example.com
+Please add the TXT records to the domains, and re-run with --renew.
+Please check log file for more details: $HOME/.acme.sh/acme.sh.log
+Removing DNS records.
+Not Found domain api file:
+```
+
+LetsEncrypt will respond with the corresponding `TXT` record needed to verify our domain.
+
+![pomerium add a text entry to your dns records](./certificates/certificate-domain-challenge.png)
+
+It may take a few minutes for the DNS records to propagate. Once it does, you can run the following command to complete the certificate request process.
+
+```bash
+# Complete the certificate request now that we have validated our domain
+$HOME/.acme.sh/acme.sh \
+    --renew \
+    --ecc \
+    -k ec-256 \
+    -d '*.corp.example.com' \
+    --dns \
+    --yes-I-know-dns-manual-mode-enough-go-ahead-please
+
+Renew: '*.corp.example.com'
+Single domain='*.corp.example.com'
+Getting domain auth token for each domain
+Verifying: *.corp.example.com
+Success
+Verify finished, start to sign.
+Cert success.
+-----BEGIN CERTIFICATE-----
+.... snip... 
+-----END CERTIFICATE-----
+Your cert is in  $HOME/.acme.sh/*.corp.example.com_ecc/*.corp.example.com.cer
+Your cert key is in  $HOME/.acme.sh/*.corp.example.com_ecc/*.corp.example.com.key
+The intermediate CA cert is in  $HOME/.acme.sh/*.corp.example.com_ecc/ca.cer
+And the full chain certs is there:  $HOME/.acme.sh/*.corp.example.com_ecc/fullchain.cer
+```
+
+Here's how the above certificates signed by LetsEncrypt correspond to their respective Pomerium configuration settings:
+
+Pomerium Config             | Certificate file
+--------------------------- | --------------------------------------------------------------
+[CERTIFICATE]               | `$HOME/.acme.sh/*.corp.example.com_ecc/fullchain.cer`
+[CERTIFICATE_KEY]           | `$HOME/.acme.sh/*.corp.example.com_ecc/*.corp.example.com.key`
+[CERTIFICATE_AUTHORITY]     | `$HOME/.acme.sh/*.corp.example.com_ecc/ca.cer`
+[OVERRIDE_CERTIFICATE_NAME] | `*.corp.example.com`
+
+Your end users will see a valid certificate for all domains delegated by Pomerium.
+
+![pomerium valid certificate](./certificates/certificates-valid-secure-certificate.png)
+
+![pomerium certificates A+ ssl labs rating](./certificates/certificates-ssl-report.png)
+
+## Resources
+
+Certificates, TLS, and Public Key Cryptography is a vast subject we cannot adequately cover here so if you are new to or just need a brush up, the following resources may be helpful:
+
+- [Why HTTPS for Everything?](https://https.cio.gov/everything/) The US government's CIO office has an excellent guide covering HTTPS and why future government sites will all be HTTPS.
+- [Is TLS Fast](https://istlsfastyet.com/) debunks the performance myth associated with HTTPS.
+- [Use TLS](https://smallstep.com/blog/use-tls.html) covers why TLS should be used everywhere; not just for securing typical internet traffic but for securing service communication in both "trusted" and adversarial situations.
+- [Everything you should know about certificates and PKI but are too afraid to ask](https://smallstep.com/blog/everything-pki.html)
+
+[certificate]: ../reference/#certificate
+[certificate_authority]: ../reference/#certificate-authority
+[certificate_key]: ../reference/#certificate-key
+[override_certificate_name]: ../reference/#override-certificate-name
+[principles]: ../docs/#why
+[zero-trust]: ../docs/#why

docs/docs/examples.md

@@ -2,7 +2,7 @@
 sidebarDepth: 3
 ---
 
-# Example Configurations
+# Example configs
 
 A collection of copy-and-paste-able configurations for various types of clouds, use-cases, and deployments. These files can also be found in the git repository in the `docs/docs/examples/` directory.
 
@@ -35,7 +35,7 @@ Uses the [latest pomerium build](https://hub.docker.com/r/pomerium/pomerium) fro
 - Minimal container-based configuration.
 - Docker and Docker-Compose based.
 - Runs a single container for all pomerium services
-- Routes default to on-prem [helloworld], [httpbin].
+- Routes default to on-premise [helloworld], [httpbin].
 
 Customize for your identity provider run `docker-compose up -f basic.docker-compose.yml`
 
@@ -48,7 +48,7 @@ Customize for your identity provider run `docker-compose up -f basic.docker-comp
 - Docker and Docker-Compose based.
 - Uses pre-configured built-in nginx load balancer
 - Runs separate containers for each service
-- Routes default to on-prem [helloworld], and [httpbin].
+- Routes default to on-premise [helloworld], and [httpbin].
 
 Customize for your identity provider run `docker-compose up -f nginx.docker-compose.yml`
 

docs/docs/readme.md

@@ -2,27 +2,46 @@
 
 ## What
 
-Pomerium is an open-source, identity-aware access proxy.
+Pomerium is an identity-aware access proxy. Pomerium can be used to:
+
+- enable secure remote access to internal websites, without a VPN.
+- provide unified authentication ([SSO]) using the [identity provider] of your choice.
+- enforce dynamic access policy based on context, identity, and device state.
+- aggregate access logs and telemetry data.
 
 ## Why
 
-Traditional [perimeter](https://www.redbooks.ibm.com/redpapers/pdfs/redp4397.pdf) [security](https://en.wikipedia.org/wiki/Perimeter_Security) has some shortcomings, namely:
+### Perimeter security's shortcomings
 
-- Insider threat is not well addressed and 28% of breaches are [by internal actors](http://www.documentwereld.nl/files/2018/Verizon-DBIR_2018-Main_report.pdf).
-- Impenetrable fortress in theory falls in practice; multiple entry points (like VPNs), lots of firewall rules, network segmentation creep.
-- Failure to encapsulate a heterogeneous mix of cloud, on-premise, cloud, and multi-cloud environments.
-- User's don't like VPNs.
+For years, secure remote access meant firewalls, network segmentation, and VPNs. However, several [high-profile](https://en.wikipedia.org/wiki/Operation_Aurora) [security](https://krebsonsecurity.com/2014/02/target-hackers-broke-in-via-hvac-company/) breaches have shown the limitations of [perimeter](https://www.redbooks.ibm.com/redpapers/pdfs/redp4397.pdf) [security](https://en.wikipedia.org/wiki/Perimeter_Security), namely:
 
-Pomerium attempts to mitigate these shortcomings by adopting the following principles.
+- Perimeter security does a poor job of addressing the insider-threat and 28% percent of breaches are [by internal actors](http://www.documentwereld.nl/files/2018/Verizon-DBIR_2018-Main_report.pdf).
+- The _impenetrable fortress_ theory of perimeter security is anything but in practice; most corporate networks have multiple entry points, lots of firewall rules, and constant pressure to expand network segmentation boundaries.
+- Even defining "what" a perimeter is is difficult as corporate networks have come to consist of an increasingly [heterogeneous](https://youtu.be/bDJb8WOJYdA?t=532) mix of on-premise, public, and private clouds.
+- VPNs frustrate end-users, give a false sense of security, and often fail to provide defense-in-depth.
 
-- Trust flows from user, device, and context.
-- Network location _does not impart trust_. Treat both internal and external networks as completely untrusted.
-- Act like you are already breached, because your probably are.
+Or for the visually inclined.
+
+![NSA exploiting google's SSL termination](./google-cloud-exploitation620x466.jpg)
+
+> SSL added and removed here :^) - [NSA](https://www.zdnet.com/article/google-the-nsa-and-the-need-for-locking-down-datacenter-traffic/)
+
+### Zero-trust
+
+Pomerium -- and zero-trust more broadly -- attempts to mitigate these shortcomings by adopting principles like:
+
+- Trust flows from identity, device-state, and context; not network location.
+- Treat both internal and external networks as completely untrusted.
+- Act like you are already breached, because you probably are.
 - Every device, user, and application's communication should be authenticated, authorized, and encrypted.
-- Policy should be dynamic, and built from multiple sources.
+- Access policy should be dynamic, and built from multiple sources.
 
 ## Resources
 
+Pomerium was designed around the security model originally articulated by [John Kindervag](http://www.virtualstarmedia.com/downloads/Forrester_zero_trust_DNA.pdf) in 2010, and by Google in 2011 which as a result of the [Operation Aurora](https://en.wikipedia.org/wiki/Operation_Aurora) breach.
+
+Typically this approach to security is called either zero-trust or BeyondCorp-inspired. Here's a curated list of resources covering th
+
 ### Books
 
 - [Zero Trust Networks](http://shop.oreilly.com/product/0636920052265.do) by Gilman and Barth
@@ -51,3 +70,6 @@ Pomerium attempts to mitigate these shortcomings by adopting the following princ
 - [What, Why, and How of Zero Trust Networking](https://youtu.be/eDVHIfVSdIo?list=PLKb9-P1fRHxhSmCy5OaYZ5spcY8v3Pbaf) by Armon Dadgar, Hashicorp
 - [O'Reilly Security 2017 NYC Beyondcorp: Beyond Fortress Security](https://youtu.be/oAvDASLehpY?list=PLKb9-P1fRHxhSmCy5OaYZ5spcY8v3Pbaf) by Neal Muller, Google
 - [Be Ready for BeyondCorp: enterprise identity, perimeters and your application](https://youtu.be/5UiWAlwok1s?list=PLKb9-P1fRHxhSmCy5OaYZ5spcY8v3Pbaf) by Jason Kent
+
+[identity provider]: ../docs/identity-providers.md
+[sso]: https://en.wikipedia.org/wiki/Single_sign-on

docs/docs/signed-headers.md

@@ -8,13 +8,7 @@ description: >-
 
 # Securing your app with signed headers
 
-This page describes how to secure your app with signed headers. When configured, pomerium uses JSON Web Tokens (JWT) to make sure that a request to your app is authorized.
-
-::: warning
-
-Health checks don't include JWT headers and pomerium doesn't handle health checks. If your health check returns access errors, make sure that you have it configured correctly and that your JWT header validation whitelists the health check path.
-
-:::
+This page describes how to add an additional layer of security to your apps with signed headers. When configured, pomerium uses JSON Web Tokens (JWT) to make sure that a given request was handled by pomerium and the request to your app is authorized.
 
 ## Prerequisites
 
@@ -27,9 +21,9 @@ To secure your app with signed headers, you'll need the following:
 
 Signed headers provide **secondary** security in case someone bypasses mTLS and network segmentation. This protects your app from the following kind of risks:
 
-- Pomerium is accidentally disabled;
-- Misconfigured firewalls;
-- Mutually-authenticated TLS;
+- Pomerium is accidentally disabled
+- Misconfigured firewalls
+- Mutually-authenticated TLS
 - Access from within the project.
 
 To properly secure your app, you must use signed headers for all app types.

docs/guide/from-source.md

@@ -5,6 +5,7 @@
 - Install [git](https://git-scm.com/) version control system
 - Install the [go](https://golang.org/doc/install) programming language
 - A configured [identity provider]
+- A [wild-card TLS certificate](../docs/certificates.md)
 
 ## Download
 

docs/guide/helm.md

@@ -10,6 +10,7 @@ This quickstart will show you how to deploy Pomerium with Kubernetes. Though the
 - Install [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
 - Install the [Google Cloud SDK](https://cloud.google.com/kubernetes-engine/docs/quickstart)
 - Install [helm](https://helm.sh/docs/using_helm/)
+- A [wild-card TLS certificate](../docs/certificates.md)
 
 ## Download
 

docs/guide/kubernetes.md

@@ -8,6 +8,7 @@ This quickstart will show you how to deploy Pomerium with Kubernetes. Though the
 - A configured [identity provider]
 - Install [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
 - Install the [Google Cloud SDK](https://cloud.google.com/kubernetes-engine/docs/quickstart)
+- A [wild-card TLS certificate](../docs/certificates.md)
 
 ## Download
 

docs/guide/readme.md

@@ -7,6 +7,7 @@ Docker and docker-compose are tools for defining and running multi-container Doc
 - A configured [identity provider]
 - Install [docker]
 - Install [docker-compose]
+- A [wild-card TLS certificate](../docs/certificates.md)
 
 ## Download
 

docs/guide/synology.md

@@ -16,7 +16,7 @@ Pomerium is lightweight, can easily handle hundreds of concurrent requests, and
 - A [docker-capable] synology product
 - A [Google Cloud Account](https://console.cloud.google.com/)
 - A configured Google OAuth2 [identity provider]
-- A wild-card TLS certificate
+- A [wild-card TLS certificate][certificate documentation]
 
 Though any supported identity provider would work, this guide uses google.
 
@@ -28,7 +28,7 @@ This will vary depending on what type of router you have but the gist is you wan
 
 ## DSM
 
-[Diskstation manager] uses [nginx] under-the-hood to proxy incoming requests. In the following steps, we'll configure DSM to handle incoming requests and certificates. 
+[Diskstation manager] uses [nginx] under-the-hood to proxy incoming requests. In the following steps, we'll configure DSM to handle incoming requests and certificates.
 
 ### Configure DSM's Reverse Proxy
 
@@ -36,7 +36,7 @@ Go to **Control Panel** > **Application Portal** > **Reverse Proxy**.
 
 Click **Create**.
 
-Set the following **Reverse Proxy Rules**. 
+Set the following **Reverse Proxy Rules**.
 
 Field                | Description
 -------------------- | -----------
@@ -56,7 +56,7 @@ This will forward any incoming HTTPS traffic to the Pomerium service that is (no
 
 ### Certificates
 
-Though DSM does support getting [LetsEncrypt] certificates, they do not support wild-card subdomain certificates which require DNS validation. Hopefully you have one handy, or you used the included [script] to get one.
+Though DSM does support getting [LetsEncrypt] certificates, they do not support wild-card subdomain certificates which require DNS validation. If you do not already have a wildcard certificate the [certificate documentation] or included [script] can help you generate one.
 
 Go to **Control Panel** > **Security** > **Certificate**
 
@@ -72,7 +72,6 @@ Services | Certificate
 -------- | -----------------------
 *:8443   | `*.int.nas.example.com`
 
-
 ![Synology assign wildcard certificate](./synology/synology-certifciate-assignment.png)
 
 ## Docker
@@ -173,8 +172,8 @@ OVERRIDE_CERTIFICATE_NAME | `*.int.nas.example.com`
 IDP_CLIENT_SECRET         | Values from setting up your [identity provider]
 IDP_CLIENT_ID             | Values from setting up your [identity provider]
 IDP_PROVIDER              | Values from setting up your [identity provider] (e.g. `google`)
-COOKIE_SECRET             | output of `head -c32 /dev/urandom | base64`
-SHARED_SECRET             | output of `head -c32 /dev/urandom | base64`
+COOKIE_SECRET             | output of `head -c32 /dev/urandom                               | base64`
+SHARED_SECRET             | output of `head -c32 /dev/urandom                               | base64`
 AUTHORIZE_SERVICE_URL     | `https://localhost`
 AUTHENTICATE_SERVICE_URL  | `https://authenticate.int.nas.example.com`
 AUTHENTICATE_INTERNAL_URL | `localhost`
@@ -187,30 +186,29 @@ If properly configured you should see something like the following when you see
 
 ![Synology pomerium all setup](./synology/synology-docker-pomerium-done.png)
 
-If something goes wrong, click the **Logs** tab.  
-
+If something goes wrong, click the **Logs** tab.
 
 ## Try it out
 
-Navigate to your new service. `https://httpbin.int.nas.example.com` 
+Navigate to your new service. `https://httpbin.int.nas.example.com`
 
-You should be redirected to your identity provider. 
+You should be redirected to your identity provider.
 
 ![Synology redirected login](./synology/synology-step-1-redirect.png)
 
-If you've enabled multi-factor authentication you should see that too. 
+If you've enabled multi-factor authentication you should see that too.
 
-![Synology multifactor authentication](./synology/synology-step-2-mfa.png)
+![Synology multi-factor authentication](./synology/synology-step-2-mfa.png)
 
 If that user is authorized to see the httpbin service, you should be redirected back to httpbin!
 
 ![Synology done](./synology/synology-step-3-validate-header.png)
 
-And just to be safe, try logging in from another google account to see what happens. You should be greeted with a `403` unauthorized access page. 
+And just to be safe, try logging in from another google account to see what happens. You should be greeted with a `403` unauthorized access page.
 
 ![Synology done](./synology/synology-step-4-unauthorized.png)
 
-
+[certificate documentation]: ../docs/certificates.md
 [configuration variable docs]: ../docs/config-reference.html
 [diskstation manager]: https://www.synology.com/en-us/dsm
 [docker-capable]: https://www.synology.com/en-us/dsm/packages/Docker

docs/readme.md

@@ -4,5 +4,5 @@ heroImage: logo.svg
 heroText: Pomerium
 tagline: Identity-aware access proxy.
 actionText: Read the docs
-actionLink: /guide/
+actionLink: /docs/
 ---

docs/reference/readme.md

@@ -194,7 +194,7 @@ Authenticate Service URL is the externally accessible URL for the authenticate s
 - Optional
 - Example: `pomerium-authenticate-service.pomerium.svc.cluster.local`
 
-Authenticate Internal Service URL is the internally routed dns name of the authenticate service. This setting is typically used with load balancers that do not gRPC, thus allowying you to specificy an internally routable name. 
+Authenticate Internal Service URL is the internally routed dns name of the authenticate service. This setting is typically used with load balancers that do not gRPC, thus allowing you to specify an internally accessible name. 
 
 ### Authorize Service URL
 
@@ -203,9 +203,9 @@ Authenticate Internal Service URL is the internally routed dns name of the authe
 - Required
 - Example: `https://access.corp.example.com` or `pomerium-authorize-service.pomerium.svc.cluster.local`
 
-Authorize Service URL is the location of the internally routable authorize service. NOTE: Unlike authenticate, authorize has no publically acccessible http handlers so this setting is purely for gRPC communicaiton. 
+Authorize Service URL is the location of the internally accessible authorize service. NOTE: Unlike authenticate, authorize has no publicly accessible http handlers so this setting is purely for gRPC communication. 
 
-If your load balancer does not support gRPC passthrough you'll need to set this value to an internally routable location (`pomerium-authorize-service.pomerium.svc.cluster.local`) instead of an externally routable one (`https://access.corp.example.com`).  
+If your load balancer does not support gRPC pass-through you'll need to set this value to an internally routable location (`pomerium-authorize-service.pomerium.svc.cluster.local`) instead of an externally routable one (`https://access.corp.example.com`).  
 
 ### Override Certificate Name
 

scripts/generate_wildcard_cert.sh

@@ -1,10 +1,24 @@
 #!/bin/bash
-# requires acme.sh see : https://github.com/Neilpang/acme.sh
-# curl https://get.acme.sh | sh
-echo "=> manually issue a wildcard certificate, renewal is up to you!"
+# acme.sh : https://github.com/Neilpang/acme.sh
+#			curl https://get.acme.sh | sh
+# NOTA BENE:
+# if you use a DNS service that supports API access, you may be able to automate
+# this process. See https://github.com/Neilpang/acme.sh/wiki/dnsapi
+
+echo "=> first generate a certificate signing request!"
 $HOME/.acme.sh/acme.sh \
 	--issue \
 	-k ec-256 \
-	-d '*.corp.beyondperimeter.com' \
+	-d '*.corp.example.com' \
+	--dns \
+	--yes-I-know-dns-manual-mode-enough-go-ahead-please
+
+read -p "press anykey once you've updated your TXT entries"
+
+$HOME/.acme.sh/acme.sh \
+	--renew \
+	--ecc \
+	-k ec-256 \
+	-d '*.corp.example.com' \
 	--dns \
 	--yes-I-know-dns-manual-mode-enough-go-ahead-please